Skill Level: Any
To install the Acoustic Exchange Toolkit, download the toolkit file archive and install various scripts and properties files on a server in your local network environment. Update default settings and property files to suit your local network requirements.
The¬†Acoustic Exchange Toolkit consists of various property files and scripts that you install in your local network environment and modify to satisfy your business requirements. The installation and configuration process proceeds as follows.
- Download the Acoustic Exchange Toolkit from developerWorks as a compressed file archive.
- Extract the archive to a directory on a local server. Extracting the archive creates local directories that contain Acoustic Exchange Toolkit environment files and configuration property files.
- Modify Acoustic Exchange Toolkit environment files to reflect paths in your local environment.
- Register Acoustic Exchange endpoints in the UI, updating Acoustic Exchange toolkit configuration properties, and running the endpoint registration script.
- (Optional) Encrypt the configuration settings for enhanced security, as required by your business security policy.
Download the Acoustic Exchange toolkit
Confirm that you have rights to access and edit files on the server where you want to install the Acoustic Exchange Toolkit.
Confirm the locations of the JRE and JDBC database drivers.
Download the Acoustic Exchange 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 developerWorks. Go to: Toolkit for IBM Marketing Software
Click the link to download either of the following binary files.
- Linux or UNIX:
The directory to where you download the files is referenced within the toolkit as CU_HOME.
Install and configure the environment files
- Depending on your operating system, copy and rename
- Modify the following variables in the
JAVA_HOME: Enter the path to the JRE.
CU_HOME: Enter the path to the directory where you extracted the Acoustic Exchange Toolkit files.
JDBC_CLASSPATH: Enter the path to the JDBC driver for the database importer.
- Depending on your operating system, copy and rename
Install the configuration properties and logback files
Copy and rename the default example files that are provided in the conf directory.
Note: Do not rename config.properties or jdbc.properties after you create them. The Acoustic Exchange Toolkit requires these default configuration files in the
CU_HOMEdirectory. 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.
Registering an endpoint using the UBX Toolkit
To share event and audience data between Acoustic Exchange endpoints, users must register each endpoint with Acoustic Exchange. After initiating the endpoint registration process in the Acoustic Exchange UI, Acoustic Exchange users can acquire their authentication key in the Acoustic Exchange Endpoint details menu and then provide the key to the endpoint provider.
Each time an endpoint communicates with Acoustic Exchange, the endpoint must submit the authentication key as the authorization bearer or URL parameter in calls to¬†Acoustic Exchange APIs. Each authentication key is unique to a specific¬†Acoustic Exchange 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.
To use the Acoustic Exchange Toolkit to register an endpoint with Acoustic Exchange, you provide an endpoint-level authentication key as a value in the Acoustic Exchange Toolkit properties file.
Running the Acoustic Exchange Toolkit endpoint registration script makes an API call that includes the authentication key so that¬†Acoustic Exchange can authenticate with the endpoint provider.
Note: To register cloud-based endpoints that are not supported by the Acoustic Exchange Toolkit, you can register the endpoint directly through the endpoint registration wizard.
- Log into Acoustic Exchange with your Acoustic Exchange account login credentials
- On the Endpoints tab, click Register new endpoint to display the endpoint registration wizard.
- From the list of provided endpoints, select Acoustic Exchange Toolkit and select¬†Next.
- The endpoint appears on the Endpoints tab as Pending.
- On the Endpoints tab, open the endpoint details menu of your endpoint and copy and save the Endpoint Authentication Key.
- In the config.properties file, enter the Endpoint Authentication Key in the¬†ubx.application.endpoint.authentication.key field.
- From the $CU_HOME/bin folder, run registerEndpoint.bat or registerEndpoint.sh. script.
- To confirm the successful endpoint registration, log in to Acoustic Exchange to find your endpoint listed as Active.
Note:¬†If you are upgrading from an earlier version of the Acoustic Exchange 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¬†Acoustic Exchange Toolkit installation to match the names that are provided in the latest version.
After you have completed the Acoustic Exchange 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.
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.¬†
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.
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:
Note: If you are upgrading from a previous version of the Acoustic Exchange 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.
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.
(Linux or UNIX only) In the bin directory, enter the command: chmod +x *.sh.