Overview

Lifecycle hooks allow you to run custom logic and specify actions to be performed by the platform when certain predefined events in the lifecycle of a policy are triggered.

These lifecycle events include when payments succeed or fail on a policy, when a policy is reactivated, when a claim is approved, and many more touch points. Within these hooks, actions can be queued to execute, such as updating the policy and its module data, changing the policy's status, crediting or debiting the premium ledger of the policy, or triggering a custom notification.

Each lifecycle hook is specified using a corresponding function in the product module code. This allows you not only to link a set of actions to a specific policy event, but also to define complex logic to configure the conditions under which each action should be queued.

Function definition

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

Name - The name of the function determines which policy lifecycle event it will "hook into". The name must match one of the supported lifecycle hooks.
Parameters - Each lifecycle hook accepts a single params object as an argument. The policy object and policyholder object are passed to all lifecycle hooks as properties of params. (Note: this guide refers to the properties of params as the function parameters.) Certain lifecycle hooks also accept additional arguments related to the event that triggered the hook.
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 execute an action or actions, the function must return an array of action objects, which are queued to be executed by the platform. See the full list of actions guide. (The return statement can be omitted if no actions are required, for example if the function only throws an error when certain conditions are met.)

/**
 * Executed after a policy is issued.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy that has been issued.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPolicyIssued = (params) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

Example

The example below uses the afterPolicyIssued hook to define custom logic for whether a policy is activated on issue. If the next policy billing date is within 30 days of the policy issue date, the policy is activated directly after it is issued. Otherwise, the policy will be issued with the default status of pending_initial_payment.

/**
 * Executed after a policy is issued.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy that has been issued.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPolicyIssued = ({ policy, policyholder }) => {
  const now = moment();
  const dayNumber = now.date();
  const billingDay = policy.billing_day;

  let nextBillingDate;
  if (billingDay < dayNumber) {
    nextBillingDate = now.clone().add(1, 'month').date(billingDay);
  } else {
    nextBillingDate = now.clone().date(billingDay);
  }

  // If next billing day is in less than 30 days, activate the policy
  if (!(nextBillingDate.diff(now, 'days') <= 30)) {
    return;
  }
  return [
    {
      name: 'activate_policy',
    },
  ];
};

Policy

These hooks are triggered by policy changes.

After policy issued

This hook is triggered when a policy is issued. Policies are issued via the policy issue endpoint. This endpoint can also be called by frontend users via the Root management dashboard.

/**
 * Executed after a policy is issued.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy that has been issued.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPolicyIssued = ({ policy, policyholder }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After policy not taken up

If not taken up checks are enabled in the general product settings, a policy's status will automatically be changed to not_taken_up if:

no payments have been collected successfully for that policy, and
the period of time since the last failed payment exceeds the specified grace period.

A policy can also be marked as not taken up by returning the mark_policy_not_taken_up action in the product module code.

/**
 * Executed after a policy is marked as `not_taken_up`.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy whose status has changed.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPolicyNotTakenUp = ({ policy, policyholder }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After policy lapsed

A policy lapses according to the lapse rules defined in the general product settings. The policy status will be changed to lapsed if:

at least one payment has been collected successfully since the policy was issued, and
the period of time since the last failed payment exceeds the grace period defined for the policy.

Policies can also be lapsed via the lapse policy endpoint, or by returning the lapse_policy action in the product module code.

/**
 * Executed after a policy is lapsed.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy whose status has changed.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPolicyLapsed = ({ policy, policyholder }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After policy cancelled

Policies are cancelled via the cancel policy endpoint. This changes the policy status to cancelled. A policy cancellation can also be initiated from the Root management dashboard.

/**
 * Executed after a policy is cancelled.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy whose status has changed.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPolicyCancelled = ({ policy, policyholder }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

Before policy reactivated

Reactivating a policy means changing the status of an inactive policy (for example a cancelled or lapsed policy) to active. Reactivation can be enabled or disabled in the general product settings.

If reactivation has been enabled, policies can be reactivated via the reactivate policy endpoint. Reactivation can also be initiated by frontend users from the Root management dashboard.

Since this hook is triggered before the policy status is changed, it can be used to prevent reactivation if certain conditions are not met. This is achieved by throwing an Error from within the function, which will prevent reactivation from being completed.

The function takes both the policy object and the reactivationOption object as parameters. Read more in the reactivation hook guide.

/**
 * Executed before a policy is reactivated.
 * Can be used to prevent reactivation if certain conditions are not met.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy to be reactivated
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy
 * @param {ReactivationOption} params.reactivationOption The reactivation option selected
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform
 */
const beforePolicyReactivated = ({ policy, policyholder, reactivationOption }) => {
  if (<condition under which reactivation should be prevented>) {
  	throw new Error('This policy cannot be reactivated');
  }
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After policy reactivated

This lifecycle hook is analogous to beforePolicyReactivated, except that it is triggered after policy reactivation has been completed.

/**
 * Executed after a policy is reactivated.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy that has been reactivated.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy
 * @param {ReactivationOption} params.reactivationOption The reactivation option selected.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPolicyReactivated = ({ policy, policyholder, reactivationOption }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

Before policy start date changed

The start date of a policy can be changed via the Root management dashboard, if this feature is enabled in the product module settings. Changing the start date of a policy means that the billing history will be recalculated with respect to the new start date.

This hook can be used to cancel the change in start date if certain conditions are not met. This is achieved by throwing an Error from within the function, which will prevent start date change from being implemented.

The function takes both the policy object and the billingChange object as parameters.

/**
 * Executed before a policy's start date is changed.
 * Can be used to prevent the start date change if certain conditions are not met.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy whose to which the start date change will be applied.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {BillingChange} params.billingChange Details of the policy billing changes
 *     resulting from the start date change.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const beforePolicyStartDateChanged = ({ policy, policyholder, billingChange }) => {
  if (<condition under which start date change should be prevented>) {
  	throw new Error(`This policy's start date cannot be changed`);
  }
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

Example of the billingChange object:

{
  "defer_update": false,
  "billing_day": 1,
  "start_date": "2022-01-01T00:00:00.000Z",
  "ledger_adjustments": [
    {
      "policy_id": "0a4c9044-856b-4584-a0d0-5ba97d44d124",
      "organization_id": "00000000-0000-0000-0000-000000000001",
      "environment": "sandbox",
      "amount": -17041,
      "description": "Adjustment for start date change",
      "currency": "ZAR"
    }
  ],
  "current_balance": -998,
  "monthly_premium": 2577
}

The billingChange object has the following properties:

Property	Definition
`start_date`	string. The new start date for the policy.
`billing_day` optional	number. The new billing day for the policy.
`defer_update`	boolean. Specifies whether the new start date will be applied to the policy immediately, or deferred to a later date.
`defer_update_until` optional	string. The date on which the start date change will be applied, if the policy start date is going to be deferred.
`billing_month` optional	number. The new billing day for the policy if it is an annual policy.
`ledger_adjustments`	array. An array of ledger entries that will be added to to policy after the start date changes. Please see the "Ledger adjustments" table.
`current_balance`	number. The current policy balance in cents.
`monthly_premium`	number. The policy monthly premium in cents.

Each object in the ledger_adjustments array has the following properties:

Property	Definition
`policy_id`	string. The UUID of the policy to which the ledger adjustment applies.
`organization_id`	string. The UUID of the organisation under which the policy was issued.
`environment`	string. One of ] { "data": { "h-0".
`amount`	integer. The amount of the ledger adjustment in cents.
`description` optional	string. The reason for the ledger adjustment.
`currency`	string. The three-digit code of the currency in which the policy is billed (e.g. `USD`).
`balance` optional	integer. The resulting balance on the policy ledger, in cents.

After policy start date changed

This lifecycle hook is analogous to beforePolicyStartDateChanged, except that it is triggered after policy start date has been changed. This hook can be used to generate any side-effects, such as making further updates to the policy module data as a result of the start date change.

/**
 * Executed after a policy's start date has changed.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy whose start date has changed.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {BillingChange} params.billingChange Details of the policy billing changes
 *     resulting from the start date change.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPolicyStartDateChanged = ({ policy, policyholder, billingChange }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After alteration package applied

This lifecycle hook is triggered after an alteration package is applied to a policy. To see which properties are included on the alteration package object, go to the API reference for the "Apply alteration package to policy" endpoint and click on the "Success" response.

Read more about how alteration hooks are configured in the alteration hooks guide.

/**
 * Executed an alteration package is applied to a policy.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy whose start date has changed.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformAlterationPackage} params.alteration_package The alteration package that was applied.
 * @param {string} params.alteration_hook_key The key identifying the alteration hook.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterAlterationPackageApplied = ({
  policy,
  policyholder,
  alteration_package,
  alteration_hook_key,
}) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

Payments

These hooks are triggered by payment events, such as a successful payment collection, a payment collection failing, or a previous payment being reversed. Read more about how these payment events are defined in the billing and payments guide (work in progress).

The payment event hooks accept a policy object and a payment object as arguments.

After payment success

A payment is marked with a successful status five days after the payment was submitted, provided that Root has not received a failed payment update from the payments provider within those five days.

/**
 * Executed a payment is marked as `successful`.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy linked to the payment.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformPayment} params.payment The payment that was marked as successful.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPaymentSuccess = ({ policy, policyholder, payment }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After payment failed

A payment is marked with a failed status if Root receives a notification, saying that the payment failed to be collected, from the payments provider within five days of the payment being submitted.

If the failed payment notification is received after five days from the payment submission date, the original payment is still marked as successful. To correct the outstanding balance on the policy, a payment reversal is created to debit the policy's ledger with the original payment amount.

/**
 * Executed a payment is marked as `failed`.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy linked to the payment.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformPayment} params.payment The payment that was marked as failed.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPaymentFailed = ({ policy, policyholder, payment }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After payment reversed

A payment reversal is a completely new, unique payment object that negates a previous payment amount. It will have a payment_type of reversal, and a field called reversal_of_payment_id which stores a reference to the original (reversed) payment. The payment amount on the payment reversal will be negative.

This payment object representing the reversal is passed to the afterPaymentReversed() function, together with the policy object.

/**
 * Executed a new payment is created with a `payment_type` of `reversal`.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy linked to the payment.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformPayment} params.payment The payment reversing a previous payment.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPaymentReversed = ({ policy, policyholder, payment }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

Payment coupons

Payment coupons allow you to credit a policy ledger for scenarios such as reward programs or schedule payment holidays for policies. For more information on creating coupons, have a look at the API.

Before payment coupon created

There is often a need for rules to govern when payment coupons may be created for a policy.

Since this hook is triggered before the payment coupon is created, it can be used to prevent the coupons from being created if certain conditions are not met. This is achieved by throwing an Error from within the function.

The function takes both the policy object and the newPaymentCoupons array of coupons as parameters.

/**
 * Executed before payment coupons are created for a policy.
 * Can be used to prevent the coupons from being created if certain conditions are not met.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy for which the payment coupons are being created.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PaymentCouponInsert[]} params.newPaymentCoupons The payment coupons to be created.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const beforePaymentCouponCreated = ({ policy, policyholder, newPaymentCoupons }) => {
  // Custom logic
  if (<condition under which creating payment coupons should be prevented>) {
  	throw new Error(`Payment coupons cannot be created for this policy`);
  }
  return [ ... ]; // Optional list of actions to queue
}

After payment coupon created

After a payment coupon has been created, the payment coupon is passed to the afterPaymentCouponCancelled function, together with the policy object.

/**
 * Executed after payment coupons are created for a policy.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy for which the payment coupons were created.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformPaymentCoupon[]} params.paymentCoupons The payment coupons that were created.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPaymentCouponCreated = ({ policy, policyholder, paymentCoupons }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After payment coupon cancelled

After a payment coupon has been canceled, the payment coupon is passed to the afterPaymentCouponCancelled function, together with the policy object.

Payment coupons are canceled via the cancel payment coupon endpoint (for a single payment coupon) or the cancel payment coupons endpoint (to cancel all payment coupons on a policy). Payment coupons can also be canceled from the Root management dashboard.

/**
 * Executed after payment coupons are cancelled.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy linked to the payment coupons.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformPaymentCoupon[]} params.paymentCoupons The cancelled payment coupons.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPaymentCouponCancelled = ({ policy, policyholder, paymentCoupons }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After payment coupon redeemed

After a payment coupon has been redeemed, the payment coupon is passed to the afterPaymentCouponRedeemed function, together with the policy object.

/**
 * Executed after payment coupons are redeemed.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy linked to the payment coupons.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformPaymentCoupon[]} params.paymentCoupons The redeemed payment coupons.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPaymentCouponRedeemed = ({ policy, policyholder, paymentCoupons }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After payment coupon reversed

Payment coupons can be reversed, changing their status from redeemed to reversed.

After a payment coupon has been reversed, the payment coupon is passed to the afterPaymentCouponReversed function, together with the policy object.

/**
 * Executed after payment coupons are reversed.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy linked to the payment coupons.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformPaymentCoupon[]} params.paymentCoupons The reversed payment coupons.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPaymentCouponReversed = ({ policy, policyholder, paymentCoupons }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

Claims

These hooks are triggered by events related to claims. Read more about claims and how claims blocks work in the claims guide.

The claim hook functions accept the policy object linked to the claim, and the claim object itself as arguments.

After policy linked to claim

A claim is linked to a policy via the link a policy endpoint.

/**
 * Executed after a policy is linked to a claim.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy linked to the claim.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformClaim} params.claim The claim linked to the policy.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterPolicyLinkedToClaim = ({ policy, policyholder, claim }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After claim block updated

Claim information is stored in claims blocks, and specifically the claim block state. Read more about how claims block states work in the claims guide.

These blocks can be updated either via the update a block state endpoint (for a single block), or the update multiple block states endpoint. Claim blocks can also be updated directly in the user interface on the Root management dashboard.

/**
 * Executed after a claims block is updated.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy linked to the claim.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformClaim} params.claim The updated claim.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterClaimBlockUpdated = ({ policy, policyholder, claim }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

❗️
Avoid infinite loops in claims blocks
The afterClaimBlockUpdated hook is triggered by a change of state of any of the blocks defined in the claim blocks schema. This means an infinite loop can be created unintentionally by updating a claim block state via the API from within the afterClaimBlockUpdated() function.
Updating claim block states from within the afterClaimBlockUpdated() function should be avoided where possible. If this cannot be avoided, you will need to define the logic in the body of the afterClaimBlockUpdated() function carefully to prevent an infinite loop from being created.
You can verify that no infinite loop has been created by checking the Execution Logs under the Product Module inside the Workbench home on the Dashboard. To stop an infinite loop in progress, you can close the claim.

After claim approved

Claims are approved via the approve claim endpoint. Claims can also be approved as part of the claims workflow on the Root management dashboard.

/**
 * Executed after a claim is approved by the claims assessor.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy linked to the claim.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformClaim} params.claim The claim that has been approved.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterClaimApproved = ({ policy, policyholder, claim }) => {
  // Custom logic
  return [ ... ]; // Optional list of actions to queue
}

After claim decision acknowledged

After the claim assessor decision (approve, repudiate, goodwill, no claim), the claim is sent to the claims supervisor for review. If the decision is acknowledged (acknowledge approved, acknowledge repudiated, acknowledge goodwill, or acknowledge no claim) by the claims supervisor, this lifecycle hook is triggered.

To know which decision was acknowledged, you can reference claim.approval_status, which will be one of ["approved", "repudiated", "goodwill", "no_claim"].

/**
 * Executed after a claim decision is acknowledged by the claims supervisor.
 * @param {object} params
 * @param {PlatformPolicy} params.policy The policy linked to the claim.
 * @param {PlatformPolicyholder} params.policyholder The policyholder linked to the policy.
 * @param {PlatformClaim} params.claim The claim for which the decision has been acknowledged.
 * @return {ProductModuleAction[] | void} The actions to be queued by the platform.
 */
const afterClaimDecisionAcknowledged = ({ policy, policyholder, claim }) => {
  if (claim.approval_status === 'approved') {
    // Custom logic
    return [ ... ]; // Optional list of actions to queue
  }
}