Exchange

Event syndication

Through event syndication, activity or interactions that are observed by one endpoint can support responses and initiatives in one or more different endpoints. Endpoint providers enable users to subscribe to events by registering event types on behalf of the 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. uses the name and description that you provide to present the event in the user interface.

Endpoints that publish event notifications to 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 posts and for creating business processes to consume the event data.

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

Sending event notifications to subscribing endpoints requires a series of actions by endpoint providers and 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 for each user account.
  2. In , 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 .
  4. 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 .
  5. 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 discovered when it searched identity associations.

How users request event data

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.

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

In , 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 .

How event endpoints connect with

endpoints connect to and communicate with 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 application on which to base your endpoint. After provisioning your endpoint, you can provide or consume event data through by implementing various APIs.

All API requests to 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 user account.

Event syndication as a PUSH or PULL exchange

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

The distinction between event sharing as push or pull determines how the 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 endpoints publish event data to as a PUSH-type publisher PUSH-type publisher.

An endpoint that receives event data that 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 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 application on which to base your endpoint.

Event publisher: PUSH

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 also requires an API call to .

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

Action
API

Define a feature and add the event types that you can produce to the feature.

Define the endpoint deployments and onboarding requirements as appropriate for your business solution.

POST /v1/application/{applicationID}/feature

POST /v1/application/{applicationID}/feature/{featureID}/eventtype

Delete an endpoint.

DELETE /v1/endpoint

Give authentication credentials and connection information for the endpoint.

PUT /v1/endpointattributes

Register the events that the endpoint publishes to .

POST /v1/eventtype

Update attributes for an event type.

PUT /v1/eventtype/attributes/publisher/{id}

Publish events from an endpoint to .

POST /v1/event

Register a syndication change notification with .

PUT /v1/subscription/notification

Remove a subscription notification.

DELETE /v1/subscription/notification

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

Event consumer: PUSH

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.

Action
API

Delete an endpoint.

DELETE /v1/endpoint

Update attributes for an event type.

PUT /v1/eventtype/attributes/subscriber/{id}

Register a syndication change notification with .

PUT /v1/subscription/notification

Remove a subscription notification.

DELETE /v1/subscription/notification

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

Event consumer: PULL

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

supports business cases where receives event data from an event publisher as an uploaded file. Although 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 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. 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.

Action
API

Get the names of files that contain event data.

GET /v1/eventfiles

Returns up to 10 file names.

Get the contents of a specific file.

GET /v1/eventfiles/<filename>

Remove an events file from after you copy its contents.

DELETE /v1/eventfiles/<filename>

Event publication

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

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 over an extended period.

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 , 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 can use to identify the specific individual who initiated the event. The identifier name must be registered with 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 .
  • Event attributes Details that describe the event. The attributes must be registered with or your endpoint.

You must specify identifiers that are registered with . 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 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.

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 <base URL>/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 .

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 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 <base URL>/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 <base URL>/v1/event.
See POST /v1/event for call details, including an example of how to build the JSON payload.

Event subscription over HTTP

After 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

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 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

does not include authentication information in the push message.

Exchange indicates where the event occurred

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

Property
Included
Data type
Valid value
Description

provider

Yes

String

Registered provider

The name of the organization that registered the publishing endpoint. The provider name displays in the Acoustic Exchange interface as the Provider. Example: “

source

Yes

String

Registered endpoint

The name of the endpoint that published the event. Example: "Mobile Customer Engagement".

channel

Optional

String

As defined by your business systems.

The method or device that was used to perform the event.

Acoustic Exchange indicates who performed the event

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

Property
Included
Data type
Valid value
Description

x1id

Yes

String

x1id

The x1Id value that Acoustic Exchange assigns to the individual who triggered the event.

name

Yes

String

As defined by your business systems

The name of the identifier. Example: loginID

value

Yes

String

As received

Specific to the individual. Example: [email protected]

isOriginal

Optional

Boolean

true

false

true: the identifier is provided by the event publisher.

false: the identifier is one that Acoustic Exchange matched to the event.

Exchange describes the event

Under events, defines several properties that describe the event and when the event occurred. Under attributes, 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 .

Property
Included
Data type
Valid value
Description

code

Required

String

As registered with Acoustic Exchange

The value that was submitted during event registration. Example: ibmcartPurchase.

namespace

Optional

String

version

Optional

Integer

Integer greater than 0

timestamp

Required

String

Time, in ISO-8601 format.

Example: 2015-02-28T20:16:12Z.

name

Required

String

As registered with Acoustic Exchange

Example: orderTotal.

value

Required

String

As received.

The value that was entered during the event.

Always passed as a string. The subscribing application must be able to recognize and convert the string.

Example: 125.53.

type

Required

String

String

Number

Boolean

Time in ISO-8601 format

The type of data that is provided by the event.

Example: number

Event subscription with the Exchange toolkit

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

When you use the Toolkit to retrieve event notifications from , 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.

Updated 6 months ago


Event syndication


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.