Overview

Prerequisites

Step-by-step

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

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

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

2. Creating a custom UBX Toolkit encryption key

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

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

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

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

   Procedure

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

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

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

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

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

   3. Run the encryptConfig script to encrypt the configuration settings.

3. Removing encryption from UBX Toolkit configuration properties

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

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

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

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

Overview

Step-by-step

1. Modify proxy server settings

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

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

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

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

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

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

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

   3. Save config.properties and verify the connection.

    

Overview

Prerequisites

Step-by-step

1. Registering audience data with UBX

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

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

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

   

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

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

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

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

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

    

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

   Procedure

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

   Optional parameter

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

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

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

2. Audience sharing by UBX users

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

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

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

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

3. Upload audience data to UBX

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

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

    

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

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

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

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

   Procedure

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

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

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

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

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

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

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

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

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

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

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

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

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

Overview

Prerequisites

Step-by-step

1. Downloading audience data from UBX

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

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

      ubx.audience.consumer.archiveDownloadedAudiences=true|false

      Default: true

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

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

      Optional parameter

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

Overview

Prerequisites

Step-by-step

1. Downloading events from UBX

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

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

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

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

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

   

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

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

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

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

   UBX event types

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

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

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

    

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

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

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

    

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

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

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

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

    

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

    

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

    Stucture of the corresponding TSV file.

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

    

2. Importing event data into a database

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

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

   

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

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

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

    

   Procedure

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

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

   Required parameters

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

   Optional parameters

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

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

    

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

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

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

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

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

    

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

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

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

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

3. Updating event download

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

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

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

    

4. Custom event downloads

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

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

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

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

Overview

Prerequisites

Step-by-step

1. Download the UBX toolkit

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

   Confirm the locations of the JRE and JDBC database drivers.

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

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

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

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

2. Install and configure the environment files

   1. Depending on your operating system, copy and rename <CU_HOME>\bin\example_setenv.bat or example_setenv.sh to setenv.bat or setenv.sh
   2. Modify the following variables in the setenv file:

   • JAVA_HOME: Enter the path to the JRE.
   • CU_HOME: Enter the path to the directory where you extracted the UBX Toolkit files.
   • JDBC_CLASSPATH: Enter the path to the JDBC driver for the database importer.

3. Install the configuration properties and logback files

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

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

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

4. Registering an endpoint using the UBX Toolkit

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

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

   • Connect to UBX through a web proxy server
   • Encrypt the UBX Toolkit configurations

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

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

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

   Procedure

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

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

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

5. Modify config.properties

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

6. Modify jdbc.properties

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

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

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

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

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

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

   For example, jdbc.user=databaseUserName

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

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

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

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

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

7. Update audience producer and audience consumer endpoint ID

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

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

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

8. Run chmod

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