Lambda Plugin

Important

If no other plugins are enabled for the tenant, when you first enable the Lambda plugin it could take up to five minutes before the initial lambda script is enabled. Until that point calling the Lambda endpoint will result in an HTTP error. After five minutes the plugin should function normally.

Overview

A typical pattern with Socotra is to create integration code in an external “orchestration” service to control high level processes, and then call the Socotra API for each discrete step. Examples of this pattern include:

  • Calling multiple endpoints to collect data, and aggregating the data within a consolidated calculation

  • Executing multiple steps along the policy lifecycle from create to quote to building

  • Embedding a specialized calculation such as pay-through date or earned premium for easy retrieval

The goal of the Lambda plugin is to make some scenarios such as these substantially easier by providing an intermediate place to host orchestration code. For some cases it eliminates the need to stand up an external system and the complexities that entails.

The general flow is as follows:

  • The client calls the API with a JSON payload that is, in part, dynamic. There’s no predefined structure or object associated with this part of the payload. This payload may include locators that refer to Socotra entities.

  • The request also includes an operation property to be used by the plugin to decide which particular operation to perform, if more than one is supported.

  • The plugin is executed, including whatever entity fetches, table lookups, auxiliary data reads or writes, etc. are needed for the operation.

  • The Plugin is executed and a return object constructed which is sent to the API caller verbatim as the response.

Plugin

The plugin is enabled automatically if it is deployed. Because the Lambda service is not specific to any product, the path and enablement setting are not defined in policy.json as in other plugins. Instead, it should always be deployed to this path:

/scripts/lambda/lambda.js

The signature for the lambda function is:

function executeLambda(operation, payload)

The operation parameter is a string, and the payload is a copy of the object sent into the API.

When the plugin is done, it should return a JavaScript object, which will then be returned to the API caller.

API

The Lambda plugin is invoked by calling the Lambda executor API:

Call the Lambda service and execute the plugin
POST /lambda
LambdaRequest
required
operation string
payload object
LambdaResponse
required
payload object

Example Script

Note

See the Plugin Data Fetch feature guide for details on using the data fetch feature in this example. Also see the ./arrays.js example for the support file.

require("../lib/arrays.js");
function executeLambda(operation, payload) // the payload is entirely constructed by the client
{
  switch (operation)
  {
    case 'is_high_value_policy':
      const policy = socotraApi.fetchByLocator(Policy, payload.policyLocator);
      const activePerilCharacteristics = policy.exposures
                                               .flatMap(ex => ex.perils)
                                               .flatMap(peril => peril.characteristics)
                                               .filter(ch => !ch.replacedTimestamp);

      const prem = activePerilCharacteristics.sum(ch => parseFloat(ch.premium));
      return {
          totalPremium: prem,
          highValuePolicy: prem > 10000
      };
    default:
      throw `Lambda operation ${operation} not supported.`;
  }
}
exports.executeLambda = executeLambda;