Integration Events

Integration Events provide an easy way to ensure that a third party system is kept up to date with changes made to Answers, Calls, Targets and Users in TeamHaven.

Integration Events are exposed through a Microsoft Windows Azure queue. When an update is made, TeamHaven adds a new message containing a JSON representation of an IntegrationEvent instance to the queue. The IntegrationEvent contains information identifying the changed object's type and unique identifier which can in turn be used by the third party system to determine what action should be taken.

Authorisation

Before it can process messages from the event queue, an application must first obtain an authorisation token. A token and all the other necessary connection information can be obtained using the following API call:

GET /api/events/authorisation

This will return a simple JSON object:

{
  Token: '?sv=2014-02-14&si=ThirdPartyAccess&sig=hblA4fGlhx4m%2FOcbeS5vlzHceMv7l78bvClRoTaQHMQ%3D',
  Expires: '2014-05-22T01:41:59.4187326Z',
  QueueName: 'events-1234',
  StorageUri:
  {
    PrimaryUri: 'https://teamhaven.queue.core.windows.net',
    SecondaryUri: 'https://teamhaven-secondary.queue.core.windows.net'
  },
  QueueStorageUri:
  {
    PrimaryUri: 'https://teamhaven.queue.core.windows.net/events-1234',
    SecondaryUri: 'https://teamhaven-secondary.queue.core.windows.net/events-1234'
  }
}

The application can continue to use the token without requesting a new one until the expiry time has passed, at which point the token will cease to operate and a new one must be obtained. It is recommended that the application renews the token at least 5 minutes before it expires avoid any access problems.

Retrieving messages from the queue

We recommend using the Microsoft .NET Azure SDK, but it is also possible to interact with the queue via Microsoft's REST API. For example, to get the next message from the queue (and format the XML output to make it readable):

curl 'https://teamhaven.queue.core.windows.net/events-1/messages?sv=2014-02-14&si=ThirdPartyAccess&sig=X8sxTil1WR3E%2BYTxp3blRAXK%2FoXu5eFu4jwz8a1NX%2BY%3D' | xmllint --format -

Which will return XML:

<?xml version="1.0" encoding="utf-8"?>
<QueueMessagesList>
  <QueueMessage>
    <MessageId>e96d3dc9-4fe5-49f6-b9ac-5feeddc17f81</MessageId>
    <InsertionTime>Wed, 25 Feb 2015 10:06:29 GMT</InsertionTime>
    <ExpirationTime>Wed, 04 Mar 2015 10:06:29 GMT</ExpirationTime>
    <DequeueCount>11</DequeueCount>
    <MessageText>eyJPYmplY3QiOnsiT2JqZWN0VHlwZSI6MTIsIk9iamVjdElEIjo0NzUyNjg4MX0sIlBhcmVudCI6eyJPYmplY3RUeXBlIjo5LCJPYmplY3RJRCI6MzUzM30sIlVzZXIiOnsiVXNlcklEIjo5MTYwNCwiQWNjb3VudElEIjoxfSwiRXZlbnRUeXBlIjo0LCJUaW1lc3RhbXAiOiIyMDE1LTAyLTI1VDEwOjA1OjUwLjg5KzAwOjAwIn0=</MessageText>
  </QueueMessage>
</QueueMessagesList>

The MessageText element contains a base64 encoded JSON string. Decoding it will return an IntegrationEvent instance.

Once a CloudQueue instance has been created, GetMessage can be used to retrieve the next message from the queue. Once a message has been successfully processed, use DeleteMessage to remove it from the queue.

IntegrationEvent instances

The contents of messages in the event queue are JSON UTF-8 strings. The JSON representation of an IntegrationEvent looks like this:

{
  Object: { ObjectType: 12, ObjectID: 12345 }, // The object that was changed
  EventType: 4                                // What kind of change was made
  User: { AccountID: 23, UserID: 45 },        // Who made the change
  Timestamp: '2014-05-22T01:41:59.4187326Z'   // When the change occurred
}

The following ObjectType values may appear:

• 7 Object is a User (Not currently implemented)
• 10 Object is a Project Target (Not currently implemented)
• 12 Object is a Call

The following EventType values may appear:

• 1 Object was created (Not currently implemented)
• 2 Object was updated (Not currently implemented)
• 3 Object was deleted (Not currently implemented)
• 4 Call's Answers were Created or Updated

Example code

Example 2 in the WebAPI GitHub repository shows how to process Integration Events.