Scheduled functions

Scheduled functions automate recurring actions on existing policies via time-based triggers. Each function is a standalone JavaScript method that returns an array of actions to update policy data, modify status, or adjust balances.

Prefer instructions. Instructions are the platform's preferred mechanism for future-dated and scheduled functionality. Scheduled functions should only be used in limited instances — at worst one or two daily functions per product module. Before adding a scheduled function, check whether the work can be expressed as pre-created, per-policy instructions; in the vast majority of cases it can.

When a scheduled function is (and isn't) appropriate

Scheduled functions run for all policies issued under your product module (filtered only by status), on every tick, indefinitely. That makes them expensive, coarse-grained, and easy to misuse: most "recurring" business logic is really a set of per-policy events that are known in advance — an anniversary, a renewal date, the end of a grace period — and those should be scheduled as instructions when the triggering event happens, not rediscovered by sweeping the whole book every day.

If you find yourself writing a scheduled function whose body starts by checking each policy's dates or module data to decide whether to act, that is an instruction in disguise — schedule the instruction at the moment the date becomes known instead.

How it works

Implementation is two steps:

1. Setup — name, schedule frequency, and policy status filters in root-config.json
2. Configuration — the JavaScript logic and returned actions in your product module code

Ad hoc triggering is available via a dedicated endpoint.

Setup

Unlike lifecycle hooks, which are triggered by policy events, scheduled functions run on a user-defined schedule.

Function name

The functionName parameter in root-config.json must exactly match the product module code function name (case-sensitive).

Function signature:

const applyAnnualIncrease = ({ policy, policyholder }) => {
  // Function body
};

Parameters: policy (PlatformPolicy object) and policyholder (PlatformPolicyholder object).

Schedule

Frequency types:

• daily – same time every day
• weekly – same day weekly (requires dayOfWeek)
• monthly – same day monthly (requires dayOfMonth)
• yearly – same day annually (requires dayOfMonth, monthOfYear)

Time specification: 30-minute intervals, specified in Coordinated Universal Time (UTC). Actual action execution may be delayed by several minutes.

Example yearly configuration:

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

Policy statuses

Apply the function to selected policy statuses only. Available options:

• active (included by default)
• pending_initial_payment
• not_taken_up
• cancelled
• lapsed
• expired

At least one status must be selected.

Configuration

Function definition

Three required components:

1. Name – matches the setup exactly (case-sensitive)
2. Body – custom logic determining when actions apply
3. Return statement – an array of action objects, or void

Return type: ProductModuleAction[] | void

Example

const applyAnnualIncrease = ({ policy, policyholder }) => {
  const newPremium = policy.monthly_premium * 1.1;
  return [
    {
      name: 'update_policy',
      data: {
        monthlyPremium: newPremium
      }
    }
  ];
}

Note that even this classic example — an annual premium increase — is better modelled as an instruction: schedule a reset/increase instruction for each policy's anniversary at issue time, and it fires once, for that policy, at exactly the right datetime, with no daily sweep across the book.

Related guides

• Instructions — the preferred mechanism for scheduled and future-dated functionality
• Lifecycle hooks — event-driven product module functions
• Product module actions — the full list of actions a function can return