Overview

Actions can be returned by lifecycle hooks and scheduled functions in the product module code. If returned, they are added to the Root platform's job queue for execution.

Three categories of actions are currently supported. Actions can be used to make the following changes related to existing policies:

• Change a policy's status - For example, mark an active policy as cancelled.
• Update existing policy data - For example, increase a policy's premium.
• Change the policy balance - For example, reduce a policy's outstanding balance.
• Trigger a custom notification event - For example, trigger a custom email or SMS when a benefit is terminated.

Actions objects are returned inside an array, allowing multiple actions to be returned by the same lifecycle hook or scheduled function.

The action object

The action to be queued is specified using the name property of the action object. The name of the action must match one of the predefined actions listed in this guide.

Actions that update policy data require a second property, the data object. This data will be used to update the existing policy data.

Actions that change the policy balance require three additional properties: the amount by which to change the balance, a description for the ledger entry, and the currency corresponding to the amount.

Example

The example below uses the after payment failed lifecycle hook to define custom logic for handling failed payments. In this example, the sum assured covered under the policy is reduced, and the policy status is changed to not_taken_up. (This example is for illustration only and the logic specifying under which conditions these actions are returned has been omitted).

const afterPaymentFailed = ({ policy, payment }) => {
  // Custom logic omitted
  const actions = [
    {
      name: "update_policy",
      data: {
        sumAssured: policy.sum_assured - 1000,
      },
    },
    { name: "mark_policy_not_taken_up" },
  ];
  return actions;
};

Change policy status

Actions can be queued to change a policy's status to active, lapsed or not_taken_up.

Activate policy

This action changes a policy's status to active (for example if a policy has been lapsed or cancelled). Only the name of the action is required.

{ name: 'activate_policy'}

Lapse policy

This action changes a policy's status to lapsed (for example as part of implementing custom lapse rules for a product). Only the name of the action is required.

{ name: 'lapse_policy' }

Mark policy not taken up

This action changes a policy's status to not_taken_up (for example as part of implementing custom not taken up checks for a product). Only the name of the action is required.

{ name: 'mark_policy_not_taken_up' }

Properties

Update policy data

You can use the update_policy action to update selected standard fields (see the supported data properties section below) on a policy, as well as the module data. The values of these fields are set when the policy is issued via the policy issue hook.

Note: Only the fields that are to be updated on the policy need to be specified in the data object. Any properties not specified will not be changed.

Read more about the standard fields included on all policies in the policy object API reference.

📘

Data object property names are in camelCase

In the update_policy action object, the names of the properties under the data object are specified in camelCase. These properties correspond to snake_case field names on the policy object. For example, sumAssured in the data object corresponds to sum_assured on the policy.

Update standard policy fields

The standard fields that can be updated on the policy are defined within the supported data properties section.

Example

The snippet below represents an update of the policy's sum assured.

{
  name: 'update_policy',
  data: {
    sumAssured: newSumAssured,
  }
}

For a full example of updating the policy premium, see the scheduled functions guide.

Update module data

Changing the module field using this action will replace the entire module object on the policy. We recommend the following approach to update the policy module data:

1. Construct the new module object from the existing policy module object, which is passed to the function as policy.module.
2. Replace the entire module object by returning the updated module object as data.module.

Example

The snippet below shows how the product specific extraction_benefit field can be updated on the module object.

const removeExtractionBenefit = ({ policy }) => {
  const newModule = {
  	...policy.module,
    extraction_benefit: false,
  };
  
  return [
    {
      name: 'update_policy',
      data: {
        module: newModule,
      }
    }
  ];
}

Supported data properties

Top-level properties

Change policy balance

Debit policy

This action creates a new ledger entry debiting the policy. If the policy has an outstanding (negative) balance, this action will increase the outstanding balance in absolute terms. If the policy is in credit (has a positive balance), the balance will be reduced.

{
  name: 'debit_policy',
  amount: 100000,
  description: 'Reactivation penalty',
  currency: 'USD'
}

Credit policy

This action creates a new ledger entry crediting the policy. If the policy has an outstanding (negative) balance, this will reduce the outstanding balance in absolute terms. If the policy is in credit (has a positive balance), this action will increase it.

{
  name:'credit_policy',
  amount: policy.balance,
  description: 'Forgive outstanding policy balance',
  currency: 'USD'
}

Properties

Trigger custom notification event

📘

Actions are executed in the order specified

Actions are executed in the same order as specified in the actions array in the product module code. For example, if you first want to update the policy module data and then trigger a custom notification event, you should include the notification action as the last object in the array.

This action is used to trigger a custom notification event from the product module code.

{
  name: 'trigger_custom_notification_event',
  custom_event_key: 'policyholder_birthday',
  custom_event_type: 'policy',
  policy_id: policy.policy_id,
}

Properties