Versioned Resource Selection

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.

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.

Note

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.

Note

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.

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.

Note

The selection time basis for invoice documents is limited to currentTime.

API and Entity Structure

ResourceGroupResponse
required
locator locator
name string
selectionStartTime datetime
createdAt datetime
createdBy uuid
retired boolean
resourceNames string[]
ResourceResponse
required
name string
resourceType Enum table | constraintTable | secret | documentTemplate | staticDocument
createdAt datetime
createdBy uuid

optional
lookupTableLocator locator?
staticDocumentLocator locator?
staticName string?
format Enum? text | html | pdf | jpg | jpeg | doc | docx | xls | xlsx | csv | txt | zip
rendering Enum? dynamic | prerendered
scope Enum? transaction | policy | term | segment | invoice
template string?
templateFormat Enum? liquid | velocity
trigger Enum? validated | priced | accepted | issued | underwritten | generated

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 after 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.

Note

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:

// 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");

Note

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

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

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.

Note

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.

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.