Pre-Grace Plugin

Overview

This plugin fires before any Grace Period object is created.

By default, when an invoice is unsettled when its dueTimestamp arrives, a grace period will be created. This grace period will expire after the number of days specified in the gracePeriodDays property set in policy.json, starting from the dueTimestamp of the past due invoice.

The Pre-Grace Plugin allows changing the construction of the grace period in two ways:

• Changing when the grace period expires (and therefore when the policy will lapse if the invoice remains unpaid), and

• Changing the effective timestamp of the lapse when the grace period expires.

For example, in a situation where a grace period is created and would normally expire on January 15, the plugin could change this to expire instead on January 10, and it could make it so that if it does expire, the effective time of the lapse would be January 11.

Configuration

This plugin is configured similarly to other plugins. See the Plugins topic for details. Here is a portion of a product’s policy.json file enabling the plugin:

{
  "plugins": {
    "getPreGraceResult": {
      "path": "main/preGrace.js",
      "enabled": true
  }
}

Plugin Interface

The following object will be sent to the plugin in the data object:

PreGracePluginData

required
defaultGracePeriodDays integer
invoiceLocator string
policy PluginPolicyInfo
tenantTimeZone string

The following response must be returned from the plugin:

PreGracePluginResponse

optional
cancelEffectiveTimestamp timestamp
gracePeriodEndTimestamp timestamp

Both gracePeriodEndTimestamp and cancelEffectiveTimestamp are optional in the response. If gracePeriodEndTimestamp is not specified, the default based on defaultGracePeriodDays. If cancelEffectiveTimestamp is not specified, the effective time of any lapse will be the same as the grace period expiration.

Note

For a grace period object to work as expected, it must have an endTimestamp that is greater than its startTimestamp. You should hold to this when using the pre-grace plugin to manipulate grace period objects.

Example Script

The plugin is invoked with a data payload that contains information about the documents for the policy. Here is a simple example that shows the grace period expiration being accelerated when the delinquency is the result of a payment reversal.

Note

This Zip file contains the required library and associated support files for this example.

require('../lib/arrays.js');
const { DateCalc } = require('../lib/DateCalc.js');

function getPreGraceResult(data)
{
  try
  {
    const policyholder = socotraApi.fetchByLocator(PolicyHolder,
                                                   data.policy.policyholderLocator);

    // Assumes policyholder has a field value called 'state' with
    // two letter state abbreviations
    let state = Object.entries(policyholder.entity.values)
                      .first(e => e[0].endsWith('_state'))[1]
                      .value[0];
    let daysGrace;
    switch (state)
    {
      case 'CA':
        daysGrace = 10;
        break;
      case 'NY':
        daysGrace = 12;
        break;
      case 'TX':
        daysGrace = 7;
        break;
      default:
        return {}; /* Just use the default from policy.json */
    }
    const nowTimestamp = new Date().getTime();
    const dateCalc = new DateCalc(data.tenantTimeZone);
    const newGraceEndTimestamp = dateCalc.addToTimestamp(nowTimestamp,
                                                         daysGrace,
                                                         'days');

    return {
      gracePeriodEndTimestamp: newGraceEndTimestamp,
      cancelEffectiveTimestamp: dateCalc.getEndOfDayTimestamp(newGraceEndTimestamp)
    };
  }
  catch (error)
  {
    console.log(`Error in Pre-Grace Plugin: ${error}`);
    return {};
  }
}
exports.getPreGraceResult = getPreGraceResult;