Event syndication

Through event syndication, activity or interactions that are observed by one Acoustic Exchange endpoint can support responses and initiatives in one or more different endpoints. Endpoint providers enable Exchange users to subscribe to events by registering event types on behalf of the Exchange user accounts and by publishing event notifications as the events occur.

As an endpoint provider, when you register an event, you provide values that identify and describe the event. Exchange uses the name and description that you provide to present the event in the Exchange user interface.

Endpoints that publish event notifications to Exchange do so in a call to a REST API. The call includes values that identify the registered event, indicate when the event occurred, and describe the nature of the event. Depending on the event, the call might also include attributes that can identify the specific individual who initiated the event.

Endpoints that serve as event destinations are responsible for establishing a URL to accept event data the Exchange posts and for creating business processes to consume the event data.

Endpoint applications that are locally installed in an Exchange network can install a toolkit from Exchange to pull event notifications from Exchange instead of relying on a post from Exchange.

Sending event notifications to subscribing endpoints requires a series of actions by endpoint providers and Acoustic Exchange users.

Event syndication typically proceeds in the following sequence.

1. Endpoint provider calls v1/eventtype to register available events. Endpoints must register events separately for Exchange for each Exchange user account.
2. In Exchange, users subscribe to event publishers and specific event types. Endpoint providers can call v1/subscription/notification to be notified of new and changed subscriptions.
3. When a source endpoint observes a specified event, the endpoint calls the v1/event API to notify Exchange.
4. Exchange examines identity data that might be included in the API call to find opportunities to join the new data with existing identifiers that are stored in Exchange.
5. Exchange posts the event to the destination endpoint in an HTTP call to the URL that the endpoint provider specified during endpoint registration. The API call includes any additional identity information that Exchange discovered when it searched identity associations.

How Exchange users request event data

Exchange provides a graphical interface for users to search for appropriate event publishers and events. They can review publisher and event descriptions, and specify individual events to send to one or more destination endpoints.

Exchange gets the details about audiences by making an API call to the URL that was specified when the audience source endpoint was registered.

In Acoustic Exchange, users subscribe to events as follows.

1. Select an event publisher.
2. Examine events types that are available from the publisher.
3. Select one or more event sources.
4. Select one or more destination endpoints to receive event data from the selected source or sources.
5. Start the subscription. When the publishing endpoint detects the selected event, it calls v1/event to send event details to the destination endpoints through Exchange.

How event endpoints connect with Acoustic Exchange

Exchange endpoints connect to and communicate with Exchange through various RESTful APIs. The specific APIs that you call as an event provider or consumer depend on the type of endpoint you create.

You declare an endpoint type as part of the endpoint provisioning and review process when you define the Exchange application on which to base your endpoint. After provisioning your endpoint, you can provide or consume event data through Exchange by implementing various Exchange APIs.

All API requests to Exchange require that the request header include an authorization bearer that is a customer-supplied authentication key. Providing the authentication key verifies that you are calling the API on behalf of a specific Exchange user account.

Event syndication as a PUSH or PULL exchange

Exchange requires that, as an event producer or consumer endpoint, you indicate whether the data exchange occurs as a push to Exchange or the endpoint, or as a pull from Exchange or the endpoint.

The distinction between event sharing as push or pull determines how the Exchange APIs are called or implemented by the endpoint. The choice usually depends on whether the endpoint is a cloud-based (or SaaS) application, or an application that is installed in a physical network behind a firewall. Installed applications are often called On Premise applications.

All Exchange endpoints publish event data to Exchange as a PUSH-type publisher PUSH-type publisher.

An endpoint that receives event data that Exchange sends as soon as it is available is considered a PUSH-type publisher.

An endpoint that receives event data only when it specifically requests the data from Exchange is considered a PULL-type consumer.

As an endpoint provider, you must declare an endpoint type as part of the endpoint provisioning and review process when you use the Integration Manager to define the Exchange application on which to base your endpoint.

Event publisher: PUSH

Exchange provides APIs that can be called by endpoints that produce events.

Event producers are also referred to as event publishers. As part of the endpoint provisioning process, you must identify the endpoint as an event producer and specify the events that you want to publish from the endpoint. Publishing events to Exchange also requires an API call to Exchange.

The following table identifies the actions you perform as an event producer by calling APIs that are hosted by Exchange.

Note: Some endpoints call additional APIs or require additional steps to connect to and communicate with Exchange.

Event consumer: PUSH

Exchange provides APIs that can be called by endpoints that consume events.

Event consumers are also referred to as event subscribers. As part of the endpoint provisioning process, you must identify the endpoint as an event destination.

The following table identifies the typical actions you perform as an event consumer.

Note: Some endpoints call additional APIs or require additional steps to connect to and communicate with Exchange.

Event consumer: PULL

Exchange can temporarily store event data in a file. You can use the v1/eventfiles API to retrieve the file from Exchange.

Exchange supports business cases where Exchange receives event data from an event publisher as an uploaded file. Although Exchange cannot be used as a file repository, it can store the uploaded events file temporarily.

You can make a series of calls to v1/eventfiles to find a file and move its contents to a directory that you maintain. In the series of API calls, you identify the files in Exchange that contain event data, retrieve the contents of a specific file, and then clean up the file store after you receive all of the files. Exchange stores event data in .event files and returns the file contents in the API response as a binary stream.

The following table identifies the series of calls you can make as a Pull-type event consumer.

Event publication

To publish an event to Exchange, make a POST request to the v1/event API. Exchange provides several ways to use v1/event to publish events.

Exchange supports two ways to publish events. You can publish events individually in a single POST to v1/event. You can also publish multiple events as a batch in a single API call.

Publishing events as a batch helps to avoid problems with the use and performance of your network resources. By publishing events in a batch, you can better manage high event volumes and more efficiently deliver events to Exchange over an extended period.

Exchange supports two ways to batch events, depending on the relationship of the events in the batch to each other. The difference between the batching methods determines how you build the JSON payload of the POST request to v1/event. When you publish a batch of events, consider how the events relate to each other, and make the following distinction.

• Simple batch. If the events in the batch are not related to each other in ways that establish dependencies, you can build the JSON payload as a simple set of separate event descriptions, including the identifiers for each event.
• Compound batch. If individual events in the batch are related by a common identifier, build the JSON payload as a list of identifiers and associate the related events under their common identifier. This relationship can occur when a single individual triggers multiple related events during the same interaction with your business solution. Cart events are a common example of such an interaction.

When you publish events in Exchange, either individually or in a batch, the JSON payload contains the following properties.

• Channel The channel specifies where the event was observed. For example, specify mobile for events related to your mobile app.
  - Identifiers The name and value of one or more identifiers that Exchange can use to identify the specific individual who initiated the event. The identifier name must be registered with Exchange for your endpoint.
• Timestamp The time when the event occurred, in ISO-8601 format.
• Event code Identifies a specific event that is recognized by Acoustic Exchange. The events that you specify must be registered with Acoustic Exchange for your endpoint. You must specify an event code that is defined by Exchange.
• Event attributes Details that describe the event. The attributes must be registered with Acoustic Exchange or your endpoint.

You must specify identifiers that are registered with Exchange. To register an identifier, call POST v1/application or PUT v1/endpoint (for custom endpoints).

To describe an event, you must specify an event code and the event attributes that your business solution supports. You must register the event types and attributes with Exchange for your endpoint. To register event types and attributes that you support, call POST v1/eventtype.

• Publishing individual events
  To publish an individual event, make a POST call to the v1/event API. Specify a channel, one or more identifiers, and describe the event.
• Publishing multiple events as a simple batch To publish multiple events in a simple batch, make a POST call to the v1/event API. Structure the request payload as a list of event descriptions that include properties for the event channel, one or more identifiers, and event attributes.
  Publishing multiple related events as a compound batch
  To publish multiple related events, call POST v1/event API. Structure the request payload as a list of identifiers and the events that are related through the identifier.

Publishing individual events

To publish an individual event, make a POST call to the v1/event API. Specify a channel, one or more identifiers, and describe the event.

Publish events individually when you expect interactions with your business solution to occur in relatively low volumes and at random times. The mobile application installation event (application/installed) is an example of an event that happens occasionally and randomly. Individuals register your mobile app one at a time, and they can do so at any time.

You might also consider sending events individually if the event is time critical and any delay to accumulate multiple events might cause a problem. For example, it is likely that you want to publish opt-out requests as soon as possible. To publish an event individually, build the JSON payload in the POST request that defines the channel, an array of identifiers, and a single event description.

Exchange originally introduced event publication as individual events as the only way to publish events. Although the v1/event API now supports sending events in a batch, event publishers do not need to change their existing implementation of v1/event. The v1/event API is fully compatible with existing implementations for sending individual events.

Procedure

Call POST /v1/event.
See POST /v1/event for call details, including an example of how to build the JSON payload.

Publishing multiple events as a simple batch

To publish multiple events in a simple batch, make a POST call to the v1/event API. Structure the request payload as a list of event descriptions that include properties for the event channel, one or more identifiers, and event attributes.

Publish events in a batch when you expect high volumes of events. Processing a large number of events in a single API call helps to avoid delay and network congestion that might occur if you process high event volumes with a series of separate API calls.
You might also want to publish events as a batch to more efficiently process events that occur regularly over time, but are not time critical. Processing as a batch avoids consuming network resources with repeated API calls to Exchange.

To publish a simple batch of events, add the multiple events to the JSON payload as a series of event descriptions. Each event description must define the identifiers that Exchange can use to identify the specific individual who is associated with the event. For example, an email address or cookieId is a typical identifier.

Each event description must also specify the event code that indicates the type of event, a time stamp, and various attributes that describe the event. The event description can also identify the channel in which you detected the event. You can also define the channel at the batch level if all of the events in the batch are observed in the same channel.

Procedure

Call POST /v1/event.
See POST /v1/event for call details, including an example of how to build the JSON payload.

Publishing multiple related events as a compound batch

To publish multiple related events, call POST v1/event API. Structure the request payload as a list of identifiers and the events that are related through the identifier.

Publish events as a compound batch of related events when you can expect multiple events to be initiated by the same individual at or about the same time. Publishing such a group of events enables you to maintain any relationships and dependencies between the events.
The most common example of related events is the cart abandonment event. The act of abandoning a cart generates the following events.

• Cart abandonment – aggregate (ibmcartAbandonment)
• Cart abandonment – item (ibmcartAbandonmentItem)

An abandoned cart establishes a parent-child relationship between the aggregate event and the item events. The abandoned cart might include multiple items, each described by various attributes. Publishing the aggregate and item events as a single batch can make it easier to analyze and report on the separate events as different aspects of the same customer interaction.

To publish events in a compound batch, build the JSON payload in the POST request as a list of one or more identifiers. Associate the related event descriptions with each identifier. Associating multiple related events with a single identifier clearly associates all of the events with the specific individual who initiated them.

The series of identifiers is contained as an array within the top-level eventbatch property. Placing the identifiers under eventbatch makes it possible to list multiple groups of related events.

With each identifier, the related event descriptions must each define the event code that indicates the type of event, a time stamp, and various attributes that describe the specific event. The event description can also identify the channel in which the event occurred. You can define the channel at the batch level if all of the events in the batch occurred in the same channel.

Procedure

Call POST /v1/event.
See POST /v1/event for call details, including an example of how to build the JSON payload.

Event subscription over HTTP

After Exchange receives and evaluates published events, it sends event data in an HTTP POST to endpoints that subscribe to the events. The POST is sent to the URL that the subscribing endpoint provided during endpoint registration.

Summary

Exchange includes the following information in the JSON payload of the push message.

• Name of the event provider.
• Name of the endpoint that published the event.
• The channel where the event occurred.
• The x1Id that is associated with the individual that initiated the event.
• All of the identifiers that are associated with the x1Id.
• The event code.
• A timestamp that indicates when the event occurred.
• Attributes that describe the event.

JSON structure

The JSON payload that Exchange sends to the subscribing endpoint is structured as follows.

The endpoint URL is the URL that was specified in the v1/endpoint API request to register the endpoint.

POST <endpoint URL>/v1/events
{
   “provider” : “<string>”,
   "source" : "<string>",
   “channel” : “<string>”,
   “x1id” : “<string>”,
   “identifiers” : 
   [
      {
      “name” : “<string>”,
      “value” : “<string>”,
      "isOriginal" : <boolean> 
      },
   ],
   “events” : 
   [
      {
      “code” : “<string>”,
      "namespace" : "<string>",
      "version" : "<integer>"
      “timestamp” : “<time>”,
      “attributes” : 
      [
         {
         “name” : “<string>”, 
         “value” : “<value>”, 
         “type” : “<type>” 
         } ,
      ]
      }
   ]
}

Authentication Requirement

Exchange does not include authentication information in the push message.

Exchange indicates where the event occurred

In the event data, Exchange defines properties to identify the event provider, endpoint, and channel that reported the event.

Acoustic Exchange indicates who performed the event

When it posts event notification data, Exchange provides as much information as possible to identify the specific individual who initiated the event. Under identifiers, Exchange defines one or more attributes that identify the specific individual who initiated the event. The list of identifiers includes any additional identifiers that Exchange discovered for the individual and merged into the x1Id record.

Exchange describes the event

Under events, Exchange defines several properties that describe the event and when the event occurred. Under attributes, Exchange provides values that were observed during the event. The attributes are those that are associated with the event when the endpoint provider registered the event with Exchange.

Event subscription with the Exchange toolkit

You can use the Toolkit to download events from Acoustic Exchange. To use the toolkit, you must install it in your local network environment.

When you use the Toolkit to retrieve event notifications from Exchange, the events are downloaded and stored as tab-separated value (TSV) files. You can insert the TSV files into a SQL database using the built-in importer, or by other custom bulk loaders or processes.