IBM Uniersal Behaior Exchange Toolkit Release 16.1.2 April 8, 2016 User's Guide IBM
Note Before using this information and the product it supports, read the information in Notices on page 39. 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.... 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-leel authentication key. 9 Requesting a UBX account-leel authentication key................ 9 Connecting the UBX Toolkit through a proxy serer 10 Encrypting the UBX Toolkit configurations.... 10 Creating a custom UBX Toolkit encryption key 12 Remoing encryption from UBX Toolkit configuration properties......... 12 Chapter 3. Eent destination endpoints 15 Registering the eent destination endpoint.... 15 Downloading eents from UBX........ 17 JSON format for download eent data.... 18 JSON to TSV Header Mapping....... 19 Importing eent data into a database...... 21 Sample database script for database table creation............... 22 Eents data to database table mapping.... 22 Updating eent download......... 25 Custom eent downloads.......... 26 Chapter 4. Audience source endpoints 27 Registering as an audience source endpoint... 27 Audience 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 Archiing 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 Priacy Policy and Terms of Use Considerations.. 41 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. An account-leel UBX authentication key. This key is required for connecting an audience consumer endpoint to UBX. 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 authentication key that is specific to your account or to your UBX endpoint registration request. UBX recognizes and requires endpoint-leel authentication keys and account-leel authentication keys. You must proide the authentication keys 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. When IBM creates your UBX user account, it creates an account-leel authentication key. The account-leel authentication key is different from the endpoint-leel authentication key that you create through the Endpoints tab in UBX. The account-leel authentication key enables endpoint proiders to take actions on behalf of multiple UBX user accounts that syndicate connection to the endpoint. To request the account-leel authentication key that IBM created for your UBX account, send a request by email to the UBX Proisioning team at ubxproisioning@wwpdl.net.ibm.com. Related tasks: Registering as an audience destination endpoint on page 36 Requesting a UBX account-leel authentication key on page 9 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. 4 IBM Uniersal Behaior Exchange Toolkit: User's Guide
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. 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 Support can help you to resole the issue. 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. To contact the UBX Support team directly, send email to: ubx@us.ibm.com. 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. Chapter 1. Oeriew of the UBX Toolkit 5
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 15 Audience producers: Chapter 4, Audience source endpoints, on page 27 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 leel and at the UBX account leel. 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 8 IBM Uniersal Behaior Exchange Toolkit: User's Guide
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 proider registers with UBX. When IBM proisions UBX endpoint proider accounts, it generates account-leel authentication keys that the endpoint requires to operate across multiple UBX user accounts. Registering audience consumer endpoints with the UBX Toolkit requires an account-leel authentication key. 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. Requesting a UBX account-leel authentication key In some cases, you must proide an account-leel authentication key as a UBX Toolkit configuration property to use the toolkit to register an endpoint. You must contact IBM to request an account leel authentication key. Chapter 2. UBX Toolkit installation and configuration 9
Procedure To request an account-leel authentication key, contact the UBX Account Proisioning team by email at ubxproisioning@wwpdl.net.ibm.com. 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. Related concepts: UBX authentication key requirements on page 4 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. 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. 10 IBM Uniersal Behaior Exchange Toolkit: User's Guide
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. 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. Chapter 2. UBX Toolkit installation and configuration 11
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>" 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. 12 IBM Uniersal Behaior Exchange Toolkit: User's Guide
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. Chapter 2. UBX Toolkit installation and configuration 13
14 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 15
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. 16 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 17
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. 18 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 19
{ } "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. 20 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 21
-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 22 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 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> <Column> <Name>Proider</Name> <EentField>proider</EentField> </Column> <Column> <Name>EndpointSource</Name> <EentField>source</EentField> </Column> <Column> <Name>Channel</Name> <EentField>channel</EentField> </Column> <Column> <Name>X1ID</Name> <EentField>x1id</EentField> </Column> <Column> <Name>Email</Name> <EentField>identifier_email</EentField> Chapter 3. Eent destination endpoints 23
</Column> <Column> <Name>Cookie</Name> <EentField>identifier_cookieid</EentField> </Column> <Column> <Name>EentCode</Name> <EentField>eent_code</EentField> </Column> <Column> <Name>EentTimeStamp</Name> <EentField>eent_timestamp</EentField> </Column> <Column> <Name>EentNameSpace</Name> <EentField>eent_namespace</EentField> </Column> <Column> <Name>EentVersion</Name> <EentField>eent_ersion</EentField> </Column> <Column> <Name>EentName</Name> <EentField>eent_name</EentField> </Column> <Column> <Name>EentDescription</Name> <EentField>eent_description</EentField> </Column> <Column> <Name>OrderID</Name> <EentField>eent_attribute_orderid</EentField> </Column> <Column> <Name>InteractionID</Name> <EentField>eent_attribute_interactionid</EentField> </Column> <Column> <Name>OrderSubTotal</Name> <EentField>eent_attribute_ordersubtotal</EentField> <EentFieldType>number</EentFieldType> </Column> <Column> <Name>OrderShipping</Name> <EentField>eent_attribute_ordershipping</EentField> <EentFieldType>number</EentFieldType> </Column> <Column> <Name>OrderDiscount</Name> <EentField>eent_attribute_orderdiscount</EentField> <EentFieldType>number</EentFieldType> </Column> <Column> <Name>OrderPromo</Name> <EentField>eent_attribute_orderpromo</EentField> <EentFieldType>number</EentFieldType> </Column> <Column> <Name>OrderTax</Name> <EentField>eent_attribute_ordetax</EentField> <EentFieldType>number</EentFieldType> </Column> <Column> <Name>OrderTotal</Name> <EentField>eent_attribute_ordetotal</EentField> <EentFieldType>number</EentFieldType> </Column> 24 IBM Uniersal Behaior Exchange Toolkit: User's Guide
<Column> <Name>Currency</Name> <EentField>eent_attribute_currency</EentField> </Column> <Column> <Name>ShippingType</Name> <EentField>eent_attribute_shippingtype</EentField> </Column> <Column> <Name>Quantity</Name> <EentField>eent_attribute_quantity</EentField> <EentFieldType>number</EentFieldType> </Column> <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 22 Chapter 3. Eent destination endpoints 25
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. 26 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 27
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 forubx.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) ubx.audience.producer.endpoint.marketingdb.attributes= <attrib_name> <attrib_type> Comma-separated list of audience attributes. Default attribute data type: string. ubx.audience.producer.audiencepublishfolder=%<home_directory>%/ <directory>/<audience_folder> Directory that contains the CSV file that proides the audience data. 28 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Audience generation 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. 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. Chapter 4. Audience source endpoints 29
Audience registration 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_< AudienceName>.cs 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. 30 IBM Uniersal Behaior Exchange Toolkit: User's Guide
C The script checks the audience name against the list of current audiences in UBX. The script calls GET /1/endpoint?segment=true&source=true &loadsegments=true&endpointid={endpointid} to get a list of existing audiences for the endpoint. If the audience name matches an existing audience name, it updates the audience. Otherwise, the audienceregister script creates a new audience. D After the script processes all CSV files, it calls the UBX API to update or add the audiences. The API call must specify the endpoint ID of the endpoint that acts as the source of the audience data. To update audiences, the script calls PUT /1/endpoint/{endpointid}/segments To register a new audience, the script calls POST /1/endpoint/{endpointid}/ segments After it completes the API calls, the script creates the published folder as a sub-folder to the directory for audience data that you specified with the ubx.audience.producer.audiencepublishfolder configuration property. The script moes the processed CSV files to the published folder. Registering audience data with UBX Run the audienceregister script as a scheduled job to proide 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 hae 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 moes 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 destination endpoint. The process is called audience sharing. Chapter 4. Audience source endpoints 31
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 proide 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 aailable 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 Uniersal Behaior 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 receie the data from the source endpoint. As the audience source endpoint, you must make API calls to UBX to determine when such jobs hae 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 aoid delays in responding to the user requests. A The audienceupload script calls GET /1/jobs/ SEGMENT_EXPORT?endpointId={endpointId}&status={status} with the status set to WAITING_TO_RECIEVE_DATA to get a list of jobs that are aailable to receie uploaded audience data. 32 IBM Uniersal Behaior Exchange Toolkit: User's Guide
B If a job is returned, the segment upload script uses the audience name to locate the CSV file that proides the audience data. If the required CSV file exists, the script calls POST /1/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 Uniersal Behaior 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 aailable to UBX users for download to an audience destination endpoint. Procedure 1. Specify timeout for missing audience data. Enter a alue, 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 oerride the toolkit default configuration. Specify the path to the alternate location and file name. Do not rename the default properties file. Chapter 4. Audience source endpoints 33
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 arious analytical and retargeting actiities. Archiing the local copy of the audience data after upload After the upload script finishes, the UBX Toolkit can either moe the CSV file to a new location or leae it in place for possible reuse. About this task The UBX Toolkit creates the Published folder and the Deliered folder to store the CSV files that are created to proide audience data for upload to UBX. By default, after it uploads the audience data to UBX, the UBX Toolkit moes the CSV file to the Deliered folder. Howeer, you can change a configuration setting to keep the CSV file in the Published folder. Procedure In configuration.properties, indicate where to locate the CSV file after uploading data to UBX by setting the following property. To moe the CSV file that defines the audience data to the Deliered folder, set ubx.audience.producer.moefiletodelieredfolder to true. This is the default behaior. The script calls DELETE /1/endpoint/{endpointid}/segments/{segmented} to delete the audience data after copying the CSV file to the Deliered folder. To keep the CSV file in the Published folder and aailable for reuse, set the property alue to false. Keeping the CSV file in the Published folder allows you to reuse the audience data. 34 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Chapter 5. Audience destination endpoints Use the UBX Toolkit to download audience data that is aailable in UBX to a locally installed application. The process inoles updating toolkit configurations and running scripts to identify and download the audience data from UBX to your local enironment. Using the UBX Toolkit to download audience data from UBX inoles the following steps. Register the audience destination endpoint. Run the registerendpoint.bat/sh script. Download aailable audience data from UBX to a locally installed application. UBX users request the audience download in the UBX user interface. Upon receipt of the request, UBX creates the audience download job. Run the audiencedownload.bat/sh script repeatedly as a scheduled task to detect new download jobs as UBX creates them. You can also run the script manually. When UBX users share an audience through the Audiences tab in the UBX user interface, UBX creates the job that it will use to receie the data from the source endpoint. As the audience destination endpoint, you make API calls to UBX to determine when such jobs hae 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 aoid delays in responding to the user requests. The following diagram illustrates the oerall 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 /1/jobs/ SEGMENT_EXPORT?endpointId={endpointId}&status={status} with the status, READY_FOR_DOWNLOAD, to get a list of jobs that hae new audience data aailable. B If a job is ready to download audience data, the audience download script calls GET /1/jobs/{jobid}/segmentDataFiles/{filepath} to download the data. Copyright IBM Corp. 2015, 2016 35
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>.cs. When the download finishes, the download script calls PUT /1/jobs/{jobid}/ status/{status} with the job status: COMPLETE. Registering as an audience destination endpoint The application that receies 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 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. This script calls the UBX 1/endpoint API to register the endpoint as an audience destination. To register the endpoint, the script must proide an endpoint-leel authentication key and an account-leel authentication key. Generate the endpoint-leel authentication in the UBX user interface. Contact IBM to get the required account-leel 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 alue for ubx.endpoint.authentication.key 2. Contact the IBM Account Proisioning team by email at ubxproisioning@wwpdl.net.ibm.com to request the account-leel authentication key for your UBX account. 3. Verify the following settings in config.properties: ubx.api.serice.url=https://api.adm01.com. Web address URL for the UBX API serice. ubx.accountleel.authentication.key=<account-leel authentication key> (Proided by IBM). 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) ubx.audience.consumer.endpoint.desc=<brief description of the audience destination endpoint> The description displays in the UBX user interface. 36 IBM Uniersal Behaior Exchange Toolkit: User's Guide
ubx.audience.consumer.endpoint.proider=<endpoint proider name> Displays in the UBX user interface. (Required) ubx.audience.consumer.endpoint.authentication.key=<endpoint-leel authentication key> Generate in the UBX user interface. (Required) ubx.audience.consumer.endpoint.marketingdb.name=<name of database that receies the audience data> 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) ubx.audience.consumer.endpoint.marketingdb.attributes= <attrib_name> <attrib_type> Comma-separated list of audience attributes. Default attribute data type: string. ubx.audience.consumer.audiencedownloadfolder=%<home_directory>%/ <directory>/<audience_folder>directory that contains the CSV file that the download script creates to receie 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 alue 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. Reiew 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 aailable 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 archie preiously downloaded audience data before downloading the new data. Indicate your choice as the alue for the following configuration property in config.properties. ubx.audience.consumer.archiedownloadedaudiences=true false Default: true When true, UBX saes any preiously downloaded data files to a folder named archie as a sub-folder to the folder that you specified with the Chapter 5. Audience destination endpoints 37
ubx.audience.consumer.audiencedownloadfolder configuration property. To establish a unique file name for the archied 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 oerride the toolkit default configuration. Specify the path to the alternate location and file name. Do not rename the default properties file. 38 IBM Uniersal Behaior Exchange Toolkit: User's Guide
Notices This information was deeloped for products and serices offered in the U.S.A. IBM may not offer the products, serices, or features discussed in this document in other countries. Consult your local IBM representatie for information about the products and serices currently aailable in your area. Any reference to an IBM product, program, or serice is not intended to state or imply that only that IBM product, program, or serice may be used. Any functionally equialent product, program, or serice that does not infringe any IBM intellectual property right may be used instead. Howeer, it is the user's responsibility to ealuate and erify the operation of any non-ibm product, program, or serice. IBM may hae patents or pending patent applications coering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drie Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan, Ltd. 19-21, Nihonbashi-Hakozakicho, Chuo-ku Tokyo 103-8510, Japan The following paragraph does not apply to the United Kingdom or any other country where such proisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-ibm websites are proided for conenience only and do not in any manner sere as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk. Copyright IBM Corp. 2015, 2016 39
IBM may use or distribute any of the information you supply in any way it beliees appropriate without incurring any obligation to you. Licensees of this program who wish to hae information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation B1WA LKG1 550 King Street Littleton, MA 01460-1250 U.S.A. Such information may be aailable, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material aailable for it are proided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equialent agreement between us. Any performance data contained herein was determined in a controlled enironment. Therefore, the results obtained in other operating enironments may ary significantly. Some measurements may hae been made on deelopment-leel systems and there is no guarantee that these measurements will be the same on generally aailable systems. Furthermore, some measurements may hae been estimated through extrapolation. Actual results may ary. Users of this document should erify the applicable data for their specific enironment. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly aailable sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objecties only. All IBM prices shown are IBM's suggested retail prices, are current and are subject to change without notice. Dealer prices may ary. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of indiiduals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on arious operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of deeloping, using, marketing or distributing application programs conforming to the application programming interface for the operating 40 IBM Uniersal Behaior Exchange Toolkit: User's Guide
platform for which the sample programs are written. These examples hae not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, sericeability, or function of these programs. The sample programs are proided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs. If you are iewing this information softcopy, the photographs and color illustrations may not appear. Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and serice names might be trademarks of IBM or other companies. A current list of IBM trademarks is aailable on the Web at Copyright and trademark information at www.ibm.com/legal/copytrade.shtml. Priacy Policy and Terms of Use Considerations IBM Software products, including software as a serice solutions, ("Software Offerings") may use cookies or other technologies to collect product usage information, to help improe the end user experience, to tailor interactions with the end user or for other purposes. A cookie is a piece of data that a web site can send to your browser, which may then be stored on your computer as a tag that identifies your computer. In many cases, no personal information is collected by these cookies. If a Software Offering you are using enables you to collect personal information through cookies and similar technologies, we inform you about the specifics below. Depending upon the configurations deployed, this Software Offering may use session and persistent cookies that collect each user's user name, and other personal information for purposes of session management, enhanced user usability, or other usage tracking or functional purposes. These cookies can be disabled, but disabling them will also eliminate the functionality they enable. Various jurisdictions regulate the collection of personal information through cookies and similar technologies. If the configurations deployed for this Software Offering proide you as customer the ability to collect personal information from end users ia cookies and other technologies, you should seek your own legal adice about any laws applicable to such data collection, including any requirements for proiding notice and consent where appropriate. IBM requires that Clients (1) proide a clear and conspicuous link to Customer's website terms of use (e.g. priacy policy) which includes a link to IBM's and Client's data collection and use practices, (2) notify that cookies and clear gifs/web beacons are being placed on the isitor's computer by IBM on the Client's behalf along with an explanation of the purpose of such technology, and (3) to the extent required by law, obtain consent from website isitors prior to the placement of cookies and clear gifs/web beacons placed by Client or IBM on Client's behalf on website isitor's deices For more information about the use of arious technologies, including cookies, for these purposes, See IBM's Online Priacy Statement at: http://www.ibm.com/ priacy/details/us/en section entitled "Cookies, Web Beacons and Other Technologies." Notices 41
42 IBM Uniersal Behaior Exchange Toolkit: User's Guide
IBM Printed in USA