Auxiliary Data
Overview
Auxiliary data is a general purpose data store for augmenting the built-in data schema that are defined by Socotra and your configuration.
Use Cases
Many Socotra entities have fieldGroups
and fieldValues
for storing data. For policy data, these are versioned, which is good because when an endorsement or renewal changes policy data, we need a way to see history and also handle out of sequence cases.
However, there is a class of data that doesn’t need to have history stored, and shouldn’t force a major policy transaction just to update it. For example, think of a key to an external CRM system, or a preference such as paper or electronic notifications. These don’t need to be managed in the same way as formal policy data, and they may be updated outside the context of an endorsement or renewal transaction.
Auxiliary data is designed to be a very flexible mechanism that supports these additional needs. For example, you could store information about;
Structure
Most entities within Socotra are identified with a locator
. For example, to fetch a policy you use the fetch policy endpoint with the locator as an argument. Socotra then retrieves the policy that has that locator. This same structure applies to many entities, such as policyholders, claims, sub claims, exposures, perils, premium reports, documents, invoices, payments, characteristics, modifications, and more.
To associate data with any of these entities, just add an auxiliary record using its locator. For example, you could track which day of the month a customer prefers to be invoiced, you could do this:
For policyholder 1234 set the invoice day of month to the value ‘5’:
locator
:1234
key
:invoice_day_of_month
value
:5
There are multiple ways to set this value and then retrieve it, as discussed in the following sections.
Important
Locators do not need to reference any Socotra entity. For example, you could use the locator global
to keep track of information common to all policies and products.
Note
Locators and keys may only include the alphanumeric characters (upper and lower case A
to Z
), numerals 0
to 9
, an underscore _
, a hyphen -
, and the tilde ~
.
Data Types
All values in auxiliary data are set, stored, and returned as strings. However, any datatype can be encoded as a string. For complex data structures, you can encode an object as JSON for storage and retrieval.
UI Hints
Some auxiliary data may be useful or understandable to human users, and others may not. Records may be marked with a uiType
parameter that describes how user interfaces should handle the record:
uiType normal
(default): Display the record in the user interface and allow users to change ituiType readonly
: Display the record but do not allow users to change ituiType hidden
: Don’t display the record at all
Note
The UI type is a hint to the user interface on how to handle that record. It is not enforced by the API. The data type is a string that must have one of the values normal
, readonly
, or hidden
.
API
PUT /auxData/{locator}
Name | Position | Type | Required |
---|---|---|---|
dataSet | body | AuxDataSetCreateRequest | required |
locator | path | string | required |
void
GET /auxData/{locator}/{key}
Name | Position | Type | Required |
---|---|---|---|
key | path | string | required |
locator | path | string | required |
GET /auxData/{locator}
Name | Position | Type | Required |
---|---|---|---|
locator | path | string | required |
page | query | integer | required |
DELETE /auxData/{locator}/{key}
Name | Position | Type | Required |
---|---|---|---|
key | path | string | required |
locator | path | string | required |
void
requiredauxData [AuxDataCreateRequest]
requiredkey stringoptionalvalue stringuiType string normal | hidden | readonly
requiredkeys [AuxDataKeyResponse]page integer
requiredkey stringuiType string normal | hidden | readonly
requiredlocator stringkey stringvalue stringuiType string normal | hidden | readonly
Important
The delete endpoint performs a hard delete. Deleted records will no longer exist and cannot be retrieved by any means.
Note
The value
property for AuxDataResponse is not optional. Therefore, if the value is null
, the property will be returned with value: null
.
Plugin Access
The following methods are available as functions on the socotraApi
object which exists in the context of all plugins:
socotraApi.setAuxData(locator, key, value, uiType = normal);
var data = socotraApi.getAuxData(locator, key); // gets a single value
var keySet = socotraApi.getAuxDataPage(locator, page); // gets keySet
socotraApi.deleteAuxData(locator, key);
A keySet
has the form:
{
"locator": "string",
"auxDataKeys": [
"string"
]
}
In a plugin, if a record is not found on getAuxData(locator, key), it will return undefined
.
KeySets and Paging
If you are not sure whether specific keys exist for a locator, you can fetch a list of keys. Using them, you can then fetch the values for the keys of interest.
When fetching all the keys for a locator, results are returned one “page” at a time. To fetch additional keys, increment the page
argument and do another fetch call. Page numbering starts at zero.
Each page will return 100 keys, though this page size may change without notice.
Document Templates
The following filter is supported in all liquid contexts:
{% assign var_value = "the_locator" | get_aux_data: "the_key" %}
User Interface
Major entities in the system will have an auxiliary data link displayed which will allow viewing and editing auxiliary data in a tabular view.
The Socotra UI will enforce uiType
settings. User interfaces created by others should also enforce this setting.
Null Handling
It is allowed to set a value to be null
. This is different from simply deleting the record. The fetch record endpoint will return an HTTP 404 error if the record doesn’t exist, but if it does exist and is null a null value
will be returned.
A value could be blank (empty string) or null, and the API will respond with either ""
or null accordingly. Multiple spaces are also allowed and distinguished. So, values of ""
, " "
, and " "
are all allowed and distinct.
It is not allowed for a locator or key to be blank or null. Any attempt to set a null key will result in an HTTP 400 error or a JavaScript exception.
Limitations
The following limitations apply to auxiliary data:
Each tenant can accommodate up to 1 billion auxiliary data records
Each record value can be up to 1 megabyte
Locators are limited 64 characters
Keys are limited to 256 characters