Overview

Atomic Operation Events group together all the actions taken against data objects in AIR from a single API call, which is in contrast to the Account Transaction Events.

These event types cover a much richer quantity of data objects, as detailed below in the Data Objects section of this page.

What are Atomic Operations?

Atomic Operations are the lowest level of operation of the platform for a data object.

Event Notifications described in this page use JSON data format for data interchange and are defined later in this guide.

Event Delivery

Atomic Operation events support a host of different delivery mechanics as detailed in the Event Delivery Methods sub-page. The range of available delivery mechanics for this style of event is much broader than with the Account Transaction Events.

Event Processing

The AIR platform will attempt to deliver an event notification to an external system(s) as soon as possible (almost in
real-time) when an entity is created, amended or deleted. This solution is designed with failover mechanisms in mind to mitigate the risk of losing any event. If the initial attempt to deliver a message fails, the message is retried several times until finally placing the message in a "dead letter" queue. If the depth of this dead queue grows, efforts will be taken to identify the root cause and actions taken where required to deliver the messages.

If the receiving application can not handle the volume of messages being delivered, AIR will respect a 429 response and try the message again to avoid flooding the downstream system.

EagleEye requires message delivery systems to handle messages at the same rate at which the AIR platform is called. Given a 100tps set of API calls which create or change data, AIR will generate the same number of outbound events. To avoid message backlogs, the receiving application should be able to receive the required messages at the same rate.

For webhook event delivery, the receiving system must send back a “200 OK”, "201 Created" or "204 No Content" response status code, which is an acknowledgement when an event is received successfully. If a successful status code is not received back, Eagle Eye will attempt to deliver the message again, a number of times, using exponential back-off.

📘

Response Time

The response to a message should be the acknowledgement of receipt of a message, not that it has been successfully processed, to ensure fast throughput.

It is advised that receiving applications employ a queuing mechanism to ensure delivery and processing are decoupled.

Event Structure

The JSON structure of each event is broken down into the following objects, with an example included.

Headers Object

Request Object

Response Object

Atomic Operations Object

This JSON array contains detailed information what was created, updated or deleted (soft-deleted) within AIR as a result of an API call mentioned above.

Each item in this array contains the following information:

Atomic Operation Types

• CREATE
• UPDATE
• DELETE

Object Types

The following is a list of available entities that could be used as items in the atomicOperations array.

Each entity's structure can be found in the response payloads for each documented API in the reference section of this portal, and further schema details for each are accessible directly from the .yaml files available in the API Specifications guide.

Object Relationships

The relational structure of these object entities is shown below, and this structure should form the foundation of any downstream platform’s schema that consumes the events to replicate the data.

Example

{
  "headers": {
    "unitId": "6082",
    "callerIp": "172.10.0.22",
    "clientId": "TESTWalletClient1",
    "eventDate": "2019-06-11T11:19:09.946511",
    "eventName": "POSCONNECT.ACCOUNT.VERIFY",
    "eesEventId": "425215af-1c81-4c64-8a22-6f6da92882b6",
    "eesApiVersion": null,
    "eesSubsystemId": "hercules.local",
    "eesMasterEventId": "XP@AHRxL7vZ36DQ0exl-HwAAAAI",
    "unitFriendlyName": "Test Wallet Unit",
    "externalMessageId": null,
    "eesEnvironmentType": "local",
    "clientIdFriendlyName": "Test Wallet Unit"
  },
  "request": {
    "body": "{\n    \"walletId\": \"52031\",\n    \"accountId\": \"16612034\"\n}",
    "method": "POST",
    "resource": "/connect/account/verify",
    "contentType": "application/json",
    "customHeaders": []
  },
  "response": {
    "body": "{\"accountTransaction\":{\"accountTransactionId\":\"1887862\",\"parentAccountTransactionId\":\"\",\"accountId\":\"16612034\",\"account\":{\"accountId\":\"16612034\",\"walletId\":\"52031\",\"campaignId\":\"29774\",\"type\":\"ECOUPON\",\"clientType\":null,\"status\":\"ACTIVE\",\"state\":\"BASIC\",\"dates\":{\"start\":\"2019-06-11T11:18:54+01:00\",\"end\":\"2038-01-19T03:14:07+00:00\"},\"meta\":[],\"dateCreated\":\"2019-06-11T11:18:54+01:00\",\"lastUpdated\":\"2019-06-11T11:18:54+01:00\",\"overrides\":{\"offer\":{\"reward\":{\"discountValue\":\"15\"}}},\"balances\":{\"available\":0,\"refundable\":0},\"relationships\":[],\"enriched\":{\"qualifier\":null,\"reward\":{\"offerId\":\"17982\",\"offerName\":\"TestOffer\",\"posReference\":null},\"enrichmentType\":\"COUPON\",\"campaignName\":\"Test Campaign\",\"campaignReference\":\"TESTCampaign1234\"}},\"event\":\"VERIFY\",\"value\":0,\"source\":1,\"balancesBefore\":{\"available\":0,\"refundable\":0},\"balancesAfter\":{\"available\":0,\"refundable\":0},\"transactionDetails\":[],\"properties\":[],\"dateCreated\":\"2019-06-11T11:19:10+01:00\",\"lastUpdated\":\"2019-06-11T11:19:10+01:00\"},\"message\":{}}",
    "code": 200,
    "contentType": "application/json;charset=utf-8"
  },
  "atomicOperations": [
    {
      "objectType": "walletAccountTransactionEntity",
      "objectValue": {
        "event": "VERIFY",
        "value": 0,
        "source": 1,
        "account": {
          "meta": [],
          "type": "ECOUPON",
          "dates": {
            "end": "2038-01-19T03:14:07+00:00",
            "start": "2019-06-11T11:18:54+00:00"
          },
          "state": "BASIC",
          "status": "ACTIVE",
          "balances": {
            "available": 0,
            "refundable": 0
          },
          "walletId": "52031",
          "accountId": "16612034",
          "overrides": {
            "offer": {
              "reward": {
                "discountValue": "15"
              }
            }
          },
          "campaignId": "29774",
          "clientType": null,
          "dateCreated": "2019-06-11T11:18:54+00:00",
          "lastUpdated": "2019-06-11T11:18:54+00:00",
          "relationships": []
        },
        "accountId": "16612034",
        "properties": [],
        "dateCreated": "2019-06-11T11:19:10+00:00",
        "lastUpdated": "2019-06-11T11:19:10+00:00",
        "balancesAfter": {
          "available": 0,
          "refundable": 0
        },
        "balancesBefore": {
          "available": 0,
          "refundable": 0
        },
        "transactionDetails": [],
        "accountTransactionId": "1887862",
        "parentAccountTransactionId": null
      },
      "operationType": "CREATE"
    }
  ]
}

Event Definitions

AIR can trigger Event Notifications as part of a number of the API's endpoints being called. A list of these events is available here.