# Versioned Resource Selection



Overview [#overview]

Many aspects of your operations will involve processes and information that change over time. The contents of documents, prices, calculations, and other aspects of your processes will evolve. The Versioned Resource Selection feature makes it easier to organize, test, and control these changes so that the correct version of each resource is used based on the data and context of the operation.

This feature controls the selection of these resource types:

* Data Tables
* Dynamic Document Templates
* Static Documents

Each resource declaration corresponds to a set of instances of a specific resource. For example, a table can be defined with a static name (but not data) called `"MyData"`, and then refer to two instances of tables (with data) called `"MyData2023"` and `"MyData2024"`. The job of the Resource Selector is to allow your plugin code to simply ask information from `"MyData"` and have it respond with lookup results from the appropriate instance. When there are many resources that need to be managed as a group this greatly simplifies the logic in your plugins.

<span id="key_concepts" />

Key Concepts [#key-concepts]

These are the key conceptual aspects of versioned resource selection:

* The **SelectionTimeBasis** for a resource is the time property that is used when comparing the time to the availability time for the resource. For example, the criterion for selection in rating operations for a given table could be the `startTime` of the policy, or it could be the current system time. This setting is set in configuration as part of the resource declaration.
* **Resource Declarations** are part of the basic configuration. These include the *static* names for each of the different resources used, along with the `selectionTimeBasis` for those resources.
* **Resources** are instances based on resource declarations. These are created when the data for the resource is first uploaded through the API. For example, when the data for a new table is uploaded, it will be given a `name` and must also specify the `staticName` that ties it to a declaration.
* **Resource Groups** are sets of resources which specify the time that the those resources become available. (The resource becomes available based on the data parameters in the group that contains it.)
* The **Resource Selector** is an object available in plugins that will find the correct resource given only its static name, to simplify plugin logic and abstract away versioning considerations.

<Callout>
  It is possible to add the same resource to more than one resource group. This is most commonly used to prevent redundant instances of data, such as when the same large table might be duplicated several times across multiple groups even though the data is the same. In this case it is more efficient just to add that resource to multiple groups.
</Callout>

<Callout>
  Resource groups can contain resources that have different values for `selectionTimeBasis`. Likewise, resource selectors can manage selection for resources with different values for `selectionTimeBasis`. It is the job of the resource selector to use the appropriate time to determine which resource should be identified for a resource static name.
</Callout>

The Selection Time Basis [#the-selection-time-basis]

Since there is no single "time" associated with a policy, there are different choices for which time is used to decide which resource will be selected. Each resource declaration includes a `selectionTimeBasis` property, and it can have any of these values:

* `termStartTime` (the default for all resource types)
* `policyStartTime`
* `transactionEffectiveTime`
* `currentTime`

For quotes, the `termStartTime`, `policyStartTime`, and `transactionEffectiveTime` are always the same, but these values will vary for policy transactions.

<Callout>
  The selection time basis for invoice documents and delinquencies is limited to `currentTime`.
</Callout>

API and Entity Structure [#api-and-entity-structure]

<ApiSchema name="ResourceGroupResponse" />

<ApiSchema name="ResourceResponse" />

Runtime Behavior in Plugins [#runtime-behavior-in-plugins]

At runtime, for a given resource `staticName`, the system will find the resource with that static name that has the latest `selectionStartTime` on or before the relevant selection time criterion.

Plugins will have access to a *Resource Selector* which will know the relevant `policyStartTime`, `termStartTime`, `segmentStartTime`, and current time, and therefore when the plugin asks the resource selector to retrieve a resource using a `staticName`, it can retrieve the correct instance of the resource using the resource data.

<Callout>
  The protocol for providing the Resource Selector in cases where there is more than one term or segment is still being determined. The `segmentLocator` should be enough for the system to construct it, so it could be that the plugin does something like the following. More details will follow when the protocol is finalized:
</Callout>

```java
// Get the selector...
var theSelector = ResourceSelector.fromSegmentLocator(theSegment.locator);

// and use it to get a table...
var myTable = theSelector.getTable("my_table_static_name");

// or if we can have resource instances defined statically in the development context
// we could do it this way:
var myTable = theSelector.tables
                         .myTableStaticName;

// either way, we can then do lookups:
var someRatingFactor = 100.0 * myTable.lookup("my_key");
```

<Callout>
  For now, tables are the only resource type used in plugins. That may change in future releases.
</Callout>

Document Selection [#document-selection]

Documents, either static or dynamic, have the appropriate resource selected based on the governing term for the transaction that is triggering production of the document, so clients will not have to use the resource selector for documents.

The `transactionEffectiveTime` selection basis is only valid for documents.

Unmanaged Resources [#unmanaged-resources]

Resources that haven't been added to any group are called *unmanaged.* Resources do not have to be added to groups in order to be used in plugins. The resource selector will find resources by `name` if there is no matching resource with the given `staticName`. This is most commonly used for resources that aren't versioned over time.

For this reason, all resource names and all resource declaration static names must be unique in the tenant. Trying to create a resource in the API or update the configuration with a non-unique name will fail with an error.

<Callout>
  Even though unmanaged resources will have a `staticName`, they can't be referenced with this name because there is no date criterion to use for selection. This is true even if there is only one resource with that static name.
</Callout>

Usage Example [#usage-example]

Suppose you need to manage two sets of resources in your operations:

* Several tables and document templates that are selected based on the `startTime` of the policy *term* being processed, updated quarterly; and
* Other document templates that are selected based on the actual time they are rendered, updated annually.

To handle this case, you would create two series of resource groups. The first series would set the `selectionStartTime` to a quarterly cadence, such as `2023-01-01`, `2023-04-01`, ..., and each group would contain the resources (instances) of tables and templates for the quarter. The second series would set the `selectionStartTime` to a series of years, like `2023-01-01`, `2024-01-01`, ...\`\` and contain those template instances that were updated annually.

Then, plugins just ask the resource selector for resources using their static names, without having to worry about any of the versioning behavior.


## API Reference

ResourceGroupResponse
Properties:
  locator (ulid, required)
  name (string, required)
  retired (boolean, required)
  selectionStartTime (datetime, required)
  resourceNames (string[], required)
  createdBy (uuid, required)
  createdAt (datetime, required)

ResourceResponse
Properties:
  name (string, required)
  staticName (string)
  resourceType (Enum constraintTable | customFont | documentTemplate | documentTemplateSnippet | rangeTable | secret | staticDocument | table, required)
  lookupTableLocator (ulid)
  template (string)
  staticDocumentLocator (ulid)
  templateFormat (Enum liquid | velocity)
  createdBy (uuid, required)
  createdAt (datetime, required)
  scope (Enum transaction | policy | term | segment | invoice)
  trigger (Enum validated | priced | accepted | underwritten | issued | generated)
  format (Enum text | html | pdf | jpg | jpeg | doc | docx | xls | xlsx | csv | txt | zip)
  rendering (Enum dynamic | prerendered)
  jurisdictions (string[], required)