Events

The event stream presents a chronological feed of activity within Socotra Insurance Suite, designed to enhance operational efficiency and data management practices in your business ecosystem. It is a pivotal feature for use cases like these:

Initiating integrated workflows triggered by key events such as invoice issuance.
Enabling automated routines, such as activating a policy renewal procedure as the expiry date approaches.
Capturing data changes for storage in a specialized database.

Event Stream Usage

The event stream offers:

The ability to fetch a single event.
The ability to fetch all the vents for a single API request.
a paginated view of events in the Socotra system, in ascending chronological order. You may include one or more options in your initial query, such as filter criteria, time range, and page size. You can then use the pagingToken to page through additional results.

Note

The pagingToken cannot be used in conjunction with any other optional arguments.

Payloads

Most Socotra events are kept deliberately sparse. A few have additional data attached, as described below.

Billing

Billing-related events such as delinquency, payment, and invoice generation have a policyLocators property with this value:

ListPageResponseULID

¶

required
listCompleted boolean
items string[]

Relevant policy locators associated with the entity will be included in the items array. If the number of items is five or fewer, the listCompleted property will be true; else, listCompleted: false serves as an indicator to fetch comprehensive data from the API if the full set of policy locators is needed for your use case.

Policy Status

The policy status event includes newStatuses and removedStatuses properties with the following value:

ListPageResponsePolicyStatus

¶

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

See the Policy Status Guide for details.

Custom Events

You may configure custom events to emit from your plugin code.

Configuring Custom Events

Add your event’s definition (CustomEventRef) to the customEvents map in your top-level configuration. Here’s an example of such a definition:

{
    // ...,
    "customEvents": {
        "CustomEventTypeA": {
            "type": "custom.event.type.a"
        }
    },
    // ...,
}

Custom events must have a type beginning with custom., followed by a sequence of .-delimited alphanumeric characters. All custom event type definitions must be unique; else, a deployment error will be thrown.

Emitting Custom Events

In plugin code, use the EventsService.getInstance().createEvent(type, data) call to emit your custom event. The type will be CustomEvent.<YourEventTypeName>; in the example above, for instance, you would reference the event as CustomEvent.CustomEventTypeA.

data must be an JSON-serializable object. A simple approach is to pass a map as data, as in this example:

// ...
EventsService.getInstance().createEvent(CustomEvent.CustomEventTypeA, Map.of("quote", quote.locator(), "info", "plugin called"));
// ...