IBM Uniersal Behaior Exchange Toolkit Release 16.2.6 June 24, 2016 User's Guide IBM
Note Before using this information and the product it supports, read the information in Notices on page 37. This document applies to all ersions of IBM Enterprise Marketing Management products that incorporate email serices hosted by IBM and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2015, 2016. US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents Chapter 1. Oeriew of the UBX Toolkit 1 When to use the UBX toolkit......... 2 UBX Oeriew............ 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.... 4 Troubleshooting and support for UBX..... 5 Logging for the UBX Toolkit........ 6 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-leel authentication key. 9 Connecting the UBX Toolkit through a proxy serer 9 Encrypting the UBX Toolkit configurations.... 10 Creating a custom UBX Toolkit encryption key. 11 Remoing encryption from UBX Toolkit configuration properties......... 12 Chapter 3. Eent destination endpoints 13 Registering the eent destination endpoint.... 13 Downloading eents from UBX........ 15 JSON format for download eent data.... 16 JSON to TSV Header Mapping....... 17 Importing eent data into a database...... 19 Sample database script for database table creation............... 20 Eents data to database table mapping.... 20 Updating eent download......... 23 Custom eent downloads.......... 24 Chapter 4. Audience source endpoints 25 Registering as an audience source endpoint... 25 Audience generation........... 27 Audience registration........... 28 Registering audience data with UBX..... 29 Audience sharing by UBX users....... 30 Audience upload............ 30 Uploading audience data to UBX...... 31 Archiing the local copy of the audience data after upload................ 32 Chapter 5. Audience destination endpoints............. 33 Registering as an audience destination endpoint.. 34 Downloading audience data from UBX..... 35 Notices.............. 37 Trademarks.............. 39 Priacy Policy and Terms of Use Considerations.. 39 Copyright IBM Corp. 2015, 2016 iii
i IBM Uniersal Behaior Exchange Toolkit: User's Guide
Chapter 1. Oeriew of the UBX Toolkit The UBX Toolkit proides a way for locally installed applications, also called On Premise applications, to interact with IBM Uniersal Behaior Exchange (UBX). UBX creates a structure that supports dynamic relationships between independent software applications that register with UBX. Each UBX participating application can proide different types of marketing data and different ways to identify indiidual 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 eent data from UBX to a local application. The application appears in UBX as an eent subscriber (eent consumer) endpoint. C Download audience data from UBX to a local application. The application appears in UBX as an audience destination (audience consumer). To download the UBX Toolkit, go to IBM Uniersal Behaior Exchange Toolkit for IBM Marketing Software on IBM deeloperworks. Copyright IBM Corp. 2015, 2016 1
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 enironment. Installing the UBX Toolkit is an alternatie 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 oer HTTPS. Audience producers Use the UBX toolkit if a locally installed business solution can proide 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 aailable audience. You can schedule the UBX Toolkit to run periodically so that UBX users always hae access to updated audience data. Audience consumers If a locally installed application is a destination for audience data, use the UBX Toolkit to proide data when it is aailable in UBX. You can configure the toolkit to run as a scheduled job to automatically check for new audience data. Eent consumers If a locally installed business solution accepts eent data as an eent subscriber, use the UBX Toolkit to download the eent data and add it to a local database. The UBX Toolkit proides a sample mapping file that you can use to specify how the eent data is stored in the database. For example, you might use the imported eent data for custom reporting, analysis, and retargeting. UBX Oeriew IBM UBX is a cloud-based serice from IBM that you can use to selectiely exchange business data between arious 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 iew of their customers that is richer, better targeted, and more timely than any single application can proide. Participating IBM Commerce and IBM Business Partner solutions can quickly integrate data from arious IBM Commerce applications that they install in their own computer network or that they access as a web-based serice. They can also integrate data from selected independent companies who collaborate with IBM to make their customer interactions aailable through UBX. Marketing applications from IBM and selected IBM Business Partners access UBX automatically through arious 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. 2 IBM Uniersal Behaior Exchange Toolkit: User's Guide
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 proider, specify the data to exchange, and designate where to delier 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 Uniersal Behaior 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 administratie access to arious systems that are related to the applications that register with UBX. Before you begin, confirm that you hae established the required access priileges and logins. To establish access to UBX, use the UBX user interface and collaborate with the UBX Account Proisioning 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. Chapter 1. Oeriew of the UBX Toolkit 3
UBX access requirements To access UBX, IBM must create and proision 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 proision your UBX account, contact the UBX Account Proisioning team by email at ubxproisioning@wwpdl.net.ibm.com or request access to UBX at https://www-01.ibm.com/marketing/iwm/iwm/web/ signup.do?source=ibm-ubxproision. Your fully proisioned account includes the following elements. UBX user account, including credentials to log in to the UBX user interface. An endpoint-leel 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 arious UBX APIs. Each call must include an endpoint-leel authentication key that is specific to your account. You must proide the authentication key in the configuration properties for your installation of the UBX Toolkit. You create an endpoint-leel authentication key through the Endpoints tab in the UBX user interface. You must hae a alid login to UBX to access the Endpoints tab. Related tasks: Registering as an audience destination endpoint on page 34 Local access requirements Installing and operating the UBX Toolkit requires access to arious systems in your local network enironment. Establishing this access typically requires network or database administratie priileges. Before you begin, confirm that you hae established the following access priileges and logins. Administratie access to install and configure files on the serer where you install the UBX Toolkit. Contact your local system administrator for the required address and priileges. Administratie access to the database where you want to import eent data. Contact your database administrator for the required address and priileges. Resources and support for the UBX Toolkit IBM proides arious resources to support the UBX Toolkit. You can take adantage of installed, online, and educational resources. IBM deeloperworks is the home for the binary source files that are required to install the UBX Toolkit. 4 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Source files for the UBX Toolkit IBM proides the UBX Toolkit as a downloadable file archie that you can access on IBM deeloperworks. To download the UBX Toolkit, go to IBM Uniersal Behaior Exchange Toolkit for IBM Marketing Software on IBM deeloperworks. Documentation and training for UBX To learn more about how to use UBX to meet your business requirements, you can reiew product documentation and training resources that IBM has deeloped for UBX. View the current UBX product documentation in the IBM Knowledge Center. In the Knowledge Center, go to ExperienceOne > IBM Uniersal Behaior Exchange. Visit the IBM Learner portal to iew a series of educational ideos that sere as an Introduction to IBM Uniersal Behaior Exchange. Troubleshooting and support for UBX If you are haing a problem with UBX, IBM proides different ways to help you to resole the issue, depending on how you are accessing UBX. UBX Forum All UBX users can access the UBX Forum. You can post your question, reiew questions and answers that fellow UBX users hae 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://deeloper.ibm.com/answers/topics/ubx/ UBX Support UBX users who hae 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, isit the IBM Client Success Portal, which proides 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 serices like UBX, see the IBM Software as a Serice (SaaS) Support Handbook. Find the handbook at http://www.ibm.com/software/support/acceleratedalue/ 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 enironment. Go to the Endpoints tab and click Register new endpoint. For more information about registering an endpoint, see Registering endpoints. Chapter 1. Oeriew of the UBX Toolkit 5
Logging for the UBX Toolkit You can access the log files for the UBX Toolkit in the <$CU_HOME>/logs folder. Eent files that are processed successfully are stored by default in the <$CU_HOME>/AppData/downloads/dataProcessed folder. Eent files that the UBX Toolkit is not able to process are stored in the dataerror directory. If you encounter problems during eent data import, reiew the condition and structure of the files in the <$CU_HOME>/AppData/downloads/ dataerror folder to determine a course of action. 6 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Chapter 2. UBX Toolkit installation and configuration Installing the UBX toolkit To install the UBX Toolkit, download the toolkit file archie and install arious scripts and properties files on a serer in your local network enironment. Update default settings and property files to suit your local network requirements. The UBX Toolkit consists of arious property files and scripts that you install in your local network enironment and modify to satisfy your business requirements. The installation and configuration process proceeds as follows. 1. Download the UBX Toolkit from IBM deeloperworks as a compressed file archie. 2. Extract the archie to a directory on a local serer. Extracting the archie creates local directories that contain UBX Toolkit enironment files and configuration property files. 3. Modify UBX Toolkit enironment files to reflect paths in your local enironment. 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 inoles downloading the source file archie from IBM deeloperworks and then modifying enironment ariables. Before you begin Confirm that you hae rights to access and edit files on the serer where you want to install the UBX Toolkit. Confirm the locations of the JRE and JDBC database driers. Procedure 1. Download the UBX Toolkit files as a compressed archie and extract in a location on a serer in your local network enironment. The source files are aailable on IBM deeloperworks. Go to: IBM UBX Toolkit for IBM Marketing Software Click the link to download either of the following binary files. Windows: IBM_Uniersal_Behaior_Exchange_Toolkit_1.2_Windows.zip Linux or UNIX: IBM_Uniersal_Behaior_Exchange_Toolkit_1.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 enironment files. a. Depending on your operating system, copy and rename <CU_HOME>\bin\example_seten.bat or example_seten.shto seten.bat or seten.sh b. Modify the following ariables in the seten file: Copyright IBM Corp. 2015, 2016 7
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 drier for the database importer. 3. Install the configuration properties and logback files. Copy and rename the default example files that are proided 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 alues so that you can oerride 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. Connect to UBX through a web proxy serer. Encrypt the UBX Toolkit configurations. Endpoint registration with the UBX Toolkit The UBX Toolkit proides 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. Eent consumers: Chapter 3, Eent destination endpoints, on page 13 Audience producers: Chapter 4, Audience source endpoints, on page 25 Audience consumers: Chapter 5, Audience destination endpoints, on page 33 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. To share eent 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 proide the key to the endpoint proider. 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 8 IBM Uniersal Behaior Exchange Toolkit: User's Guide
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 proider registers with UBX. Generating an endpoint-leel authentication key As a UBX user, you generate an endpoint-leel authentication key in the UBX user interface. You can enter an endpoint-leel 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 proide the authentication key as a alue in the UBX Toolkit configuration. Running the endpoint registration script with the toolkit makes an API call that proides the authentication key to UBX on behalf of the endpoint proider. 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 proider. 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 sae it. What to do next Enter the authentication key as a alue in the UBX Toolkit configuration. The configuration property that you populate depends on the type of endpoint that you are registering. Connecting the UBX Toolkit through a proxy serer 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 serer. About this task The proxy serer must support HTTPS. The config.properties configuration file includes optional properties that you must configure if you plan to connect through a web proxy serer. To use a web proxy serer, you must proide the proxy serer address. For authenticated access to the proxy, you must also proide the required user name and password. Chapter 2. UBX Toolkit installation and configuration 9
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 Serer Host Settings section, modify the following properties. Comments in the file proide guidance for updating each property. proxy.url Specify the URL for the web proxy serer. proxy.username Specify the user name that is used to access the web proxy serer. Leae blank if authenticated access is not required. proxy.password Specify the password that is used to access the web proxy serer. Leae blank if authenticated access is not required. 3. Sae config.properties and erify the connection. Encrypting the UBX Toolkit configurations When you install the UBX Toolkit, configuration settings, including passwords, are isible in properties files. To encrypt certain settings so that sensitie information is not isible, 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 enironment by defining a custom encryption key. Defining a custom encryption key is optional. Howeer, 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 alues in jdbc.properties and config.properties. The script encrypts only alues that include the terms: authkey, password, secret, refresh, or access. When you run the encryptconfig script, the script replaces the displayed alues for these settings with a string of encrypted characters. Note: Encrypting configurations with the encryptconfig script does not encrypt the proxy serer settings if you encrypt the toolkit configuration settings. Howeer, if the proxy.password property contains a alue, the alue is encrypted. File jdbc.properties config.properties Property jdbc.password: Password for the database user. ubx.endpoint.authentication.key: The authentication key for registering an endpoint and accessing UBX APIs. 10 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Encrypting the alue of a configuration property does not preent you from changing the alue. Howeer, each time that you change the alue, you must run encryptconfig again to encrypt the new alue. You can encrypt alues 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). 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 relatie path to CU_HOME>/conf/<properties file>. Example: <CU_HOME>/bin/encryptConfig.sh -f <CU_HOME>/conf/ config.properties The script encrypts alues only in the property file that you specify with the -f option. Creating a custom UBX Toolkit encryption key To apply increased local control oer the encryption of sensitie configuration alues, you can create a custom encryption key. This task is optional, but does proide 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 sensitie configuration alues. If you decide to create a custom encryption key, you must perform this procedure before you run the encryptconfig script. Define the alue 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 seten file. Note: If you change the alue of the Encryption Key File, you must remoe 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 sae the file as a text file. The file that you create is the Encryption Key File. Sae the file in a folder outside of the bin directory. Restrict access to the directory in which you sae the file. 2. In the bin directory of <CU_HOME>, edit the seten file to specify the path to the Encryption Key File. Modify the ENCRYPTION_KEY_FILE setting, as follows. Windows (seten.bat): set ENCRYPTION_KEY_FILE="- com.ibm.emm.integration.security.encryptionkeyfile=<path to file>\<encryptionkeyfile>" Chapter 2. UBX Toolkit installation and configuration 11
UNIX or Linux (seten.sh): ENCRYPTION_KEY_FILE=com.ibm.emm.integration.security.EncryptionKeyFile=<path to file>/<encryptionkeyfile> Results The new custom password is used to encrypt alues in jdbc.properties and authentication.key in config.properties. What to do next Run the encryptconfig script to encrypt the configuration settings. Remoing encryption from UBX Toolkit configuration properties Some situations require that you remoe the encryption from encrypted properties. For example, to change the alue for the Encryption Key File, you must remoe encryption from all currently encrypted alues before you can proceed. About this task Encrypted alues can be found in jdbc.properties and config.properties. The encrypted alues appear as random strings. Procedure 1. In jdbc.properties and config.properties, locate the encrypted alues. Replace each encrypted alue with its correct unencrypted alue. 2. Sae the file. On Windows, if you were using a custom encryption key and then stopped using the key, close all command prompts. Results After you complete this task, the configuration alues appear without encryption. 12 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Chapter 3. Eent destination endpoints To use the UBX Toolkit to download eent data from UBX, update certain toolkit configurations and run arious scripts in the bin folder of the UBX Toolkit installation. Some scripts run as scheduled jobs. Eent destination endpoints are also called eent subscribers or eent consumers. Run the UBX Toolkit eent consumer scripts to perform the following tasks. Register the eent destination endpoint Download eent data from UBX Import eent data into a specified local database The scripts call UBX public APIs. Before you begin, contact IBM to erify the URL that IBM assigned to your UBX account for submitting API calls. The UBX Toolkit proides an example mapping file that you can use to specify how to add downloaded eent data into a local database. Modify the mapping file as necessary to match your local tables. Adding the eent data to a local table makes it aailable for analysis and contact retargeting. Registering the eent destination endpoint The application that receies eent 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 hae a UBX user account. You can contact the IBM Account Proisioning team to erify your UBX account details. About this task Run the registerendpoint script to register the application as a UBX endpoint. Registering the endpoint makes it isible in the UBX user interface and proides UBX with the information that it needs to download the eent data. You need to run the registerendpoint script only once. Copyright IBM Corp. 2015, 2016 13
This script calls the UBX 1/endpoint API to register the endpoint as a subscriber. To register the endpoint, the script must proide the authentication key. After the endpoint is registered, you must log in to the UBX UI to select which eent types to subscribe to before running scripts for downloading eent data or importing the data into local tables. Procedure Log in to the UBX user interface to create an authentication key. In config.properties, enter the key as the alue for ubx.endpoint.authentication.key Verify the following settings in config.properties: ubx.eent.consumer.endpoint.name: name for the endpoint that receies eent data ubx.eent.consumer.endpoint.desc: brief description for the endpoint that receies eent data ubx.eent.consumer.endpoint.proider: name of the endpoint proider as it should appear in the UBX user interface. ubx.eent.consumer.endpoint.authentication.key: the authentication key for registering the endpoint and accessing APIs. ubx.api.serice.url=http://<serer-name>:<port>. The serice URL for UBX public APIs. The path must include the serer and port that IBM assigns to your UBX account. Note: If you are upgrading from an earlier ersion of the UBX Toolkit, notice that the property names hae changed. Update the property names in your UBX Toolkit installation to match the names that are proided here. From the $CU_HOME/bin folder, run registerendpoint.bat or registerendpoint.sh. Specify the -t option as -t eentconsumer. 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. 14 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Select the eent types to which you want to subscribe. Configure an eent subscription between the eent source endpoint and the eent destination endpoint. For more information about how to define an eent subscription, see the IBM Uniersal Behaior Exchange User s Guide. Downloading eents from UBX The UBX Toolkit proides the eentsdownload script to download eent data from UBX to a to a file in your local enironment. You can run the script manually or as a scheduled job. Before you begin Log in to UBX to confirm that you hae configured an eent subscription to the destination endpoint. About this task The eentsdownload script calls the 1/eentfiles API to download the eents files. Calling the API initiates a secure file download. The eent data is downloaded in JSON format to the directory that you specify in the local.download.dir property 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, erify the following settings in the config.properties file. ubx.api.serice.url=http://<serer-name>:<port>. The serice URL for UBX public APIs. The path must include the serer and port that IBM assigns to your UBX account. Chapter 3. Eent destination endpoints 15
ubx.endpoint.eentfiles.numfilesinlist=<number> The number of files in the list returned when the eentfiles API is called. local.download.dir=%cu_home%/appdata/downloads. The directory where the downloaded files are saed. dbinsert.keep.processed.files=true 2. From the $CU_HOME/bin folder, run eentsdownload.bat [-c <config properties file>] or eentsdownload.sh [-c <config properties file>] By default, UBX downloads the eent 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 oerride 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 eent data from UBX in JSON format. When the eent data has finished downloading, the eentsdownload script conerts JSON objects to TSV format. After the eentsdownload script finishes downloading the eent data, the eent files are deleted from the UBX serer. JSON format for download eent data The UBX eents are serialized JSON objects in the downloaded files. Each file can contain data for multiple eents. The UBX Toolkit downloads eent data in the following JSON format. { } "proider" : "<string>", "source" : "<string>", "channel" : "<string>", "x1id" : "<string>", "identifiers" : [ { "name" : "<string>","alue" : "<string>" }, { "name" : "<string>","alue" : "<string>" } ], "eents" : [ { "code" : "<string>", "timestamp" : "<timestamp>", "attributes" : [ {"name" : "<string>", "alue" : "<alue>", "type" : "<type>" }, {"name" : "<string>", "alue" : "<alue>", "type" : "<type>" } ] } ] See the IBM Uniersal Behaior Exchange Integration Guide for more information about how UBX proides eent data in JSON format to eent subscribers. 16 IBM Uniersal Behaior Exchange Toolkit: User's Guide
JSON to TSV Header Mapping After it downloads the eent data, the eentsdownload 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 eent types, but all identifiers and attributes are added to the header. The data alue of the identifier or attribute that does not belong to an eent 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 proider source channel x1id Identifiers[i].name eent.code eent.timestamp eent.attributes[i].alue TSV header proider source channel x1id identifiers_<string_alue> eent_code eent_timestamp eent_attributes_<string_alue> The following JSON sample and table illustrate how UBX maps the JSON data to a tab-separated file. Chapter 3. Eent destination endpoints 17
{ } "proider": "IBM", "source" : "Digital Analytics", "channel": "Web", "x1id": "81147632-a3fe-43a5-b0c8-6289ca9302bc" "identifiers": [ { "name": "email", "alue": "slmoore@example.com" }, { "name": "DA_cookie_id", "alue": "098098-adfsfd-9323ad-78sdfs" } ], "eents": [ { "code" : "cartpurchase", "timestamp": "2015-03-18T13:55:06+00:00", "attributes": [ { "name": "productid", "alue": "d12345" }, { "name": "productname", "alue": "Widget ABC" }, { "name": "baseprice", "alue": "200.00", "type" : "number" }, { "name": "quantity", "alue": "2", "type" : "number" } ] }, { "code" : "cartpurchase", "timestamp": "2015-03-18T13:55:06+00:00", "attributes": [ { "name": "productid", "alue": "d123465" }, { "name": "productname", "alue": "Widget 123" }, { "name": "baseprice", "alue": "13.00", "type" : "number" }, { "name": "quantity", "alue": "1", "type" : "number" } ] } ] Stucture of the corresponding TSV file. TSV Header Eent 1 Eent 2 Eent <n> proider 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 eent_code cartpurchase cartpurchase eent_timestamp 2015-03-18T13:55:06+00:00 2015-03-18T14:08:36+00:00 eent_attribute_productid d12345 d123456 eent_attribute_productname Widget ABC Widget 123 eent_attribute_baseprice 200.00 13.00 eent_attribute_quantity 2 1 You can use the TSV file as the source file for importing the eents data into a local database. 18 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Importing eent data into a database Run the eentsimport script to add eent data from the TSV file that is created by the eentsdownload 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 proides a mapping file that you use to specify how the eent data is added to the database. A The Eents Downloader calls the UBX HTTP API to download the eent data from UBX and stores the data as a tab-separated (TSV) file in the client file system. UBX proides eents files in JSON format. The Eents Downloader component of the UBX Toolkit conerts the JSON to a tab-separated alue (TSV) format. The JSON data and the.ts file are stored on the client. B The Eents DBImporter processes the TSV file and inserts indiidual eents into the respectie database tables, based on the eent type. C Use the sample mapping file to specify how the eents data is stored in the local database. Procedure Run eentsimport.bat -m <mapping file> -i <source TSV file> -f <source directory> [-c <config properties file> -j <jdbc properties file> For Linux or UNIX, run eentsimport.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 EentsToDBMapping.xml. Chapter 3. Eent destination endpoints 19
-i <input TSV file> Path to the input TSV file. If you specify a single.ts file with the -i option, only that file is processed and the -f option will be ignored, een 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.ts files in that directory are imported. Optional parameters: -c <alternate config.properties> Use to define alternate configurations. When specified, properties in this file oerride 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 oerride the default configuration. Specify the path to the alternate location and file name. Do not rename the default properties file. Results After the eentsimport script imports the eent data to the specified database, the script moes 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 proides a sample SQL script for creating the local database tables that you can use to store downloaded eents data. In the $CU_HOME/ddl directory, the UBX Toolkit proides 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 ersion of the UBX Toolkit, you can use upgrade scripts that are proided in the ddl directory. The toolkit also proides an example mapping file to match eent data to the field names in the tables that you create with the sample EentToDBTableMapping.xml file. Eents data to database table mapping The UBX Toolkit proides the EentToDBTableMapping.xml file. You can use this file to map the fields in each eent type to the columns in the eent 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 eent codes to the same database tables. Eent identifiers or attributes that are not mapped are ignored. The EentToDBTableMapping.xml proides examples for the following types of IBM recognized eents. Email eents 20 IBM Uniersal Behaior Exchange Toolkit: User's Guide
CartPurchase Cart Purchase Item Cart Abandonment Cart Abandonment Item Conersion Abandoned conersion Searched site Product View Visited site Email Sent Email Open Email Click Email Bounce SMS eents sentsms interactedsms multistepsms Mobile push eents application/appinstalled application/appuninstalled application/sessionstarted application/sessionended application/uipushenabled application/uipushdisabled simplenotification/appopened simplenotification/urlclicked The following example of how a recognized eent is represented in the sample mapping file is based on the Cart Purchase recognized eent. <?xml ersion="1.0"?> <EentToDBTableMappings> <TableMapping> <EentCode>ibmcartPurchase</EentCode> <Table>UBX_IBMCARTPURCHASE</Table> <Name>Proider</Name> <EentField>proider</EentField> </Column> <Name>EndpointSource</Name> <EentField>source</EentField> </Column> <Name>Channel</Name> <EentField>channel</EentField> </Column> <Name>X1ID</Name> <EentField>x1id</EentField> </Column> <Name>Email</Name> Chapter 3. Eent destination endpoints 21
<EentField>identifier_email</EentField> </Column> <Name>Cookie</Name> <EentField>identifier_cookieid</EentField> </Column> <Name>EentCode</Name> <EentField>eent_code</EentField> </Column> <Name>EentTimeStamp</Name> <EentField>eent_timestamp</EentField> </Column> <Name>EentNameSpace</Name> <EentField>eent_namespace</EentField> </Column> <Name>EentVersion</Name> <EentField>eent_ersion</EentField> </Column> <Name>EentName</Name> <EentField>eent_name</EentField> </Column> <Name>EentDescription</Name> <EentField>eent_description</EentField> </Column> <Name>OrderID</Name> <EentField>eent_attribute_orderid</EentField> </Column> <Name>InteractionID</Name> <EentField>eent_attribute_interactionid</EentField> </Column> <Name>OrderSubTotal</Name> <EentField>eent_attribute_ordersubtotal</EentField> <EentFieldType>number</EentFieldType> </Column> <Name>OrderShipping</Name> <EentField>eent_attribute_ordershipping</EentField> <EentFieldType>number</EentFieldType> </Column> <Name>OrderDiscount</Name> <EentField>eent_attribute_orderdiscount</EentField> <EentFieldType>number</EentFieldType> </Column> <Name>OrderPromo</Name> <EentField>eent_attribute_orderpromo</EentField> <EentFieldType>number</EentFieldType> </Column> <Name>OrderTax</Name> <EentField>eent_attribute_ordetax</EentField> <EentFieldType>number</EentFieldType> </Column> <Name>OrderTotal</Name> <EentField>eent_attribute_ordetotal</EentField> <EentFieldType>number</EentFieldType> 22 IBM Uniersal Behaior Exchange Toolkit: User's Guide
</Column> <Name>Currency</Name> <EentField>eent_attribute_currency</EentField> </Column> <Name>ShippingType</Name> <EentField>eent_attribute_shippingtype</EentField> </Column> <Name>Quantity</Name> <EentField>eent_attribute_quantity</EentField> <EentFieldType>number</EentFieldType> </Column> <Name>ProductList</Name> <EentField>eent_attribute_productlist</EentField> </Column> </TableMapping> Related tasks: Updating eent download Updating eent download You can use the UBX Toolkit to download eents 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 eents you must update the configuration of your UBX destination endpoint. If you add eent data to a local SQL database using the example mapping file that the UBX Toolkit proides, 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 eents. After you update the eent registration for the subscribing endpoint, the eentsdownload script processes the new eent files. For more information about updating your endpoint subscriptions, see the IBM Uniersal Behaior Exchange User s Guide. 2. If you use the UBX Toolkit to add eent data to a local database, complete the following steps. a. Update the local database tables to receie the new eent data. b. Update EentToDBTableMapping.xml to include a new section that maps fields from the new eent to the new fields in the database. Related concepts: Eents data to database table mapping on page 20 Chapter 3. Eent destination endpoints 23
Custom eent downloads To use the UBX Toolkit to download modified eents or eents other than the eents that are supported by default, you must update your UBX endpoint subscriptions. If you add eent data to a local SQL database, you must update the mapping file and the database tables. The example mapping file that is proided with the UBX Toolkit is based on the standard definition of specific recognized eents. IBM recognized eents contain some attributes that are optional. Depending on the source of the eent data, the downloaded eents might not contain data for all possible attributes. To download eent data that does not contain all of the standard eent attributes, you must remoe 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 eent types other than the default eents. To download eent data for recognized eents other than the eents specified in the mapping file, you must add a section to the mapping file that defines the added eent data. 24 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Chapter 4. Audience source endpoints Use the UBX Toolkit to make audience data generated in a locally installed application aailable for syndication by UBX users. The process inoles 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 aailable in UBX inoles the following steps. Register the audience producer endpoint. Run the registerendpoint.bat/sh script. Create an audience file in the audience producer application. Create the file as a CSV file. Register the CSV file as an aailable audience in UBX. Run audienceregister.bat/sh as a scheduled job. Upload the aailable 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 proides 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 hae a UBX user account. You can contact the IBM Account Proisioning team to erify your UBX account details. About this task Run the registerendpoint script to register the application as a UBX endpoint. Registering the endpoint makes it isible in the UBX user interface and proides UBX with the information that it needs to download the eent 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. Copyright IBM Corp. 2015, 2016 25
This script calls the UBX 1/endpoint API to register the endpoint as an audience source. To register the endpoint, the script must proide an endpoint-leel authentication key. Procedure 1. Log in to the UBX user interface to create an authentication key. In config.properties, enter the key as the alue for ubx.endpoint.authentication.key 2. Verify the following settings in config.properties: ubx.api.serice.url=https://api.adm01.com. Web address URL for the UBX API serice. ubx.audience.producer.endpoint.name=<name of the endpoint that produces the audience data> Displays in the UBX user interface. (Required) ubx.audience.producer.endpoint.desc=<brief description of the audience producer endpoint> The description displays in the UBX user interface. ubx.audience.producer.endpoint.proider=<endpoint proider name> Displays in the UBX user interface. (Required) ubx.audience.producer.endpoint.authentication.key=<endpoint-leel authentication key> Generate in the UBX user interface. (Required) ubx.audience.producer.endpoint.marketingdb.name=<name of the database that proides the audience data> 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). For more information about identifiers, see Suggested unique identifier types. Note: The identifier types that are specified in the destination audience must match the types that are specified for the source audience. ubx.audience.producer.endpoint.marketingdb.attributes= <attrib_name> <attrib_type> Comma-separated list of audience attributes. Default attribute data type: string. 26 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Audience generation ubx.audience.producer.audiencepublishfolder=%<home_directory>%/ <directory>/<audience_folder> Directory that contains the CSV file that proides 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 alue 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. Reiew the endpoint details pages to confirm that the descriptions, identifiers, and attributes are set correctly. Use features in the audience source application to generate the audience data that you want to make aailable 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 indiiduals 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. Chapter 4. Audience source endpoints 27
Audience registration B Sae the segment that defines the audience as a CSV file in the following format: UBXSegment_<AudienceName>.cs Do not include spaces in the file name. C You must sae the application output file in a directory that you specify in the ubx.audience.producer.audiencepublishfolder property in the config.properties file. You must sae the CSV file with the required naming conention 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. Registering an audience with UBX enables the UBX Toolkit to recognize changes in the audience data that is aailable 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 saed in a CSV file and saed 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 hae resered for audience data. The script looks for new CSV files. The audienceregister script ignores files that do not follow the required naming conention. If you do not sae audience data to this directory as UBXSegment_<AudienceName>.cs, 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 aailable. The script scans the folder that is resered for published CSV files to determine if new CSV files are present. If a CSV file with the name format in UBXSegment_< 28 IBM Uniersal Behaior Exchange Toolkit: User's Guide