template-cloud-family.php

Watson Commerce

Capitalize on opportunities and trends using the cognitive learning power of Watson

What is Watson Commerce?

Watson Commerce is all about delivering the right customer experience at the right time. Our Developer Centers will help you configure and customize our offerings to deliver these experiences for your customers.

Help your company grab hold of their marketing data using the IBM Universal Behavior Exchange.

Easily connect your marketing technology platforms, understand cross-channel behaviors and personalize engagement.

What is Universal Behavior Exchange?

The UBX ecosystem enables marketers with near real-time customer insights, engagement and the ability to orchestrate automated, personalized marketing strategies across channels in a more unified way. Help your company integrate with UBX today.

Forum

Ask a question
See more forum posts

Events

No Events

Overview

Skill Level: Any

Prerequisites

When you install the UBX Toolkit, configuration settings, including passwords, are visible in properties files. To encrypt certain settings so that sensitive information is not visible, run the encryptconfig script.

The encryption is based on a password-based cryptography standard. By default, the encryption uses a password that is built into the toolkit code. You can further secure the configuration settings by defining a different password. You can define a different password for your environment by defining a custom encryption key.

Defining a custom encryption key is optional. However, you must decide whether to define a custom encryption key before you encrypt the properties settings. If you choose to create a custom encryption key, you must do so before you run the encryptconfig script.

The encryptConfig script is in the bin directory in the folder where you installed the UBX Toolkit files. The script encrypts configuration values in jdbc.properties and config.properties. The script encrypts only values that include the terms: authkey, password, secret, refresh, or access. When you run the encryptConfig script, the script replaces the displayed values for these settings with a string of encrypted characters.

Note: Encrypting configurations with the encryptconfig script does not encrypt the proxy server settings if you encrypt the toolkit configuration settings. However, if the proxy.password property contains a value, the value is encrypted.

 

File Property
jdbc.properties

jdbc.password: Password for the database user.

Note: The password must correlate with the system user who is specified in jdbc.user.

config.properties

ubx.endpoint.authentication.key: The authentication key for registering an endpoint and accessing UBX APIs.

Encrypting the value of a configuration property does not prevent you from changing the value. However, each time that you change the value, you must run encryptConfig again to encrypt the new value.

You can encrypt values in jdbc.properties and config.properties simultaneously or encrypt each file separately.

Step-by-step

  1. Run encryptConfig.bat (Windows) or encryptConfig.sh (UNIX or Linux)

    Depending on your operating system, run encryptConfig.bat (Windows) or encryptConfig.sh (UNIX or Linux).

    • To encrypt jdbc.properties and config.properties simultaneously, run the script as: <CU_HOME>/bin/encryptConfig.
      Example: <CU_HOME>\bin\encryptconfig.bat
    • To encrypt the files separately. Run encryptConfig with the -f parameter as: <CU_HOME>/bin/encryptconfig -f <absolute or relative path to CU_HOME>/conf/<properties file>.
      Example: <CU_HOME>/bin/encryptConfig.sh -f <CU_HOME>/conf/config.properties
      The script encrypts values only in the property file that you specify with the -f option.
  2. Creating a custom UBX Toolkit encryption key

    To apply increased local control over the encryption of sensitive configuration values, you can create a custom encryption key. This task is optional, but does provide an added layer of security.

    When you create a custom encryption key, you change the password that the encryption script uses to hide sensitive configuration values. If you decide to create a custom encryption key, you must perform this procedure before you run the encryptConfig script.

    Define the value for the custom encryption key in a flat file. The file is considered the Encryption Key File and system administrators must restrict access to it. Enter the path to this file as a setting in the setenv file.

    Note: If you change the value of the Encryption Key File, you must remove the current encryption, repeat this procedure to create a new custom encryption key, and run encryptConfig again. If you do not repeat all of the steps in this process, the toolkit scripts will fail.

    Procedure

    1. In a text editor, create a strong password for the encryption script and save the file as a text file. The file that you create is the Encryption Key File. Save the file in a folder outside of the bin directory.

      Restrict access to the directory in which you save the file.

    2. In the bin directory of <CU_HOME>, edit the setenv file to specify the path to the Encryption Key File. Modify the ENCRYPTION_KEY_FILE setting, as follows.

      Windows (setenv.bat): set ENCRYPTION_KEY_FILE="-com.ibm.emm.integration.security.EncryptionKeyFile=<path to file>\<EncryptionKeyFile>"

      UNIX or Linux (setenv.sh): ENCRYPTION_KEY_FILE=-com.ibm.emm.integration.security.EncryptionKeyFile=<path to file>/<EncryptionKeyFile>
      The new custom password is used to encrypt values in jdbc.properties and authentication.key in config.properties.

    3. Run the encryptConfig script to encrypt the configuration settings.
  3. Removing encryption from UBX Toolkit configuration properties

    Some situations require that you remove the encryption from encrypted properties. For example, to change the value for the Encryption Key File, you must remove encryption from all currently encrypted values before you can proceed.

    Encrypted values can be found in jdbc.properties and config.properties. The encrypted values appear as random strings.

    1. In jdbc.properties and config.properties, locate the encrypted values. Replace each encrypted value with its correct unencrypted value.
    2. Save the file.
      On Windows, if you were using a custom encryption key and then stopped using the key, close all command prompts.

    After you complete this task, the configuration values appear without encryption.

Overview

Skill Level: Any

Step-by-step

  1. Modify proxy server settings

    If your corporate data security plans demand separation between your corporate data and the public Internet, you can connect to UBX through a web proxy server. The proxy server must support HTTPS.

    The config.properties configuration file includes optional properties that you must configure if you plan to connect through a web proxy server. To use a web proxy server, you must provide the proxy server address. For authenticated access to the proxy, you must also provide the required user name and password.

    The config.properties file is in the conf directory of <CU_HOME>

    1. In the conf directory, open config.properties in a text editor.
    2. In the Proxy Server Host Settings section, modify the following properties. Comments in the file provide guidance for updating each property.

      proxy.url
      Specify the URL for the web proxy server.

      proxy.username
      Specify the user name that is used to access the web proxy server. Leave blank if authenticated access is not required.

      proxy.password
      Specify the password that is used to access the web proxy server. Leave blank if authenticated access is not required.

    3. Save config.properties and verify the connection.

     

Overview

Skill Level: Any

Prerequisites

Use the UBX Toolkit to make audience data generated in a locally installed application available for syndication by UBX users. The process involves updating toolkit configurations, generating or updating audience data in the source application, and running scripts to identify and upload the audience data to UBX.

Using the UBX Toolkit to make audience data available in UBX involves the following steps.

  • Create an audience file in the audience producer application. Create the file as a CSV file.
  • Register the CSV file as an available audience in UBX. Run audienceRegister.bat/sh as a scheduled job.
  • Upload the available audience to UBX so that UBX users can share the data with a destination endpoint. Run the audienceUpload.bat/sh script as a scheduled job.

Step-by-step

  1. Registering audience data with UBX

    Registering an audience with UBX enables the UBX Toolkit to recognize changes in the audience data that is available from the audience source. Run the audienceRegister script to register the description of the audience with UBX.

    A. During routine business operations, marketers update existing audiences and create new audiences. The audience data must be saved in a CSV file and saved in a specific directory that is identified in the toolkit configuration properties. Specify the folder with the ubx.audience.producer.audiencePublishFolder property in config.properties.

    B. Run the audienceRegister script to examine the directory that you have reserved for audience data. The script looks for new CSV files. The audienceRegister script ignores files that do not follow the required naming convention. If you do not save audience data to this directory as UBXSegment_<AudienceName>.csv, the UBX Toolkit does not upload the new audience data to UBX. Run the audienceRegister as a scheduled job so that you can regularly monitor the audience source directory for new audience data. Doing so helps to ensure that you are working with the most current data available.

    The script scans the folder that is reserved for published CSV files to determine if new CSV files are present. If a CSV file with the name format in UBXSegment_< AudienceName>.csv is found, the script parses the file name to get the audience name. It reads the first line of the CSV file and uses the column headers as the audience attributes.

    C. The script checks the audience name against the list of current audiences in UBX. The script calls GET /v1/endpoint?segment=true&source=true&loadSegments=true&endpointId={endpointid} to get a list of existing audiences for the endpoint. If the audience name matches an existing audience name, it updates the audience. Otherwise, the audienceRegister script creates a new audience.

    D. After the script processes all CSV files, it calls the UBX API to update or add the audiences. The API call must specify the endpoint ID of the endpoint that acts as the source of the audience data.

    • To update audiences, the script calls PUT /v1/endpoint/{endpointid}/segments
    • To register a new audience, the script calls POST /v1/endpoint/{endpointid}/segments

    After it completes the API calls, the script creates the published folder as a sub-folder to the directory for audience data that you specified with the ubx.audience.producer.audiencePublishFolder configuration property. The script moves the processed CSV files to the published folder.

     

    The script examines CSV files that have been added or updated in the folder that you specify with the ubx.audience.producer.audiencePublishFolder configuration property.

    Procedure

    Run %CU_HOME%\bin\audienceRegister.bat as a scheduled job. For Linux or UNIX, run %CU_HOME%/bin/audienceRegister.sh.

    Optional parameter

    -c <custom config filepath> Specify this path if you did not install the bin directory in the default installation location.

    The script creates the published folder as a sub-folder to the directory for audience data that you specified with the ubx.audience.producer.audiencePublishFolder configuration property. The script moves the processed CSV files to the published folder.

    UBX users must request an audience through the UBX user interface. Upon receipt of the user request, UBX begins the process that is required to share the audience data between the source and destination endpoints.

  2. Audience sharing by UBX users

    UBX users make selections in the UBX user interface to initiate the actual exchange of audience data between an audience source endpoint and an audience destination endpoint. The process is called audience sharing.

    UBX users select audiences in the UBX user interface and indicate when they want the data to be sent from the source to the destination. They can request that the audience source endpoint send the data immediately, at a future time, or on a recurring basis.

    When a UBX user requests audience data from your endpoint, UBX creates a job to provide the data through UBX to the destination that the user specifies. New and updated audiences appear in UBX as Waiting for data.

    To ensure that the latest audience data is displayed and made available when UBX users request it, you must schedule the audience upload script to run repeatedly to make API calls to UBX to detect when UBX has created an audience upload job.

  3. Upload audience data to UBX

    As an audience source endpoint, run the audience upload script repeatedly to respond to audience sharing requests from UBX users and to get the corresponding audience upload job that is waiting for audience data from you.

    When UBX users share an audience through the Audiences tab in the UBX user interface, UBX creates the job that it will use to receive the data from the source endpoint. As the audience source endpoint, you must make API calls to UBX to determine when such jobs have been created. Since users can request that audience source share audience data immediately, good practice demands that you schedule the audience upload script to make the API calls frequently, to avoid delays in responding to the user requests.

     

    A. The audienceUpload script calls GET /v1/jobs/SEGMENT_EXPORT?endpointId={endpointId}&status={status} with the status set to WAITING_TO_RECIEVE_DATA to get a list of jobs that are available to receive uploaded audience data.

    B. If a job is returned, the segment upload script uses the audience name to locate the CSV file that provides the audience data. If the required CSV file exists, the script calls POST /v1/jobs/{jobid}/data to upload data to the job.

    If the CSV file does not exist, the script reports an error and tries again on the next round. The script ignores the job if the CSV file is still not found after the period of time that you specify in the ubx.audience.producer.jobWaitingForDataTimeoutInMinutes configuration property.

    Run the audienceUpload script as a scheduled job to make audience data available to UBX users for download to an audience destination endpoint.

    Procedure

    1. Specify timeout for missing audience data. Enter a value, in minutes, for the following configuration property in config.properties.ubx.audience.producer.jobWaitingForDataTimeoutInMinutes
      Default: 1440 minutes (24 hours)
    2. Run %CU_HOME%\bin\audienceUpload.bat as a scheduled job. For Linux or UNIX, run %CU_HOME%/bin/audienceUpload.sh.

      Optional parameter
      -c <alternate config.properties> Use this option to define alternate configurations. When you specify this option, properties in the alternate configuration file override the toolkit default configuration. Specify the path to the alternate location and file name. Do not rename the default properties file.

    The UBX scheduler creates a job to export the audience. On the Audiences tab in UBX, users can see the job listed as Waiting for data.

    The audience data is uploaded to the destination endpoint through UBX, where UBX users can use the data for various analytical and retargeting activities.

  4. Archiving the local copy of the audience data after upload

    After the upload script finishes, the UBX Toolkit can either move the CSV file to a new location or leave it in place for possible reuse.

    The UBX Toolkit creates the Published folder and the Delivered folder to store the CSV files that are created to provide audience data for upload to UBX.

    By default, after it uploads the audience data to UBX, the UBX Toolkit moves the CSV file to the Delivered folder. However, you can change a configuration setting to keep the CSV file in the Published folder.

    Procedure
    In configuration.properties, indicate where to locate the CSV file after uploading data to UBX by setting the following property.

    • To move the CSV file that defines the audience data to the Delivered folder, set ubx.audience.producer.moveFileToDeliveredFolder to true. This is the default behavior.

      The script calls DELETE /v1/endpoint/{endpointid}/segments/{segmented} to delete the audience data after copying the CSV file to the Delivered folder.

    • To keep the CSV file in the Published folder and available for reuse, set the property value to false.

      Keeping the CSV file in the Published folder allows you to reuse the audience data.

Overview

Skill Level: Any

Prerequisites

Using the UBX Toolkit to download audience data from UBX involves download available audience data from UBX to a locally installed application. UBX users request the audience download in the UBX user interface. Upon receipt of the request, UBX creates the audience download job. Run the audienceDownload.bat/sh script repeatedly as a scheduled task to detect new download jobs as UBX creates them. You can also run the script manually.

When UBX users share an audience through the Audiences tab in the UBX user interface, UBX creates the job that it will use to receive the data from the source endpoint. As the audience destination endpoint, you make API calls to UBX to determine when such jobs have been created. Since users can request that audience source share audience data immediately, good practice demands that you schedule the audience upload script to make the API calls frequently, to avoid delays in responding to the user requests.

The following diagram illustrates the overall workflow for using the UBX Toolkit to pull audience data down from UBX.

 

A. To determine if audience download jobs exist, run the audienceDownload.bat/sh script as a scheduled job. The script calls GET /v1/jobs/SEGMENT_EXPORT?endpointId={endpointId}&status={status} with the status, READY_FOR_DOWNLOAD, to get a list of jobs that have new audience data available.

B. If a job is ready to download audience data, the audience download script calls GET /v1/jobs/{jobid}/segmentDataFiles/{filepath} to download the data.

C. The script stores the data as a CSV file in a specified local directory. Specify the directory as a configuration property. The script creates the CSV file with the name format: <Audience name>.csv.

When the download finishes, the download script calls PUT /v1/jobs/{jobid}/status/{status} with the job status: COMPLETE.

Step-by-step

  1. Downloading audience data from UBX

    Run the audienceDownload script as a scheduled job to make audience data available to UBX users for download to an audience destination endpoint. Audience downloads happen only in response to requests from UBX users in the UBX user interface.

    1. Indicate whether or not to archive previously downloaded audience data before downloading the new data. Indicate your choice as the value for the following configuration property in config.properties.

      ubx.audience.consumer.archiveDownloadedAudiences=true|false

      Default: true

      When true, UBX saves any previously downloaded data files to a folder named archive as a sub-folder to the folder that you specified with the ubx.audience.consumer.audienceDownloadFolder configuration property. To establish a unique file name for the archived audience, the UBX Toolkit adds the current timestamp to the original audience file name.

    2. Run %CU_HOME%\bin\audienceDownload.bat as a scheduled job. For Linux or UNIX, run %CU_HOME%/bin/audienceDownload.sh

      Optional parameter

      -c <alternate config.properties> Use this option to define alternate configurations. When you specify this option, properties in the alternate configuration file override the toolkit default configuration. Specify the path to the alternate location and file name. Do not rename the default properties file.

Overview

Skill Level: Any

Prerequisites

To use the UBX Toolkit to download event data from UBX, update certain toolkit configurations and run various scripts in the bin folder of the UBX Toolkit installation. Some scripts run as scheduled jobs.

Event destination endpoints are also called event subscribers or event consumers. Run the UBX Toolkit eventsDownload and eventsImport  scripts to perform the following tasks.

  • Download event data from UBX
  • Import event data into a specified local database

The scripts call UBX public APIs. Before you begin, contact IBM to verify the URL that IBM assigned to your UBX account for submitting API calls.

The UBX Toolkit provides an example mapping file that you can use to specify how to add downloaded event data into a local database. Modify the mapping file as necessary to match your local tables. Adding the event data to a local table makes it available for analysis and contact retargeting.

Step-by-step

  1. Downloading events from UBX

    The UBX Toolkit provides the eventsDownload script to download event data from UBX to a to a file in your local environment. You can run the script manually or as a scheduled job.

    Log in to UBX to confirm that you have configured an event subscription to the destination endpoint.

    The eventsDownload script calls the v1/eventfiles API to download the events files. Calling the API initiates a secure file download. The event data is downloaded in JSON format to the directory that you specify in the lzocal.download.dir property in config.properties.

    The UBX Toolkit transforms the downloaded JSON object into a TSV file.

    The default local download directory is $CU_HOME/AppData/eventsDownload, but it can be customized in the config.properties file.

    1. In the conf directory, verify the following settings in the config.properties file.
      • ubx.api.service.url=http://<server-name>:<port>. The service URL for UBX public APIs. The path must include the server and port that IBM assigns to your UBX account.
      • ubx.endpoint.eventfiles.numFilesInList=<number> The number of files in the list returned when the eventfiles API is called.
      • local.download.dir=%CU_HOME%/AppData/eventsDownload. The directory where the downloaded files are saved.
      • dbinsert.keep.processed.files=true.¬†If set to true, after event import, the TSV file are moved to the dataProcessed directory. If set to False, after import, the TSV file is deleted and the JSON is not moved.
    2. From the %CU_HOME%/bin folder, run eventsDownload.bat [-c <config properties file>] or eventsDownload.sh [-c <config properties file>] By default, UBX downloads the event data to %CU_HOME%/AppData/eventsDownload.

      Use the ‚Äďc option to define alternate configurations. When you specify this option, properties in the alternate configuration file override the toolkit default configuration. Specify the path to the alternate location and file name. Do not rename the default properties file.

    The UBX toolkit downloads event data from UBX in JSON format. When the event data has finished downloading, the eventsDownload script converts JSON objects to TSV format.

    After the eventsDownload script finishes downloading the event data, the event files are deleted from the UBX server.

    UBX event types

    IBM defines several types of recognized events and organizes them into classes that are based loosely on the channel in which the events are observed.

    IBM also recognizes custom events that are defined by IBM Business Partners, but only after consultation and agreement on the event name, event code, and support for event attributes. Such consultation helps ensure that UBX can correctly recognize and process the data that the custom event promises to deliver.

    For more information about UBX event types, see UBX event type directory and Dynamic Event Library

     

    JSON format for download event data
     
    The UBX events are serialized JSON objects in the downloaded files. Each file can contain data for multiple events.

    The UBX Toolkit downloads event data in the following JSON format.

    {
    "provider" : "<string>",
    "source" : "<string>",
    "channel" : "<string>",
    "x1id" : "<string>",
    "identifiers" :
    [
    { "name" : "<string>","value" : "<string>" },
    { "name" : "<string>","value" : "<string>" }
    ],
    "events" :
    [
    {
    "code" : "<string>",
    "timestamp" : "<timestamp>",
    "attributes" :
    [
    {"name" : "<string>", "value" : "<value>", "type" : "<type>" } ,
    {"name" : "<string>", "value" : "<value>", "type" : "<type>" }
    ] }
    ]
    }

     

    After it downloads the event data, the eventsDownload script transforms the JSON object into a TSV file.

    The first line in the TSV file contains the header names. The identifiers and attributes might be different for different event types, but all identifiers and attributes are added to the header. The data value of the identifier or attribute that does not belong to an event code is blank for that row.

    The following table illustrates an example of the relationship between identifiers and attributes in the JSON to the first line of the TSV file.

    JSON TSV header
    provider provider
    source source
    channel channel
    x1id x1id
    Identifiers[i].name identifiers_<string_value>
    event.code event_code
    event.timestamp event_timestamp
    event.attributes[i].value event_attributes_<string_value>

     

     The following JSON sample and table illustrate how UBX maps the JSON data to a tab-separated file. 

     

    {
    "provider": "IBM",
    "source" : "Digital Analytics",
    "channel": "Web",
    "x1Id": "81147632-a3fe-43a5-b0c8-6289ca9302bc"
    "identifiers":
    [
    { "name": "email", "value": "slmoore@example.com" },
    { "name": "DA_cookie_id", "value": "098098-adfsfd-9323ad-78sdfs" }
    ],
    "events":
    [
    {
    "code" : "cartPurchase",
    "timestamp": "2015-03-18T13:55:06+00:00",
    "attributes":
    [
    { "name": "productId", "value": "d12345" },
    { "name": "productName", "value": "Widget ABC" },
    { "name": "basePrice", "value": "200.00", "type" : "number" },
    { "name": "quantity", "value": "2", "type" : "number" }
    ] },
    {
    "code" : "cartPurchase",
    "timestamp": "2015-03-18T13:55:06+00:00",
    "attributes":
    [
    { "name": "productId", "value": "d123465" },
    { "name": "productName", "value": "Widget 123" },
    { "name": "basePrice", "value": "13.00", "type" : "number" },
    { "name": "quantity", "value": "1", "type" : "number" }
    ] }
    ]}

     Stucture of the corresponding TSV file.

    SV Header Event 1 Event 2 Event <n>
    provider IBM IBM  
    source Digital Analytics Digital Analytics  
    channel web web  
    x1id 81147632-a3fe-43a5- b0c8-6289ca9302bc 81147632-a3fe-43a5- b0c8-6289ca9302bc  
    identifier_email slmoore@example.com slmoore@example.com  
    identifier_cookieid 098098-adfsfd-9323ad-78sdfs 098098-adfsfd-9323ad-78sdfs  
    event_code cartPurchase cartPurchase  
    event_timestamp 2015-03-18T13:55:06+00:00 2015-03-18T14:08:36+00:00  
    event_attribute_productid d12345 d123456  
    event_attribute_productname Widget ABC Widget 123  
    event_attribute_baseprice 200.00 13.00  
    event_attribute_quantity 2 1  

     

  2. Importing event data into a database

    Run the eventsImport script to add event data from the TSV file that is created by the eventsDownload script to a local SQL database. You can run the script manually or as a scheduled job.

    You can insert a single file or a single directory into the database. The UBX Toolkit provides a mapping file that you use to specify how the event data is added to the database.

    A. The Events Downloader calls the UBX HTTP API to download the event data from UBX and stores the data as a tab-separated (TSV) file in the client file system. UBX provides events files in JSON format. The Events Downloader component of the UBX Toolkit converts the JSON to a tab-separated value (TSV) format. The JSON data and the .tsv file are stored on the client.

    B. The Events DBImporter processes the TSV file and inserts individual events into the respective database tables, based on the event type.

    C. Use the sample mapping file to specify how the events data is stored in the local database.

     

    Procedure

    Run eventsImport.bat -m <mapping file> -i <source TSV file> -f <source directory> [-c <config properties file> -j <jdbc properties file>

    For Linux or UNIX, run eventsImport.sh -m <mapping file> -i <source TSV file> -f <source directory> [-c <config properties file> -j <jdbc properties file>

    Required parameters

    • -m <mapping file> The default mapping file is EventsDBTableMappings.
    • -i <input TSV file> Path to the input TSV file. If you specify a single .tsv file with the -i option, only that file is processed and the -f option will be ignored, even it is used.
    • -f <input folder> Path to the folder that contains the TSV files to be processed. If you specify a directory with the -f option, all .tsv files in that directory are imported.

    Optional parameters

    • -c <alternate config.properties> Use to define alternate configurations. When specified, properties in this file override the default configuration. Specify the path to the alternate location and file name. Do not rename the default properties file.
    • -j <alternate jdbc.properties> Use to define an alternate data source. When specified, properties in this file override the default configuration. Specify the path to the alternate location and file name. Do not rename the default properties file.
      Results

    After the eventsImport script imports the event data to the specified database, the script moves the TSV files to the $CU_HOME/AppData/dataProcessed directory. The dataProcessed folder is created under the downloads folder that you specify in config.properties.

     

    Sample database script for database table creation
     
    The UBX Toolkit provides a sample SQL script for creating the local database tables that you can use to store downloaded events data.

    In the $CU_HOME/ddl directory, the UBX Toolkit provides a sample script for MSSQL, DB2 and Oracle. The table and field names can be used with the sample mapping file.

    You can use this sample script as a solution that is ready for immediate use and that you can modify as needed to meet your business need.

    If you are upgrading from an earlier version of the UBX Toolkit, you can use upgrade scripts that are provided in the ddl directory.

    The toolkit also provides an example mapping file to match event data to the field names in the tables that you create with the sample EventToDBTableMapping.xml file.

     

    Events data to database table mapping
     
    The UBX Toolkit provides the EventDBTableMapping.xml file. You can use this file to map the fields in each event type to the columns in the event type database table. A sample file is located in the $CU_HOME/mapping folder.

    You can customize the sample file as needed. You can map multiple event codes to the same database tables. Event identifiers or attributes that are not mapped are ignored.

    The following example of how a recognized event is represented in the sample mapping file is based on the Cart Purchase recognized event.

    <?xml version="1.0"?>
    <EventToDBTableMappings>
    <TableMapping>
    <EventCode>ibmcartPurchase</EventCode>
    <Table>UBX_IBMCARTPURCHASE</Table>
    <Column>
    <Name>Provider</Name>
    <EventField>provider</EventField>
    </Column>
    <Column>
    <Name>EndpointSource</Name>
    <EventField>source</EventField>
    </Column>
    <Column>
    <Name>Channel</Name>
    <EventField>channel</EventField>
    </Column>
    <Column>
    <Name>X1ID</Name>
    <EventField>x1id</EventField>
    </Column>
    <Column>
    <Name>Email</Name>
    <EventField>identifier_email</EventField>
    </Column>
    <Column>
    <Name>Cookie</Name>
    <EventField>identifier_cookieid</EventField>
    </Column>
    <Column>
    <Name>EventCode</Name>
    <EventField>event_code</EventField>
    </Column>
    <Column>
    <Name>EventTimeStamp</Name>
    <EventField>event_timestamp</EventField>
    </Column>
    <Column>
    <Name>EventNameSpace</Name>
    <EventField>event_namespace</EventField>
    </Column>
    <Column>
    <Name>EventVersion</Name>
    <EventField>event_version</EventField>
    </Column>
    <Column>
    <Name>EventName</Name>
    <EventField>event_name</EventField>
    </Column>
    <Column>
    <Name>EventDescription</Name>
    <EventField>event_description</EventField>
    </Column>
    <Column>
    <Name>OrderID</Name>
    <EventField>event_attribute_orderid</EventField>
    </Column>
    <Column>
    <Name>InteractionID</Name>
    <EventField>event_attribute_interactionid</EventField>
    </Column>
    <Column>
    <Name>OrderSubTotal</Name>
    <EventField>event_attribute_ordersubtotal</EventField>
    <EventFieldType>number</EventFieldType>
    </Column>
    <Column>
    <Name>OrderShipping</Name>
    <EventField>event_attribute_ordershipping</EventField>
    <EventFieldType>number</EventFieldType>
    </Column>
    <Column>
    <Name>OrderDiscount</Name>
    <EventField>event_attribute_orderdiscount</EventField>
    <EventFieldType>number</EventFieldType>
    </Column>
    <Column>
    <Name>OrderPromo</Name>
    <EventField>event_attribute_orderpromo</EventField>
    <EventFieldType>number</EventFieldType>
    </Column>
    <Column>
    <Name>OrderTax</Name>
    <EventField>event_attribute_ordetax</EventField>
    <EventFieldType>number</EventFieldType>
    </Column>
    <Column>
    <Name>OrderTotal</Name>
    <EventField>event_attribute_ordetotal</EventField>
    <EventFieldType>number</EventFieldType>
    </Column>
    <Column>
    <Name>Currency</Name>
    <EventField>event_attribute_currency</EventField>
    </Column>
    <Column>
    <Name>ShippingType</Name>
    <EventField>event_attribute_shippingtype</EventField>
    </Column>
    <Column>
    <Name>Quantity</Name>
    <EventField>event_attribute_quantity</EventField>
    <EventFieldType>number</EventFieldType>
    </Column>
    <Column>
    <Name>ProductList</Name>
    <EventField>event_attribute_productlist</EventField>
    </Column>
    </TableMapping>
  3. Updating event download

    You can use the UBX Toolkit to download events that are not included by default in the example mapping file. To do so, you must update the mapping file and the local database tables.

    To download other events you must update the configuration of your UBX destination endpoint. If you add event data to a local SQL database using the example mapping file that the UBX Toolkit provides, you must update the mapping file and the database tables.

    1. In the UBX user interface, update the subscriber endpoint to subscribe to the new events. After you update the event registration for the subscribing endpoint, the eventsDownload script processes the new event files.
    2. If you use the UBX Toolkit to add event data to a local database, complete the following steps.
      1. Update the local database tables to receive the new event data.
      2. Update EventToDBTableMapping.xml to include a new section that maps fields from the new event to the new fields in the database.

     

  4. Custom event downloads

    To use the UBX Toolkit to download modified events or events other than the events that are supported by default, you must update your UBX endpoint subscriptions. If you add event data to a local SQL database, you must update the mapping file and the database tables.

    The example mapping file that is provided with the UBX Toolkit is based on the standard definition of specific recognized events. IBM recognized events contain some attributes that are optional. Depending on the source of the event data, the downloaded events might not contain data for all possible attributes.

    To download event data that does not contain all of the standard event attributes, you must remove the missing attributes from the mapping file and update the design of the local destination database to match.

    You can also configure the UBX Toolkit to download event types other than the default events. To download event data for recognized events other than the events specified in the mapping file, you must add a section to the mapping file that defines the added event data.

Overview

Skill Level: Any

Prerequisites

To install the UBX Toolkit, download the toolkit file archive and install various scripts and properties files on a server in your local network environment. Update default settings and property files to suit your local network requirements.

The UBX Toolkit consists of various property files and scripts that you install in your local network environment and modify to satisfy your business requirements. The installation and configuration process proceeds as follows.

  1. Download the UBX Toolkit from IBM developerWorks as a compressed file archive.
  2. Extract the archive to a directory on a local server. Extracting the archive creates local directories that contain UBX Toolkit environment files and configuration property files.
  3. Modify UBX Toolkit environment files to reflect paths in your local environment.
  4. Register UBX endpoints in the UBX user interface, updating UBX toolkit configuration properties, and running the endpoint registration script.
  5. (Optional) Encrypt the configuration settings for enhanced security, as required by your business security policy.

Step-by-step

  1. Download the UBX toolkit

    Confirm that you have rights to access and edit files on the server where you want to install the UBX Toolkit.

    Confirm the locations of the JRE and JDBC database drivers.

    Download the UBX Toolkit files as a compressed archive and extract in a location on a server in your local network environment. The source files are available on IBM developerWorks. Go to: IBM UBX Toolkit for IBM Marketing Software

    Click the link to download either of the following binary files.

    • Windows: IBM_Universal_Behavior_Exchange_Toolkit_v1.3_Windows.zip
    • Linux or UNIX: IBM_Universal_Behavior_Exchange_Toolkit_v1.3_Unix-Linux.tar.gz

    The directory to where you download the files is referenced within the toolkit as CU_HOME.

  2. Install and configure the environment files

    1. Depending on your operating system, copy and rename <CU_HOME>\bin\example_setenv.bat or example_setenv.sh to setenv.bat or setenv.sh
    2. Modify the following variables in the setenv file:
    • JAVA_HOME: Enter the path to the JRE.
    • CU_HOME: Enter the path to the directory where you extracted the UBX Toolkit files.
    • JDBC_CLASSPATH: Enter the path to the JDBC driver for the database importer.
  3. Install the configuration properties and logback files

    Copy and rename the default example files that are provided in the conf directory.

    • Rename example_logback.xml to be logback.xml.
    • Rename example_config.properties to be config.properties.
    • Rename example_jdbc.properties to jdbc.properties.

    Note: Do not rename config.properties or jdbc.properties after you create them. The UBX Toolkit requires these default configuration files in the CU_HOME directory. If you need to create alternative configuration or data source files, you can create multiple other copies with different names and different values so that you can override the default settings, if necessary.

  4. Registering an endpoint using the UBX Toolkit

    To share event and audience data between UBX endpoints, users must register each endpoint with UBX. After initiating the endpoint registration process in the UBX UI, UBX users can acquire their authentication key in the UBX Endpoint details menu and then provide the key to the endpoint provider.
    Each time an endpoint communicates with UBX, the endpoint must submit the authentication key as the authorization bearer or URL parameter in calls to UBX APIs. Each authentication key is unique to a specific UBX account and for use by a single endpoint.

    Depending on your corporate data and network security policies, you can perform either or both of the following configurations.

    To use the UBX Toolkit to register an endpoint with UBX, you provide an endpoint-level authentication key as a value in the UBX Toolkit properties file.

    Running the UBX Toolkit endpoint registration script makes an API call that includes the authentication key so that UBX can authenticate with the endpoint provider.

    Note: To register cloud-based endpoints that are not supported by the UBX Toolkit, you can register the endpoint directly through the endpoint registration wizard.

    Procedure

    1. Log into UBX with your UBX account login credentials
    2. On the Endpoints tab, click Register new endpoint to display the endpoint registration wizard.
    3. From the list of provided endpoints, select UBX Toolkit and select Next.
    4. The endpoint appears on the Endpoints tab as Pending.
    5. On the Endpoints tab, open the endpoint details menu of your endpoint and copy and save the Endpoint Authentication Key.
    6. In the config.properties file, enter the Endpoint Authentication Key in the ubx.application.endpoint.authentication.key field.
    7. From the $CU_HOME/bin folder, run registerEndpoint.bat or registerEndpoint.sh. script.
    8. To confirm the successful endpoint registration, log in to UBX to find your endpoint listed as Active.

    Note: If you are upgrading from an earlier version of the UBX Toolkit, you will not need to complete this step as your current enpoint will still function. However, notice that the property names have changed. Update the property names and event mapping file in your UBX Toolkit installation to match the names that are provided in the latest version.

    After you have completed the UBX Toolkit and configuration process, return to the UI to select the events and audiences to which you want to subscribe. Configure an event subscription between the event source endpoint and the event destination endpoint.

  5. Modify config.properties

    Modify the content of config.properties to suit your installation. Replace the default values with values that are appropriate for your business application and requirements. 

  6. Modify jdbc.properties

    If you plan to import event data into a SQL database, modify the content of jdbc.properties to suit your installation. Configure the required parameters in this file:

    • jdbc.driver: Specify the JDBC driver class that is used by the database where you import event data. Example, if you are using a DB2 database, jdbc.driver=com.ibm.db2.jcc.DB2Driver;
    • jdbc.url: Specify the database type, database driver, host, port, database name, and schema name, if applicable. Consult your database documentation for specific instructions.

    Note: If you are using a DB2 database, you must specify the schema name, and it must be specified in uppercase characters.

    For example, if you are using a DB2 database, jdbc.url=jdbc:db2://exampleServer:<1234>/DBname:currentSchema=<SCHEMA_NAME>

    • jdbc.user: Specify the name of a database user that can automatically access, and write to, the database where you import event data.

    Note: Database users are restricted to the schemas that they have permission to write to. Moreover, the database user you specify in jdbc.user must have permission to write to the schema you specified in jdbc.url.

    For example, jdbc.user=databaseUserName

    • jdbc.password: Specify the password that is defined for a system user that can automatically access, and write to, the database where you import event data.

    Note:The password must correlate with the system user who is specified in jdbc.user.
    Example, jdbc.password=databaseUserPassword

    After you have configured the schema, and are using recognized UBX events, run the DDL the corresponds to the SQL database you use. The Toolkit includes DDL for three database types. They are:

    • camp_ubx_tab_db2.sql
    • camp_ubx_tab_ora.sql
    • camp_ubx_tab_sqlsvr.sql

    Note: If you are upgrading from a previous version of the UBX Toolkit, you must upgrade in order of succession. For example, if you are upgrading from Toolkit 1.0 then you first must upgrade to 1.2 before you can upgrade to 1.3. This is required if you intend to use recognized UBX events.

  7. Update audience producer and audience consumer endpoint ID

    In the config.properties file you must update both the ubx.audience.consumer.endpoint.id and the ubx.audience.producer.endpoint.id with your endpoint ID. The endpoint ID is returned registerEndpoint script’s log file.

    The following is an example of a log generated by the registerEndpoint script:

    2017-06-23 09:56:18,432 INFO Registered Endpoint ID: 60871
    2017-06-23 09:56:18,433 INFO Please update the configuration file with the endpoint ID for:
    Audience Producer endpoint ID=60871
    Audience Consumer endpoint ID=60871
    2017-06-23 09:56:18,433 INFO Register Endpoint script succeeded.
    2017-06-23 09:56:18,434 INFO ***** Register Endpoint script completed.

  8. Run chmod

    (Linux or UNIX only) In the bin directory, enter the command: chmod +x *.sh.

The UBX Toolkit provides a way for locally installed applications, also called On Premises applications, to interact with IBM Universal Behavior Exchange (UBX).

UBX creates a structure that supports dynamic relationships between independent software applications that register with UBX. Each UBX participating application can provide different types of marketing data and different ways to identify individual customers. The UBX Toolkit installs behind your corporate firewall to securely connect your local applications and databases to UBX APIs and the IBM Watson Customer Engagement ecosystem.

You can use the UBX Toolkit to perform the following actions.

  • A. Upload audience data from a local application to UBX. The application appears in UBX as an audience source endpoint (audience producer).
  • B. Download event data from UBX to a local application. The application appears in UBX as an event subscriber (event consumer) endpoint.
  • C. Download audience data from UBX to a local application. The application appears in UBX as an audience destination (audience consumer).
  • UBXtoolkit_GnrlOverview

    When to use the UBX toolkit

    UBX users can apply the UBX Toolkit to integrate their business solution with UBX when the solution includes software that a UBX customer installs in their local environment.

    Installing the UBX Toolkit is an alternative to opening your corporate firewalls to allow UBX to pull data from a data source application or to push data to a data consumer application. The UBX Toolkit installs behind your corporate firewall to communicate securely with UBX over HTTPS.

    Audience producers

    Use the UBX toolkit if a locally installed business solution can provide audience data as a file that can be uploaded to UBX. For example, owners of IBM Campaign can run flowcharts that generate output as a CSV file. The toolkit enables the flowchart output to appear in UBX as an available audience. You can schedule the UBX Toolkit to run periodically so that UBX users always have access to updated audience data.

    Audience consumers

    If a locally installed application is a destination for audience data, use the UBX Toolkit to provide data when it is available in UBX. You can configure the toolkit to run as a scheduled job to automatically check for new audience data.

    Event consumers

    If a locally installed business solution accepts event data as an event subscriber, use the UBX Toolkit to download the event data and add it to a local database. The UBX Toolkit provides a sample mapping file that you can use to specify how the event data is stored in the database. For example, you might use the imported event data for custom reporting, analysis, and retargeting.

    General requirements for the UBX Toolkit

    Installing and operating the UBX Toolkit requires access to the UBX user interface, UBX authentication keys, and administrative access to various systems that are related to the applications that register with UBX.

    Before you begin, confirm that you have established the required access privileges and logins.

    To establish access to UBX, use the UBX user interface and collaborate with the UBX Account Provisioning team.

    To establish access to resources that are associated with the locally installed data producer or consumer application, contact the local system

    UBX access requirements

     

    To access UBX, IBM must create and provision a UBX account on your behalf. UBX depends on authentication keys to ensure that you can access only the endpoints that are registered for your account.

    To request that IBM to create and provision your UBX account, contact the UBX Account Provisioning team by email at ubxprovisioning@wwpdl.vnet.ibm.com or request access to UBX at https://www-01.ibm.com/marketing/iwm/iwm/web/signup.do?source=ibm-ubxprovision.

    Your fully provisioned account includes the following elements.

    • UBX user account, including credentials to log in to the UBX user interface.
    • An endpoint-level UBX authentication key.
    • A URL to call external UBX APIs. Contact IBM for the address that your UBX account requires.

    UBX authentication key requirements

    The UBX Toolkit calls various UBX APIs. Each call must include an endpoint-level authentication key that is specific to your account.

    You must provide the authentication key in the configuration properties for your installation of the UBX Toolkit.

    You can find your endpoint-level authentication key in the Endpoint details menu on the Endpoints tab in the UBX user interface. You must have a valid login to UBX to access the Endpoints tab.

    Local access requirements

    Installing and operating the UBX Toolkit requires access to various systems in your local network environment. Establishing this access typically requires network or database administrative privileges.

    Before you begin, confirm that you have established the following access privileges and logins.

    • Administrative access to install and configure files on the server where you install the UBX Toolkit. Contact your local system administrator for the required address and privileges.
    • Administrative access to the database where you want to import event data. Contact your database administrator for the required address and privileges.

    Resources and support for the UBX Toolkit

     

    IBM provides various resources to support the UBX Toolkit. You can take advantage of installed, online, and educational resources. IBM developerWorks is the home for the binary source files that are required to install the UBX Toolkit.

    Source files for the UBX Toolkit

    IBM provides the UBX Toolkit as a downloadable file archive that you can access on IBM developerWorks.

    To download the UBX Toolkit, go to

    IBM Universal Behavior Exchange Toolkit for IBM Marketing Software

    Documentation and training for UBX

    To learn more about how to use UBX to meet your business requirements, you can review product documentation and training resources that IBM has developed for UBX.

    View the general UBX product documentation in the IBM Knowledge Center. In the Knowledge Center, > IBM Universal Behavior Exchange.

    For tutorials that are specific to the UBX Toolkit, see the following links.

    Visit the IBM Learner portal to view a series of educational videos that serve as an Introduction to IBM Universal Behavior Exchange.

    Troubleshooting and support for UBX

     

    If you are having a problem with UBX, IBM provides different ways to help you to resolve the issue, depending on how you are accessing UBX.

    UBX Forum

    All UBX users can access the UBX Forum. You can post your question, review questions and answers that fellow UBX users have posted, or make a suggestion of your own. UBX subject matter experts routinely monitor the forum to contribute their own insights and experience to the discussion.

    To access the UBX Forum, go to https://developer.ibm.com/answers/topics/ubx/

    UBX Support

    UBX users who have registered at least one IBM Commerce endpoint in UBX are considered registered users. As a registered UBX user, not only can you access the UBX Forum, but you are also entitled to assistance from IBM Support and access to the IBM Client Success Portal.

    For issue tracking from ticket creation to resolution, visit the IBM Client Success Portal, which provides complete insight into the status of your inquiries. Find the IBM Client Success Portal at https://support.ibmcloud.com.

    To learn more about IBM support for cloud-based services like UBX, see the IBM Software as a Service (SaaS) Support Handbook. Find the handbook at http://www.ibm.com/software/support/acceleratedvalue/SaaS_Handbook_V18.pdf.

    Note: You must be a registered UBX user to engage the UBX Support team.

    To become a registered UBX user, simply register one IBM Commerce endpoint in your UBX environment. Go to the Endpoints tab and click Register new endpoint. For more information about registering an endpoint, see Registering endpoints.

    Logging for the UBX Toolkit

    You can access the log files for the UBX Toolkit in the %CU_HOME%/logs folder.

    Event files that are processed successfully are stored by default in the %CU_HOME%/AppData/eventsDownload folder.

    Event files that the UBX Toolkit is not able to process are stored in the dataError directory. If you encounter problems during event data import, review the condition and structure of the files in the %CU_HOME%/AppData/downloads/dataError folder to determine a course of action.


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.