Policy Status

Overview

You can easily obtain a policy’s status in Socotra and listen on status updates. Socotra defines the following policy statuses:

Status	Meaning
`pending`	The policy has not yet reached its `startTime`.
`inGap`	The policy’s `startTime` is in the past, and the `endTime` is in the future, but the latest issued transactions have left the segment that covers the current time with a gap segment.
`expired`	The policy’s `endTime` is in the past.
`cancelled`	The transaction stack contains an issued cancellation that has an effective time in the past. It is removed when the policy is reinstated or the cancellation is reversed.
`cancelPending`	The transaction stack contains an issued cancellation that has an effective time in the future. The status is removed when the policy is reinstated, the cancellation is reversed, or the cancellation effective time enters the past.
`onRisk`	The policy is not `pending`, `inGap`, `expired`, or `cancelled`.
`delinquent`	There is an active delinquency. This status is set when delinquency is `inGrace` and unset when the delinquency is in `preGrace`, `settled`, or `lapseTriggered`.
`doNotRenew`	The latest term’s auto-renewal object has `doNotRenew`.

Socotra does not attempt to impose a singular status in cases where a policy can be said to fulfill multiple state conditions. This is why the platform exposes statuses, an array of enumerated values, on PolicyResponse. For example, a policy’s status can be [onRisk, cancelPending].

Note

The inGap status will be implemented in a subsequent release.

Obtaining Policy Status

API

Policy status is provided as statuses on the PolicyResponse returned by endpoints such as Fetch Policy and supplied as inputs to plugins like the precommit plugin.

Event Stream

The event stream includes policy.status.update, which is emitted on any change to policy status. The event body includes newStatuses and removedStatuses to indicate which statuses may have been added and which may have been removed, respectively. Both newStatuses and removedStatuses have ListPageResponsePolicyStatus values:

ListPageResponsePolicyStatus

¶

required
listCompleted boolean
items Enum[] pending | inGap | expired | cancelled | cancelPending | onRisk | delinquent | doNotRenew

For example, when a new on-risk policy is issued, you should expect to see an event like this:

{
    "locator": "...",
    "requestId": "...",
    "userLocator": "...",
    "timestamp": "...",
    "type": "policy.status.update",
    "data": {
        "removedStatuses": {
            "listCompleted": true
        },
        "policyLocator": "...",
        "newStatuses": {
            "listCompleted": true,
            "items": [
                "onRisk"
            ]
        }
    }
}

If you were to then issue a cancellation effective now or in the past, a new event would be emitted:

{
    "locator": "...",
    "requestId": "...",
    "userLocator": "...",
    "timestamp": "...",
    "type": "policy.status.update",
    "data": {
        "removedStatuses": {
            "listCompleted": true,
            "items": [
                "onRisk"
            ]
        },
        "policyLocator": "...",
        "newStatuses": {
            "listCompleted": true,
            "items": [
                "cancelled"
            ]
        }
    }
}

As the event implies, statuses in PolicyResponse would be [cancelled].