Overview

Scheduled functions allow you to automate recurring actions to run against existing policies on a time-based schedule. You can configure how frequently the function will run, define custom function logic based on the existing policy data, and select from a predefined set of actions to be added to the platform's job queue.

Each scheduled function is defined as a standalone JavaScript function in the product module code. Each function can be defined to return a list of actions to update policy data, change policy status, and credit or debit the policy balance.

An example would be a monthly function that checks whether a policy is due for an annual premium increase, and returns an action to update the premium if the requirements are met.

You create a scheduled function by completing two steps:

1. Setup - Choose a name for the scheduled function, define the schedule on which it will run, and filter for specific policy statuses.
2. Configuration - Specify the function logic and the actions to be returned in the product module code.

Scheduled functions can also be triggered ad hoc using the trigger policy scheduled function endpoint.

📘

Implementing scheduled functions safely

Scheduled functions are a powerful tool that, by default, will

• run for all policies issued under your product module, and
• continue running indefinitely on your specified schedule (daily, monthly or yearly).

You may need to condition your scheduled function on the existing policy data to ensure that you execute actions for the right policies. For example, you can use a policy's start date to check that the anniversary has been reached before returning an action to update the premium.

We recommend testing scheduled functions in sandbox mode before implementing them for live policies.

Setup

Unlike lifecycle hooks, which are triggered by predefined policy events, scheduled functions are called on a schedule which you can determine.

When creating a scheduled function, you first need to specify the name of the code-function the platform will call in product module code, the time interval at which the function will be run, and for which policy statuses it will be applied.

You can set up a scheduled function for your product module using Workbench. Below is an example of a scheduled function in the root-config.json file.

{
  "configVersion": "2021-05-09",
  "productModuleName": "Shackleton Endurance",
  "productModuleKey": "shackleton_endurance",
  ...
  "scheduledFunctions": [
    {
      "functionName": "applyAnnualIncrease",
      "policyStatuses": [
        "not_taken_up",
        "cancelled",
        "active",
        "lapsed",
        "expired",
        "pending_initial_payment"
      ],
      "frequency": {
        "type": "daily",
        "timeOfDay": "02:00"
      }
    }
  ]
}

Function name

The function name you specify (under the "functionName" parameter) must match the function name in the product module code. For example, if you create a new scheduled function with a name of applyAnnualIncrease, you need to include a corresponding function in your product module code with the same name:

/**
 * Executed on the schedule defined in `.root-config.json`.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy for which the scheduled function is running.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const applyAnnualIncrease = ({ policy, policyholder }) => {
  // Function body
};

Schedule

This scheduled function will recur indefinitely at the interval you specify. The frequency type can be set to any of the following:

-   `daily` -  to run the function at the same time every day
-   `weekly` - to run the function on the same day every week
-   `monthly` - to run the function on the same day every month
-   `yearly` - to run the function on the same day every year

Depending on the frequency type selected, you will also need to specify the following:

• dayOfWeek (for weekly functions)
• dayOfMonth (for monthly and yearly functions)
• monthOfYear (for yearly functions)

Irrespective of the selected frequency, you will also need to specify the time of day the function will run. This is the time at which any actions returned by the function will be added to the platform's job queue. The actual execution of those actions may be delayed by a few minutes.

This can be set at 30 minute intervals for any time during a 24-hour day.

📘

Scheduled function execution time

The time of day is specified as a UTC time. The actual time of execution in your local timezone will depend on your timezone's offset from UTC.

This is the time at which any actions returned by the function will be added to the platform's job queue. The actual execution of those actions may be delayed by a few minutes.

Below is an example of the schedule frequency settings for a yearly scheduled function.

"frequency": {
   "type": "yearly",
   "monthOfYear": "january",
   "dayOfMonth": 13,
   "timeOfDay": "15:30"
 }

Scheduled functions can also be triggered ad hoc using the trigger policy scheduled function endpoint.

Policy statuses

The scheduled function will be applied only to the policy statuses you select. For example, you may want to exclude policies with an expired status from a scheduled function that implements an annual premium increase. Then you would select all policy statuses except expired.

You can select one or more of the policy statuses listed below. The active status is included by default, but can be removed. Note: At least one status must always be selected.

• active
• pending_initial_payment
• not_taken_up
• cancelled
• lapsed
• expired

Configuration

The configuration step involves defining the JavaScript function that will be called by the platform in the product module code. All scheduled functions accept the policy object and the policyholder object as arguments. Note: Both arguments are passed as properties of a single params object.

Function definition

You need to specify the following parts of the lifecycle hook function.

• Name - The name of the function in the product module code must match the name specified in the setup step exactly (case sensitive).
• Body - The body of the function can be used to define custom logic specifying the conditions under which certain actions are returned.
• Return statement - To queue an action or actions to be executed, the function must return an array of action objects. See the full list of actions.

Example

In this example, a scheduled function applyAnnualIncrease is defined to increase the policy's monthly premium by 10%.

/**
 * Executed on the schedule defined in `.root-config.json`.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy for which the scheduled function is running.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const applyAnnualIncrease = ({ policy, policyholder }) => {
  const newPremium = policy.monthly_premium * 1.1;
  return [
    {
      name: 'update_policy',
      data: {
        monthlyPremium: newPremium
      }
    }
  ];
}