Working with the ITAS Events API

Overview

This article covers the scope of the Events API which is primarily used to manage subscriptions to the ITAS Events Engine (Database). This Database is used as a repository for subscriber’s mailboxes which hold messages termed as Alerts and Notifications. The workflow for handling messages is as follows:

The endpoints can be found on the local ITAS server on port 4710 (typically http://your.server.name:4710/Help/Events) 

API Credentials

For all API requests, authentication is applied at message level (request header) using a client key/HMAC combination. The credentials to be applied will be supplied by Hivedome.

Initialisation

Setup a Mailbox (Subscriber) 

This step is required when initialising a mailbox, i.e. establishing a dedicated channel for messages. You can create as many as these as you require although it is suggested you use a single mailbox for middleware-based projects to prevent any potential loss of messages due to multi-threading.  

By establishing a mailbox, you are creating a unique SubscriberID that your middleware will use when communicating with the message queue(s): 

POST EVENTS/REGISTER? SUBSCRIBERNAME={SUBSCRIBERNAME} 

The JSON response will contain the SubscriberID: 

{ 
  "SubscriberId": "3ab1147a-05db-e511-80ec-00155d3d0e65", 
  "Name": "subscriber1", 
  "ServiceResult": null 
}

Subscribe to a Topic 

Once you have your mailbox (identified using the SubscriberID) it will be necessary to subscribe to a Topic which is the name given to the message queue of interest. For example, if notification is required when a Physical Contract is created then the Topic would be “2-220” (a full list of Topics is available on request). 

The following endpoint can be used to subscribe to any Topic (CompanyCode will normally be ‘GF’ for this usage of the Events API): 

POST EVENTS/SUBSCRIBE? SUBSCRIBERID={SUBSCRIBERID}&TOPIC={TOPIC}&COMPANYCODE={COMPANYCODE} 

The following 201 Response would be returned to confirm successful subscription to Topic 2-220: 

{ 
  "SubscriberId": "3ab1147a-05db-e511-80ec-00155d3d0e65", 
  "Topic": "2-220", 
  "CompanyCode": "GF", 
  "ServiceResult": null 
} 

Additional subscriptions can be applied by substituting the relevant Topic. As part of implementation Hivedome will provide a full list of Topic IDs relevant to the interface points identified. As mentioned above, we strongly suggest using a single Subscriber for all Topics as there should be no need to segregate responsibility at this level. Messages will contain all relevant information and apply a standard template. 

To verify subscriptions use the following endpoint: 

GET EVENTS/VIEWSUBSCRIPTIONS? SUBSCRIBERID={SUBSCRIBERID}

Poll for Messages (PEEK) 

Once subscriptions are setup it is then possible to start checking for messages: 

GET EVENTS/PEEK? SUBSCRIBERID={SUBSCRIBERID}&TIMEOUT={TIMEOUT} 

The timeout property is a measurement in seconds of how long the request should wait until receiving a response. It is used as part of the long poll process devised to prevent repeated calls with downtime in between. Instead the call is made by the client and if a message is found it is instantly returned otherwise it will wait for the timeout period. If within that period another message is detected then it can return immediately. It enables a mechanism that will effectively deliver immediately but is still controlled by the consumer/client. 

If no messages are found within the timeout period the 200 Response will be: 

{
  "NextMessageId": null,
  "SubscriberId": "3ab1147a-05db-e511-80ec-00155d3d0e65", 
  "MessageCount": 0,
  "ServiceResult": null 
} 

If messages are found the 200 Response will be similar to this: 

{ 
  "NextMessageId": "a866cd65-0fdb-e511-80ec-00155d3d0e65", 
  "SubscriberId": "3ab1147a-05db-e511-80ec-00155d3d0e65", 
  "MessageCount": 1, 
  "ServiceResult": null 
} 

The NextMessageId holds the unique ID for the next available message.  

NOTE: Messages will always be stored and returned in chronological order as sequence can often play an important role in managing a workflow 

Get Message Content (RECEIVE) 

Once a message is identified it can be Read using the following endpoint: 

POST EVENTS/RECEIVE? SUBSCRIBERID={SUBSCRIBERID}&MESSAGEID={MESSAGEID}&LOCKTIMEOUT={LOCKTIMEOUT} 

NOTE: The locktimeout property is to be deprecated in the next major release as it is no longer required – for now a value of 0 will suffice. 

This step ensures that the content of the message can be read without assuming the message is to be removed from the queue. This is useful where the polling process and the middleware ‘action’ are separated – possibly on different servers – and the ‘action’ cannot be performed immediately. Subsequent requests using the messageid will generate the same response until removed from the queue, although the LockId generated will be unique to each request. 

For this example (notification generated through TRADE -> Image process) the response will be similar to this: 

{
  "MessageId": "a866cd65-0fdb-e511-80ec-00155d3d0e65", 
  "LockId": "31a5d65c-17db-e511-80ec-00155d3d0e65", 
  "Topic": "2-220", 
  "CompanyCode": "GF",
  "MessageType": "{ITASMessage}", 
  "MessageBody": { 
    "TID": "TID-010",
    "TopicId": "2-220”, 
    "audit_trans": "O",
    "InnerBody": {
      "Title": "Contract Created",
      "Message": "Contract created through Image of P00012.000", 
      "TradingEntity": "xx",
      "EntityID": "P00013.000", 
      "EntityTypeID": "1", 
      "EntityType": "contract", 
      "SubmittedBy": "ITASUSER",
      "AdditionalParameters": null
      ...
      } 
    }, 
    "EnqueueTime": "2019-02-01T15:58:13.41", 
    "ServiceResult": null 
} 

The key information here is: 

  • LockId: unique reference for the lock in place for this message receipt request 
  • TID: identifies the message template, i.e. the structure of the InnerBody part of the message 
  • TradingEntity: the ITAS company code  
  • EntityId: the reference/id for the entity or object the notification refers to (in this case a contract) 

As previously discussed the information contained will be specific to the Topic, as will the next action. For example, the workflow here may be to Read the contract details and push a message to another user. 

For the purposes of this article we are simply concerned with handling the notification messages. The assumption here is therefore that the consumer has deserialised the message content and wishes to clear the message from the queue to prevent being picked up again. This involves one further step.

Remove Message (CONFIRM) 

This step serves two purposes: 

  1. Informs ITAS Events Engine (message queue) that the message has been received/read 
  2. Requests that the message be removed 

This process can be triggered using the following endpoint: 

DELETE EVENTS/CONFIRM? SUBSCRIBERID={SUBSCRIBERID}&MESSAGEID={MESSAGEID}&LOCKID={LOCKID} 

As part of the ‘guaranteed delivery’ requirement the confirmation of the message ties in all parts of the message identification picked up through this workflow process: 

  • subscriberId 
  • messageId 
  • lockId 

So without going through each of these steps this information will not available and as such the request to remove the message will not be accepted.  

The request can be made at any time as, again, no assumption is made that message removal request can be made in-time.