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 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 is passed 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. Use the following JavaScript function:
socotraApi.fetchByLocator(entityType, locator);
The entityType
is a constant that is automatically injected into the JavaScript context. The locator is the same locator that is used in the main Socotra API.
Note
Because the entityType
is a constant, it should be passed as is, without enclosing in quotes. For example, socotraApi.fetchByLocator(Policy, "10000000");
Important
The data returned from the fetchByLocator
function may differ from what is available in the data
object. For example, on a rating call after an endorsement, the policy has not yet been updated with the endorsement changes. The data
object will reflect these “in-flight” changes, while the fetchByLocator
version will not reflect the changes.
The following entity types are available:
FieldGroup (
map<string, string[]>
)
Table Lookups
To lookup information in a table, use the function:
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
.
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.json
configuration file. For example, the following block will enable the underwriting and proration plugins, other plugins will be disabled:
{
"plugins": {
"getPerilRates": {
"path": "master/rater.js",
"enabled": true
},
"getProrationResult":
{
"path": "master/my_proration_plugin.js",
"enabled": true
},
"createInstallments":
{
"path": "master/installments.js",
"enabled": false
},
"getUnderwritingResult":
{
"path": "master/underwriter.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/master
.
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.