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 thestaticName
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
requiredlocator locatorname stringselectionStartTime datetimecreatedAt datetimecreatedBy uuidretired booleanresourceNames string[]
requiredname stringresourceType Enum table | constraintTable | secret | documentTemplate | staticDocumentcreatedAt datetimecreatedBy uuidoptionallookupTableLocator locator?staticDocumentLocator locator?staticName string?format Enum? text | html | pdf | jpg | jpeg | doc | docx | xls | xlsx | csv | txt | ziprendering Enum? dynamic | prerenderedscope Enum? transaction | policy | term | segment | invoicetemplate string?templateFormat Enum? liquid | velocitytrigger 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; andOther 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.