Event Stream

Overview

The event stream is a streaming data source that provides a serialized history of Socotra system events. It is useful for situations like:

  • Triggering integration processes, such as printing and sending an invoice after it is issued

  • Created automated processes, such as a renewal process after a policy nears expiration

  • Capturing data changes for maintaining an external database that includes Socotra data

Note

We recommend waiting at least 5 seconds after receipt of an event to perform follow-up entity fetches by locator, since events are emitted independently of data persistence routines.

See the Event Stream API topic for information about how to implement this feature.

Structure

The event stream is a paged mechanism. Start by querying for events, and then if more records are needed, requery using the pagingToken from the previous response to fetch more records.

Note

For the first call to fetch events, do not include a pagingToken; instead include at least one filter criterion, such as startTimestamp or eventType.

The EventPageResponse will always include a pagingToken. You can use the pagingToken to get additional results for the same query. When making a call using the pagingToken, omit the original filter criteria. The pagingToken lasts forever: even if you reached the end of the result set, you can save the pagingToken to check for more results later.

On each call to the Event Stream, a different pagingToken may be returned.

Attribution

There are two event stream query endpoints: Fetch Events and Fetch Attributed Events. The difference is that the latter endpoint will include the username of the user that initiated the event as part of the EventResponse.

Data Types

The event stream contract is to return objects of type EventResponse, each of which contains an EventStreamData object. Each actual data type returned will be a subtype of EventStreamData depending on what kind of event it is. The type can be identified using the type property on the EventResponse that contains the data.

Event Details

Transaction Effective Events

Transaction Effective Events are available for all major transactions and indicate that the previously issued transaction has come into effect. These events will supplement the existing transaction lifecycle action events create, update, quote, issue and discard. Effective events for back-dated transactions will be emitted at the next scheduled execution of the event trigger job.

  • policy.effective event

  • endorsement.effective event

  • renewal.effective event

  • cancellation.effective event

  • reinstatement.effective event

  • premiumReport.effective event

Policy Termination and Expiration

  • The policy.end event fires only for policies that expire when they reach their policy’s effectiveContractEndTimestamp. It will not fire when policies end due to cancellation.

  • The cancellation.issue event will fire for both manual cancellations and automatic cancellations due to lapse, unless the system is configured to use Legacy Lapsing and Reinstatement. Lapses can be distinguished from manual cancellations using the cancellationName property.

  • If a cancellation is issued for a future effective date, the cancellation.issue event will be fired immediately. cancellation.effective will fire at that future effective date.

  • The policy.end.reminder event will not fire for policies that have been cancelled.

  • The policy.lapse event is a legacy event and is not fired unless using legacy cancellation processes. Use the cancellation.issue event instead.