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}
Retrieve a single auxiliary data record
GET /auxData/{locator}/{key}
    Request:
    NamePositionTypeRequired
    keypathstringrequired
    locatorpathstringrequired
    Response: AuxDataResponse
Fetch a set of auxiliary data record keys
GET /auxData/{locator}
    Request:
    NamePositionTypeRequired
    locatorpathstringrequired
    pagequeryintegerrequired
Delete an auxiliary data record
DELETE /auxData/{locator}/{key}
    Request:
    NamePositionTypeRequired
    keypathstringrequired
    locatorpathstringrequired
    Response: void
AuxDataSetCreateRequest
required
AuxDataCreateRequest
required
key string

optional
value string
uiType string normal | hidden | readonly
AuxDataKeySetResponse
required
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