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

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

Endpoint applications that are locally installed in a UBX user's network can install a toolkit from IBM to pull event notifications from UBX instead of relying on a post from UBX.

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

How UBX users request event data

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

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

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

How UBX event endpoints connect with UBX

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

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

Event syndication as a PUSH or PULL exchange

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

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

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

Event publisher: PUSH

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

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

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 UBX authentication credentials and connection information for the endpoint. PUT /v1/endpointattributes
Register the events that the endpoint publishes to UBX. POST /v1/eventtype
Update attributes for an event type. PUT /v1/eventtype/attributes/publisher/{id}
Publish events from an endpoint to UBX. POST /v1/event
Register a syndication change notification with UBX. 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 UBX.

Event consumer: PUSH

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

Event consumer: PULL

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

UBX supports business cases where UBX receives event data from an event publisher as an uploaded file. Although UBX 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 UBX 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. UBX 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 UBX after you copy its contents.

DELETE /v1/eventfiles/<filename>

Event publication

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

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

UBX 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 UBX, 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 UBX can use to identify the specific individual who initiated the event. The identifier name must be registered with UBX for your endpoint.
  • Timestamp The time when the event occurred, in ISO-8601 format.
  • Event code Identifies a specific event that is recognized by UBX. The events that you specify must be registered with UBX for your endpoint. You must specify an event code that is defined by IBM.
  • Event attributes Details that describe the event. The attributes must be registered with UBX for your endpoint.

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

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.

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

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

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

UBX does not include authentication information in the push message.

UBX indicates where the event occurred

In the event data, UBX 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 UBX interface as the Provider. Example: “IBM”
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.

UBX indicates who performed the event

When it posts event notification data, UBX provides as much information as possible to identify the specific individual who initiated the event. Under identifiers, UBX defines one or more attributes that identify the specific individual who initiated the event. The list of identifiers includes any additional identifiers that UBX 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 UBX 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: jsmith@example.com
isOriginal Optional Boolean

true

false

true: the identifier is provided by the event publisher.

false: the identifier is one that UBX matched to the event.

UBX describes the event

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

Property Included Data Type Valid Value Description
code Required String As registered with UBX 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 UBX 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 UBX toolkit

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

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

For more information about the IBM Universal Behavior Exchange Toolkit, see the IBM Universal Behavior Exchange Toolkit Implementation Guide.


Join The Discussion

Your email address will not be published. Required fields are marked *