Change Notifications

Many API's have functionality to create change notifications when there are updates to data. This enables an online notification functionality that other systems can subscribe on when there are changes rather than schedule polling of data. 

Each API documentation shall include information if it supports change notifications. If there are no information regardin notifications/events in an API documentation there are currently no such functionality.

How to get notifications events?

Change notification events can be gotten from the Service Bus topic "api.event.{entityName}" (ex. api.event.customer). In order to actually get the data a subscription to that topic must be created by the Integration team. The access to these subscriptions can be aquired by creating a ServiceNow case assigned to the Integration team.

Once the configuration is done connection strings to the subscription will be sent to the caller of the case and can be used to get changes on an topic.

NB: Once you have a subscription you also have a dead letter queue (error queue) where messages that have failed will be placed. It is the responsibility of the subscriber to handle these errors.

Contract details

The details of the change notifications should be similar. However, some APIs may have specific implementations related to the contracts. This will be described in the relevant API documentation.

The correlation id of an event is included in the Message Custom Properties (Diagnostic-Id). The values of the changed fields is included in the message's custom properties dictionary (UserProperties). Contract information related to the change notification message body is described below in JSON:

{
"sourceSystem": string,
"evenType": int,
"id": string,
"type": string,
"timestamp": string($date-time),
"partitionKey": string,
"onBehalfOf": string
"changedFields": string
}

Change notification message body property descriptions

• sourceSystem - The name of the system that performs the change.
  Example: "CRM"

• evenType - The type of event which triggered the notification
  Possible values: CREATE = 1, UPDATE = 2, DELETE = 3

• id - The id of the changed entity.
  Example: "EC3F119AF3B76F6FC2992BFE576DF220"

• type - The type of the changed entity.
  Example: "customer"

• timestamp - The modified timestamp of the changed entity.
  Example: "2020-10-11T11:25:20"

• partitionKey - The partitionKey of the changed entity.
  Example: "customer.EC3F119AF3B76F6FC2992BFE576DF220"

• onBehalfOf - The name of the system that the source system does the change on behalf of.
  Example: "IFS"

• changedFields - A comma separated list of field names that have been changed as part of an update event.
  Example: "FirstName,LastName,City"