OpenAPI

The event notification service group is dedicated to the support of an enterprise wide event notification mechanism. It currently implements one resource, /ens/v1/activities/ through which a client application can subscribe to information about important events.

The events provided through this system are primarily intended to provide near-realtime updates to a client application or a client enterprise system. This is different from the /trade/messages endpoint which is primarily intended to provide ready formatted feedback to the end user.

Using the Event Notification Service

Starting a subscription

To use the notification service, you setup a subscription to the /ens/v1/activities/subscriptions endpoint. You may specify the following parameters.

Selecting Activities

When setting up the subscription the caller must specify which type of activities or events they want to receive information about. Currently four types of events are supported, the contents of each is described further below.

Selecting FieldGroups

For subscriptions to Orders and Positions, you may specify two field groups, which will be returned in addition to the main message structure.

.

Selecting the scope of the subscription

It is possible to select the scope of the subscription.This is particularly important if the user setting up the subscription is a user of client in the top of a client hierarchy.

Consider the following setup:


In this situation:

A user underWithWill receive events for
8328393 (top house)IncludeSubAccounts, ClientKey and AccountKey undefined

All events for all clients and accounts under this top level client, so:

  • Events related to client 8328393 as well as BlockTrade8393, Demo_8328393 and ERROR_8939, as well as all
  • Events related to clients 8328394, 8328394,8328424 and all of their accounts.
8328393 (top house)IncludeSubAccounts=falseAll events for client 8328393 and that clients accounts: (BlockTrade8393, Demo_8328393 and ERROR_8939)
8328393 (top house)ClientKey=<clientKey for 8328395>All events for client 8328395 and all his/her account(s).
8328395IncludeSubAccounts,ClientKey and AccountKey undefinedAll events under 8328395 and all his/her accounts.

In addition you can use the combination of ClientKey and AccountKey to only only receive events pertaining to a specific single account.

Selecting the starting point of receiving events

If the subscription is started without setting neither a SequenceId, nor a FromDateTime, the first event received, will be the first event occurring after the start of the subscription.

You may request to receive events "back in time", by specifying a FromDateTime or a known existing SequenceId. In this situation you will still not get any data in the "snapshot". Instead you will start receiving these previous messages over the streaming channel. The maximum rate for receiving old messages is capped at 50 msgs/second.

Events in the past

The cache of available past events is a maximum of 3 calendar days in the streaming based subscription and 14 calendar days in the GET ens/v1/activities endpoint.

The purpose is only to allow an application to recover from a situation, where the streaming subscription has been broken, not to provide access to a long term record of all historical events.

Receiving Data

Following a successful subscription, data will start flowing via the streaming channel only. Contrary to most other OpenAPI endpoints, this service does not provide initial data via a snapshot. All events, both past events (if a SequenceId or FromDate has been set) and all current events are delivered via the streaming channel.

Message Formats

Shared Message Properties

All messages have a few shared properties:

Specific Events

Depending of the activity type, additional fields will be available. For detailed information about each event type please refer to:


See also the live sample on ENS (with source) and the live sample on ENS for Corporate Actions (with source)