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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange enables the Acoustic Exchange 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 Acoustic Exchange.

   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 Acoustic Exchange Toolkit does not upload the new audience data to Acoustic Exchange. 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 Acoustic Exchange 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 Acoustic Exchange user interface. Upon receipt of the user request, Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange user requests audience data from your endpoint, Acoustic Exchange creates a job to provide the data through Acoustic Exchange to the destination that the user specifies. New and updated audiences appear in Acoustic Exchange as Waiting for data.

   To ensure that the latest audience data is displayed and made available when Acoustic Exchange users request it, you must schedule the audience upload script to run repeatedly to make API calls to Acoustic Exchange to detect when Acoustic Exchange 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 Acoustic Exchange users and to get the corresponding audience upload job that is waiting for audience data from you.

   When Acoustic Exchange users share an audience through the Audiences tab in the Acoustic Exchange user interface, Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange Toolkit can either move the CSV file to a new location or leave it in place for possible reuse.

   The Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange users for download to an audience destination endpoint. Audience downloads happen only in response to requests from Acoustic Exchange users in the Acoustic Exchange 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, Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange Toolkit provides the eventsDownload script to download event data from Acoustic Exchange to a to a file in your local environment. You can run the script manually or as a scheduled job.

   Log in to Acoustic Exchange 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 Acoustic Exchange 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 Acoustic Exchange public APIs. The path must include the server and port that Acoustic Exchange assigns to your Acoustic Exchange 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, Acoustic Exchange 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 Acoustic Exchange toolkit downloads event data from Acoustic Exchange 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 Acoustic Exchange server.

   Acoustic Exchange event types

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

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

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

    

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

   The Acoustic Exchange 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 Acoustic Exchange 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	Â