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;

Invoicing preferences like the day of month to bill
Keys to external systems like CRM or general ledger
Data needed to generated rating worksheets
Customer notification preferences
Rating factors
Additional context for plugins and documents
Information used in a prequalification process

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 it
uiType readonly: Display the record but do not allow users to change it
uiType 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

Set or update an auxiliary data record set¶

PUT /auxData/{locator}

Request:

Name	Position	Type	Required
dataSet	body	AuxDataSetCreateRequest	required
locator	path	string	required

Response: void

Retrieve a single auxiliary data record¶

GET /auxData/{locator}/{key}

Request:

Name	Position	Type	Required
key	path	string	required
locator	path	string	required

Response: AuxDataResponse

Fetch a set of auxiliary data record keys¶

GET /auxData/{locator}

Request:

Name	Position	Type	Required
locator	path	string	required
page	query	integer	required

Response: AuxDataKeySetResponse

Delete an auxiliary data record¶

DELETE /auxData/{locator}/{key}

Request:

Name	Position	Type	Required
key	path	string	required
locator	path	string	required

Response: void

AuxDataSetCreateRequest¶

required
auxData [AuxDataCreateRequest]

AuxDataCreateRequest¶

required
key string

optional
value string
uiType string normal | hidden | readonly

AuxDataKeySetResponse¶

required
keys [AuxDataKeyResponse]
page integer

AuxDataKeyResponse¶

required
key string
uiType string normal | hidden | readonly

AuxDataResponse¶

required
locator string
key string
value string
uiType 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