Plugins

Plugins are places in Socotra where system behavior can be customized with user-created scripts written in JavaScript.

Note

See the Scripts API topic for information about deploying scripts and retrieving logs from scripts.

The following plugins are currently available:

Script Format

Each plugin is implemented in a JavaScript file with a predefined name. A data object with a predefined format is passed to a function, again with a predefined name, and the response is sent back using the JavaScript return statement. For example, a simple implementation for the underwriting decision plugin can look like this:

// in /main/underwriter.js
function getUnderwritingResult(data)
{
  console.log("Hello underwriting world!");

  return {
    "decision": "accept",
    "notes": [ "Everyone wins!" ]
  };
}
exports.getUnderwritingResult = getUnderwritingResult;

In this example, the file is underwriter.js, the function name is getUnderwritingResult, and the return object has a decision string property and a notes string array property. The exports statement at the end is required.

Script Data

Each plugin receives a data object with information specific to that plugin. See the feature guide for the specific plugin for information about the structure of the data object.

Note

To ensure full precision in passed data, numeric values in the data object are passed as strings. You can use the JavaScript parseInt or parseFloat functions to convert these values to standard JavaScript numeric values as needed.

Fetching Socotra Entities

If the information you need is not contained in the data object passed into a plugin, you can fetch additional data with socotraApi.fetchByLocator:

socotraApi.fetchByLocator(entityType, locator);

See the Plugin Data Fetch feature guide for more details.

Note

Because the entityType is a constant, it should be passed as-is, without enclosing in quotes. For example, socotraApi.fetchByLocator(Policy, '10000000');

Table Lookups

To look up information in a table, use socotraApi.tableLookup:

socotraApi.tableLookup(configVersion, tableName, key)

The table referenced by the tableName parameter must have two columns named key and value. The value returned will be a string but can be converted to other JavaScript types as desired.

Note

Tables are versioned with the Product Versioning feature. The config version for a given policy can be found in the PolicyResponse object. To use the latest version of the table, pass the value 0 for configVersion.

Note

Though the placement of tables in a config might suggest that tables are scoped at the product level, they are actually scoped at the tenant level. We recommend that each table have a unique name to avoid unexpected lookup results. One common technique is to preface each table with the product name.

Script Deployment

Scripts may be uploaded in either of two ways:

Embedded in a configuration deployment. There will be top-level folder in the configuration zip file called /scripts which will contain folders and JavaScript files below.
Uploaded directly to the scripts deployment endpoint with a zip file in multipart form format. With this endpoint, include the structure below what would have gone in the configuration /scripts folder.

Script Enablement

By default scripts are disabled. To enable them, include a ProductScriptingConfig block in your /products/{productName}/policy/policy.json configuration file. For example, the following block will enable all plugins:

{
  "plugins": {
    "getUnderwritingResult":
    {
      "path": "main/underwriter.js",
      "enabled": true
    },
    "getPerilRates": {
      "path": "main/rater.js",
      "enabled": true
    },
    "createInstallments":
    {
      "path": "main/installments.js",
      "enabled": true
    },
    "getProrationResult":
    {
      "path": "main/prorater.js",
      "enabled": true
    },
    "getPostPaymentReversal": {
      "path": "main/postPaymentReversal.js",
      "enabled": true
    },
    "getPostIssuanceResult": {
      "path": "main/postIssuance.js",
      "enabled": true
    },
    "getPreGraceResult": {
      "path": "main/preGrace.js",
      "enabled": true
    }
  }
}

The path, relative to the scripts folder in the configuration, is set with the path parameter for each plugin type. For example, the rater.js file would be located in the folder /scripts/main.

Logging

In a JavaScript plugin script, the JavaScript method console.log can be used to log messages which can be retrieved later.

To retrieve logs, first call the scripts log query endpoint (with a QueryRequest object to filter based on desired values) to retrieve a list of top-level QueryResponseLineItem objects (there will be one per plugin call).

Then, using the specific LogEvent of interest, retrieve individual log messages by calling the scripts logging endpoint again by setting the requestId property of the QueryRequest object.

Note

Top-level logs are generated by Socotra and aren’t based on console.log events in plugin scripts. The format and contents of the message properties of those events is subject to change. Don’t base integration code or automated processes on the structure or contents of those messages.

Log messages may be limited in size to 4096 characters. Longer messages may be split across multiple log messages. Consider using Auxiliary Data to store and retrieve larger diagnostic signals.

Error Handling

You can use the javascript throw expression to throw an exception and prevent the transaction from completing. To provide a human-readable error message in the Socotra UI, you can wrap the string thrown in the tags StartUIerror and EndUIerror. For example, in the following script:

let tableName = 'my_table';
let lookupKey = 'knownMissingRecord';
let lookupVal  = socotraApi.tableLookup(configVersion, tableName, lookupKey);
if(!lookupVal)
  throw `${StartUIerror Plugin Error: No value returned from ${tableName} using lookup key '${lookupKey}'. EndUIerror`;

The user will be shown the error message Plugin Error: No value returned from my_table using lookup key ‘knownMissingRecord’.

If more than one pair of StartUIerror and EndUIerror tags is used, a list of the text enclosed between each pair will be presented to the user.

Reference Implementations

The Socotra Plugin Reference Implementations accelerate plugin adoption with ready-to-use scripts and tests that you can extend as needed.