IBM Universal Behavior Exchange Toolkit
Release 16.1.2
April 8, 2016
User's Guide
Note
Before using this information and the product it supports, read the information in “Notices” on page 39.
This document applies to all versions of IBM Enterprise Marketing Management products that incorporate email services hosted by IBM and to all subsequent releases and modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 2015, 2016.
Contents
Chapter 1. Overview of the UBX Toolkit
1
When to use the UBX toolkit . . . 2
UBX Overview . . . 2
General requirements for the UBX Toolkit . . . . 3
UBX access requirements . . . 4
UBX authentication key requirements . . . 4
Local access requirements . . . 4
Resources and support for the UBX Toolkit . . . . 5
Troubleshooting and support for UBX . . . 5
Logging for the UBX Toolkit . . . 5
Chapter 2. UBX Toolkit installation and
configuration
. . . 7
Installing the UBX toolkit . . . 7
Endpoint registration with the UBX Toolkit . . . 8
UBX authentication keys for the UBX Toolkit . . . 8
Generating an endpoint-level authentication key . 9 Requesting a UBX account-level authentication key . . . 9
Connecting the UBX Toolkit through a proxy server 10 Encrypting the UBX Toolkit configurations . . . . 10
Creating a custom UBX Toolkit encryption key 12 Removing encryption from UBX Toolkit configuration properties . . . 12
Chapter 3. Event destination endpoints 15
Registering the event destination endpoint . . . . 15Downloading events from UBX. . . 17
JSON format for download event data . . . . 18
JSON to TSV Header Mapping . . . 19
Importing event data into a database . . . 21
Sample database script for database table creation. . . 22
Events data to database table mapping . . . . 22
Updating event download . . . 25
Custom event downloads. . . 26
Chapter 4. Audience source endpoints
27
Registering as an audience source endpoint . . . 27Audience generation . . . 29
Audience registration . . . 30
Registering audience data with UBX . . . 31
Audience sharing by UBX users . . . 31
Audience upload . . . 32
Uploading audience data to UBX . . . 33
Archiving the local copy of the audience data after upload . . . 34
Chapter 5. Audience destination
endpoints . . . 35
Registering as an audience destination endpoint . . 36
Downloading audience data from UBX . . . 37
Notices
. . . 39
Trademarks . . . 41
Chapter 1. Overview of the UBX Toolkit
The UBX Toolkit provides a way for locally installed applications, also called On
Premise 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 Commerce 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).
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.
UBX Overview
IBM UBX is a cloud-based service from IBM that you can use to selectively exchange business data between various IBM Commerce solutions and IBM Business Partner applications.
Owners of IBM Commerce and IBM Business Partner solutions can use UBX to specify what to share and when to share it. By blending data contributions from multiple UBX endpoints, UBX users can build a view of their customers that is richer, better targeted, and more timely than any single application can provide. Participating IBM Commerce and IBM Business Partner solutions can quickly integrate data from various IBM Commerce applications that they install in their own computer network or that they access as a web-based service. They can also integrate data from selected independent companies who collaborate with IBM to make their customer interactions available through UBX.
Marketing applications from IBM and selected IBM Business Partners access UBX automatically through various APIs. Each application is referred to as an endpoint. Each endpoint must be registered with UBX. When you register an endpoint with UBX, the endpoint appears as an option in the UBX user interface.
UBX users create connections between data that is produced by registered
applications to help address their unique use cases. These connections are referred to as syndications. In UBX, syndication refers to the process that business users complete to select a data provider, specify the data to exchange, and designate where to deliver the data.
The following diagram illustrates the relationships and interactions between UBX and the syndicated marketing applications that participate in UBX.
For more information about how to integrate business solutions through UBX, see the IBM Universal Behavior Exchange Integration Guide.
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 administrator or IT department.
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 [email protected] 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.
v UBX user account, including credentials to log in to the UBX user interface. v An endpoint-level UBX authentication key.
v An account-level UBX authentication key. This key is required for connecting an audience consumer endpoint to UBX.
v 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 authentication key that is specific to your account or to your UBX endpoint registration request. UBX recognizes and requires endpoint-level authentication keys and account-level authentication keys.
You must provide the authentication keys in the configuration properties for your installation of the UBX Toolkit.
You create an endpoint-level authentication key through the Endpoints tab in the UBX user interface. You must have a valid login to UBX to access the Endpoints tab.
When IBM creates your UBX user account, it creates an account-level
authentication key. The account-level authentication key is different from the endpoint-level authentication key that you create through the Endpoints tab in UBX. The account-level authentication key enables endpoint providers to take actions on behalf of multiple UBX user accounts that syndicate connection to the endpoint.
To request the account-level authentication key that IBM created for your UBX account, send a request by email to the UBX Provisioning team at
Related tasks:
“Registering as an audience destination endpoint” on page 36 “Requesting a UBX account-level authentication key” on page 9
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.
v 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.
v 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 on IBM developerWorks.
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 current UBX product documentation in the IBM Knowledge Center. In the Knowledge Center, go to ExperienceOne > IBM Universal Behavior Exchange. 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 Support can help you to resolve the issue.
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.
To contact the UBX Support team directly, send email to: [email protected] .
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
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.
Chapter 2. UBX Toolkit installation and configuration
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 source or destination endpoints by updating specific UBX toolkit configuration properties.
5. (Optional) Encrypt the configuration settings for enhanced security, as required by your business security policy.
Installing the UBX toolkit
Installing the UBX Toolkit involves downloading the source file archive from IBM developerWorks and then modifying environment variables.
Before you begin
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.
Procedure
1. 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.
v Windows: IBM_Universal_Behavior_Exchange_Toolkit_v1.2_Windows.zip v Linux or UNIX:
IBM_Universal_Behavior_Exchange_Toolkit_v1.2_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.
a. Depending on your operating system, copy and rename
<CU_HOME>\bin\example_setenv.bat or example_setenv.shto setenv.bat or setenv.sh
v JAVA_HOME: Enter the path to the JRE.
v CU_HOME: Enter the path to the directory where you extracted the UBX Toolkit files.
v 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.
a. Rename example_logback.xml to be logback.xml.
b. Rename example_config.properties to be config.properties.
c. 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 alternate 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.
What to do next
Configure the UBX Toolkit to register the local application as a UBX endpoint. Depending on your corporate data and network security policies, you can perform either or both of the following configurations.
v Connect to UBX through a web proxy server. v Encrypt the UBX Toolkit configurations.
Endpoint registration with the UBX Toolkit
The UBX Toolkit provides configuration properties and scripts that can call UBX endpoint registration APIs. Register an endpoint by modifying configuration properties and running the registration script.
The specific configurations and scripts that are required depend on whether the endpoint is a data producer or data consumer and on the type of data that you exchange with UBX.
v Event consumers: Chapter 3, “Event destination endpoints,” on page 15 v Audience producers: Chapter 4, “Audience source endpoints,” on page 27 v Audience consumers: Chapter 5, “Audience destination endpoints,” on page 35
UBX authentication keys for the UBX Toolkit
UBX requires a user-generated authentication key to indicate that an endpoint has permission to interact with UBX on behalf of a specific authorized UBX user account. UBX recognizes authentication keys generated at the endpoint level and at the UBX account level.
To share event and audience data between UBX endpoints, users must register each endpoint with UBX. During endpoint registration, UBX users generate an authentication key in the UBX user interface and then provide the key to the endpoint provider. A UBX user account typically generates multiple authentication keys.
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. UBX compares the authentication key that the endpoint submits to the authentication keys that it recognizes as being created by the UBX user. Each authentication key is unique to a specific UBX account and for use by a single endpoint.
Endpoints do not appear as options in the UBX user interface until the endpoint provider registers with UBX.
When IBM provisions UBX endpoint provider accounts, it generates account-level authentication keys that the endpoint requires to operate across multiple UBX user accounts. Registering audience consumer endpoints with the UBX Toolkit requires an account-level authentication key.
Generating an endpoint-level authentication key
As a UBX user, you generate an endpoint-level authentication key in the UBX user interface. You can enter an endpoint-level authentication key in the UBX Toolkit configuration when you register an endpoint with the UBX Toolkit.
About this task
To register an endpoint in UBX, you must generate an authentication key that is specific to your UBX account. For each endpoint that you register under your UBX account, you must log in to UBX and generate the key through a link in the UBX user interface.
To use the UBX Toolkit to register the endpoint with UBX, you provide the authentication key as a value in the UBX Toolkit configuration. Running the endpoint registration script with the toolkit makes an API call that provides the authentication key to UBX on behalf of the endpoint provider.
Note: To register cloud-based endpoints that are not supported by the UBX Toolkit, you generate the authentication key and submit it directly to the endpoint provider.
You must register each endpoint separately.
Procedure
1. Log into UBX with your UBX account login credentials.
2. On the Endpoints tab, click Register new endpoint. An authentication key displays as an alphanumeric string.
3. Copy the string and save it.
What to do next
Enter the authentication key as a value in the UBX Toolkit configuration. The configuration property that you populate depends on the type of endpoint that you are registering.
Requesting a UBX account-level authentication key
In some cases, you must provide an account-level authentication key as a UBX Toolkit configuration property to use the toolkit to register an endpoint. You must contact IBM to request an account level authentication key.
Procedure
To request an account-level authentication key, contact the UBX Account Provisioning team by email at [email protected].
What to do next
Enter the authentication key as a value in the UBX Toolkit configuration. The configuration property that you populate depends on the type of endpoint that you are registering.
Related concepts:
“UBX authentication key requirements” on page 4
Connecting the UBX Toolkit through a proxy server
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.
About this task
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>
Procedure
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.
v proxy.url
Specify the URL for the web proxy server. v proxy.username
Specify the user name that is used to access the web proxy server. Leave blank if authenticated access is not required.
v 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.
Encrypting the UBX Toolkit configurations
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.
Before you begin
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.
About this task
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.
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.
Procedure
Depending on your operating system, run encryptConfig.bat (Windows) or
encryptConfig.sh(UNIX or Linux).
v To encrypt jdbc.properties and config.properties simultaneously, run the script as: <CU_HOME>/bin/encryptConfig.
Example: <CU_HOME>\bin\encryptconfig.bat
v 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.
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.
About this task
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>
Results
The new custom password is used to encrypt values in jdbc.properties and authentication.keyin config.properties.
What to do next
Run the encryptConfig script to encrypt the configuration settings.
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.
About this task
Encrypted values can be found in jdbc.properties and config.properties. The encrypted values appear as random strings.
Procedure
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.
Results
Chapter 3. Event destination endpoints
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 event consumer scripts to perform the following tasks.
v Register the event destination endpoint v Download event data from UBX
v 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.
Registering the event destination endpoint
The application that receives event data with UBX must be registered with UBX as an endpoint. Run the registerEndpoint script to perform the registration.
Before you begin
Confirm that you have a UBX user account. You can contact the IBM Account Provisioning team to verify your UBX account details.
About this task
Run the registerEndpoint script to register the application as a UBX endpoint. Registering the endpoint makes it visible in the UBX user interface and provides UBX with the information that it needs to download the event data.
This script calls the UBX v1/endpoint API to register the endpoint as a subscriber. To register the endpoint, the script must provide the authentication key.
After the endpoint is registered, you must log in to the UBX UI to select which event types to subscribe to before running scripts for downloading event data or importing the data into local tables.
Procedure
v Log in to the UBX user interface to create an authentication key. In config.properties, enter the key as the value for
ubx.endpoint.authentication.key
v Verify the following settings in config.properties:
– ubx.event.consumer.endpoint.name: name for the endpoint that receives event data
– ubx.event.consumer.endpoint.desc: brief description for the endpoint that receives event data
– ubx.event.consumer.endpoint.provider: name of the endpoint provider as it should appear in the UBX user interface.
– ubx.event.consumer.endpoint.authentication.key: the authentication key for registering the endpoint and accessing APIs.
– 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.
Note: If you are upgrading from an earlier version of the UBX Toolkit, notice that the property names have changed. Update the property names in your UBX Toolkit installation to match the names that are provided here.
v From the $CU_HOME/bin folder, run registerEndpoint.bat or registerEndpoint.sh. Specify the -t option as -t eventConsumer.
What to do next
To confirm the successful endpoint registration, log in to UBX to find the endpoint as an option in your UBX endpoints tab.
Select the event types to which you want to subscribe. Configure an event subscription between the event source endpoint and the event destination endpoint.
For more information about how to define an event subscription, see the IBM
Universal Behavior Exchange User’s Guide.
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.
Before you begin
Log in to UBX to confirm that you have configured an event subscription to the destination endpoint.
About this task
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 local.download.dirproperty in config.properties.
UBX transforms the downloaded JSON object into a TSV file.
The default local download directory is $CU_HOME/AppData/downloads, but it can be customized in the config.properties file.
Procedure
1. In the conf directory, verify the following settings in the config.properties file. v ubx.api.service.url=http://<server-name>:<port>. The service URL for
v ubx.endpoint.eventfiles.numFilesInList=<number>The number of files in the list returned when the eventfiles API is called.
v local.download.dir=%CU_HOME%/AppData/downloads. The directory where the downloaded files are saved.
v dbinsert.keep.processed.files=true
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/downloads. 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.
Results
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.
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>" } ]
} ] }
See the IBM Universal Behavior Exchange Integration Guide for more information about how UBX provides event data in JSON format to event subscribers.
JSON to TSV Header Mapping
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": "[email protected]" },
{ "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.
TSV 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 [email protected] [email protected] 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
You can use the TSV file as the source file for importing the events data into a local database.
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.
About this task
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:
v -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.
v -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:
v -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.
v -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 EventToDBTableMapping.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 EventToDBTableMapping.xml provides examples for the following types of IBM recognized events.
v CartPurchase v Cart Purchase Item v Cart Abandonment v Cart Abandonment Item v Conversion v Abandoned conversion v Searched site v Product View v Visited site v Email Sent v Email Open v Email Click v Email Bounce SMS events v sentSMS v interactedSMS Mobile push events
v application/appInstalled v application/appUninstalled v application/sessionStarted v application/sessionEnded v application/uiPushEnabled v application/uiPushDisabled v simpleNotification/appOpened v simpleNotification/urlClicked
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>
</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> Related tasks:
“Updating event download”
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.
About this task
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.
Procedure
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.
For more information about updating your endpoint subscriptions, see the IBM
Universal Behavior Exchange User’s Guide.
2. If you use the UBX Toolkit to add event data to a local database, complete the following steps.
a. Update the local database tables to receive the new event data.
b. Update EventToDBTableMapping.xml to include a new section that maps fields from the new event to the new fields in the database.
Related concepts:
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.
Chapter 4. Audience source endpoints
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.
v Register the audience producer endpoint. Run the registerEndpoint.bat/sh script.
v Create an audience file in the audience producer application. Create the file as a CSV file.
v Register the CSV file as an available audience in UBX. Run audienceRegister.bat/shas a scheduled job.
v 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.
Registering as an audience source endpoint
The application that provides audience data to UBX must be registered with UBX as an audience source endpoint. Run the registerEndpoint script to perform the registration.
Before you begin
Confirm that you have a UBX user account. You can contact the IBM Account Provisioning team to verify your UBX account details.
About this task
Run the registerEndpoint script to register the application as a UBX endpoint. Registering the endpoint makes it visible in the UBX user interface and provides UBX with the information that it needs to download the event data.
You need to run the registerEndpoint script only once, unless you change the endpoint configuration. If you change properties in the endpoint configuration, run the script after you complete the changes.
This script calls the UBX v1/endpoint API to register the endpoint as an audience source. To register the endpoint, the script must provide an endpoint-level authentication key.
Procedure
1. Log in to the UBX user interface to create an authentication key. In config.properties, enter the key as the value
forubx.endpoint.authentication.key
2. Verify the following settings in config.properties:
v ubx.api.service.url=https://api.adm01.com. Web address URL for the UBX API service.
v ubx.audience.producer.endpoint.name=<name of the endpoint that
produces the audience data> Displays in the UBX user interface. (Required) v ubx.audience.producer.endpoint.desc=<brief description of the audience
producer endpoint> The description displays in the UBX user interface. v ubx.audience.producer.endpoint.provider=<endpoint provider name>
Displays in the UBX user interface. (Required)
v ubx.audience.producer.endpoint.authentication.key=<endpoint-level authentication key> Generate in the UBX user interface. (Required)
v ubx.audience.producer.endpoint.marketingdb.name=<name of the database that provides the audience data>
v ubx.audience.producer.endpoint.marketingdb.identifiers=
<identifier_name>|<identifier_type>Comma-separated list of identifiers contained in the audience data. Default identifier data type: string.
(Required)
v ubx.audience.producer.endpoint.marketingdb.attributes=
<attrib_name>|<attrib_type>Comma-separated list of audience attributes. Default attribute data type: string.
v ubx.audience.producer.audiencePublishFolder=%<home_directory>%/ <directory>/<audience_folder>Directory that contains the CSV file that provides the audience data.
3. From the $CU_HOME/bin folder, run registerEndpoint.bat or registerEndpoint.sh. Specify the –t option as audienceProducer. When the script finishes, the script displays:
Registered endpoint ID = <number>
Please ensure that this endpoint ID is stored in the config.properties file.
4. In config.properties, update the endpoint ID property. Enter the value that the script returned. For example, ubx.audience.producer.endpoint.id=<enter the number here>.
What to do next
To confirm the successful endpoint registration, log in to UBX to find the endpoint as an audience source option in your UBX endpoints tab. Review the endpoint details pages to confirm that the descriptions, identifiers, and attributes are set correctly.
Audience generation
Use features in the audience source application to generate the audience data that you want to make available in UBX. The application output must be in the form of a CSV file.
The first line of the CSV file contains the column headers. One column must be an identifier that you use to uniquely identify each audience member. For example, email address.
▌A▐ Create an audience that you can upload to UBX by segmenting a marketing database to select individuals according to specific identifiers and attributes. The method that you use to create an audience depends on the application. For
example, in IBM Campaign, to create an audience that you can upload to UBX, run a flowchart that generates a CSV file as output.
▌B▐ Save the segment that defines the audience as a CSV file in the following format: UBXSegment_<AudienceName>.csv Do not include spaces in the file name.
▌C▐ You must save the application output file in a directory that you specify in the ubx.audience.producer.audiencePublishFolderproperty in the config.properties file.
You must save the CSV file with the required naming convention and in the location that you specify for audience data. The audience registration and upload scripts ignore audience data that does not follow the file naming and location requirements.
Audience registration
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
audienceRegisterscript 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
audienceRegisterscript 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.
v To update audiences, the script calls PUT /v1/endpoint/{endpointid}/segments v 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.audiencePublishFolderconfiguration property. The script moves the processed CSV files to the published folder.
Registering audience data with UBX
Run the audienceRegister script as a scheduled job to provide information to UBX that describes new or updated audience data that has been created in the source application.
About this task
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.
Results
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.
What to do next
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.
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
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. For more information about how UBX users request audience data, see the IBM
Universal Behavior Exchange User's Guide.
Related concepts: “Audience upload”
Audience upload
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.
For more information about the UBX public APIs, see the IBM Universal Behavior
Exchange Integration Guide.
Related concepts:
“Audience sharing by UBX users” on page 31
Uploading audience data to UBX
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
Results
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.
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.
About this task
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.
v To move the CSV file that defines the audience data to the Delivered folder, set ubx.audience.producer.moveFileToDeliveredFolderto 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. v 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.
Chapter 5. Audience destination endpoints
Use the UBX Toolkit to download audience data that is available in UBX to a locally installed application. The process involves updating toolkit configurations and running scripts to identify and download the audience data from UBX to your local environment.
Using the UBX Toolkit to download audience data from UBX involves the following steps.
v Register the audience destination endpoint. Run the registerEndpoint.bat/sh script.
v 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/shscript 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.
▌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.
Registering as an audience destination endpoint
The application that receives audience data from UBX must be registered with UBX as an audience destination endpoint. Run the registerEndpoint script to perform the registration.
Before you begin
Confirm that you have a UBX user account. You can contact the IBM Account Provisioning team to verify your UBX account details.
About this task
Run the registerEndpoint script to register the application as a UBX endpoint. Registering the endpoint makes it visible in the UBX user interface and provides UBX with the information that it needs to download the event data.
You need to run the registerEndpoint script only once, unless you change the endpoint configuration. If you change properties in the endpoint configuration, run the script after you complete the changes.
This script calls the UBX v1/endpoint API to register the endpoint as an audience destination. To register the endpoint, the script must provide an endpoint-level authentication key and an account-level authentication key. Generate the endpoint-level authentication in the UBX user interface. Contact IBM to get the required account-level authentication key.
The following procedure describes how to register a Pull type audience destination endpoint.
Procedure
1. Log in to the UBX user interface to create an authentication key. In
config.properties, enter the key as the value for ubx.endpoint.authentication.key
2. Contact the IBM Account Provisioning team by email at
[email protected] to request the account-level authentication key for your UBX account.
3. Verify the following settings in config.properties:
v ubx.api.service.url=https://api.adm01.com. Web address URL for the UBX API service.
v ubx.accountlevel.authentication.key=<account-level authentication key> (Provided by IBM).
v ubx.audience.consumer.endpoint.name=<name of the endpoint that consumes the audience data> Displays in the UBX user interface as an audience destination. (Required)
v ubx.audience.consumer.endpoint.desc=<brief description of the audience destination endpoint> The description displays in the UBX user interface.
v ubx.audience.consumer.endpoint.provider=<endpoint provider name> Displays in the UBX user interface. (Required)
v ubx.audience.consumer.endpoint.authentication.key=<endpoint-level authentication key> Generate in the UBX user interface. (Required)
v ubx.audience.consumer.endpoint.marketingdb.name=<name of database that receives the audience data>
v ubx.audience.consumer.endpoint.marketingdb.identifiers=
<identifier_name>|<identifier_type>Comma-separated list of identifiers contained in the audience data. Default identifier data type: string.
(Required)
v ubx.audience.consumer.endpoint.marketingdb.attributes=
<attrib_name>|<attrib_type>Comma-separated list of audience attributes. Default attribute data type: string.
v ubx.audience.consumer.audienceDownloadFolder=%<home_directory>%/ <directory>/<audience_folder>Directory that contains the CSV file that the download script creates to receive the audience data.
4. From the $CU_HOME/bin folder, run registerEndpoint.bat or registerEndpoint.sh. Specify the –t option as audienceConsumer. When the script finishes, the script displays:
Registered endpoint ID = <number>
Please ensure that this endpoint ID is stored in the config.properties file.
5. In config.properties, update the endpoint ID property. Enter the value that was returned by the script. For example,
ubx.audience.consumer.endpoint.id=<enter the number here>
What to do next
To confirm the successful endpoint registration, log in to UBX to find the endpoint as an audience destination option in your UBX endpoints tab. Review the endpoint details pages to confirm that the descriptions, identifiers, and attributes are set correctly.
Related concepts:
“UBX authentication key requirements” on page 4
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.
Procedure
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
ubx.audience.consumer.audienceDownloadFolderconfiguration 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.
