IBM Campaign Version-independent Integration with IBM Engage Version 1 Release 3 April 8, Integration Guide IBM

Transcription

1 IBM Campaign Version-independent Integration with IBM Engage Version 1 Release 3 April 8, 2016 Integration Guide IBM

2 Note Before using this information and the product it supports, read the information in Notices on page 107. This document describes procedures and features that are supported by IBM Campaign version to x. Copyright IBM Corporation 2014, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

3 Contents Chapter 1. Overview What you can do with the integration What you cannot do with the integration New in this release Resources to support the integration Chapter 2. Planning Security considerations for Campaign and Engage.. 7 Security in Campaign Security in IBM Engage Data management for Campaign and Engage... 8 Integration database tables, ETL, and partitioning 9 Chapter 3. Prerequisites Integration prerequisites for Engage IBM Marketing Cloud organization account.. 11 Creating the integration user SMS enablement Mobile push enablement Integration prerequisites for Campaign IBM Campaign installation requirements Integration prerequisites for UBX Integration prerequisites for the UBX Toolkit Chapter 4. Installation and configuration Installing the integration files CS_HOME directory Upgrading an existing integration Configuring access to JDBC Creating tables for data download Configuring connections between Campaign and Engage Firewall preparations Configuring data exchange properties Configuring access to Engage Proxy server connections Connecting through an HTTP proxy Connecting through an FTP proxy server Encrypting the integration configurations Creating a custom encryption key Removing encryption from configuration properties UBX Toolkit installation Preparing UBX endpoints for the integration Chapter 5. Data upload - Campaign to Engage What to upload from Campaign Where to put uploaded data in Engage Finding contact list, database, and relational table IDs in Engage Finding mailing IDs in Engage How to upload data to Engage contactupload tableupload Upload preparation and requirements Uploading data by running a script Uploading data by running a flowchart Flowchart design for data upload to Engage.. 39 Requirement to match Campaign fields to Engage fields Mapping field names in a flowchart Mapping fields with a custom XML file Requirement to match date formats Default date format for uploads Uploading dates with derived fields Chapter 6. Contact data download - Engage to Campaign Contact data available from Engage Where to download contact data How to download contact data contactdownload Downloading contact data by running a script.. 51 Scheduling contact data downloads by running a flowchart Flowchart design for downloading contact data 53 Chapter 7. Tracking data download - Engage to Campaign Tracking data provided by Engage Adding additional tracking information Tracking data available through the UBX Toolkit 59 Where to download tracking data How to download tracking data trackingdownload Downloading tracking data with a script Scheduling tracking data downloads Tracking data download with the UBX Toolkit.. 63 Error reporting for tracking data Chapter 8. messaging Uploading contact data to Engage Sending messages after uploading contact data Downloading contact data Downloading tracking data Support for Send Time Optimization Chapter 9. SMS messaging General requirements for SMS messaging Consent requirements for SMS messaging Data required for SMS consent Uploading SMS contact and consent data to Engage 77 Sending SMS messages after uploading SMS contact and consent data Downloading SMS consent data Copyright IBM Corp. 2014, 2016 iii

4 SMS Opt-in and Opt-out synchronization between Campaign and Engage Downloading SMS message tracking data Chapter 10. Mobile app messaging.. 83 Mobile push contact synchronization between Campaign and Engage Uploading mobile push contact data to Engage.. 84 Sending push notifications after uploading contact data Downloading mobile push contact data Downloading mobile push tracking data Chapter 11. Reference: Mapping files 87 Chapter 12. Custom tracking tables.. 93 Event types Report IDs Reasons for contact suppression SP_Attachment SP_BounceReply SP_Click SP_Conversion SP_Forward SP_Open SP_OptIn SP_OptOut SP_Sent SP_Suppressed SP_UploadAudit Contacting IBM technical support Notices Trademarks Privacy Policy and Terms of Use Considerations 109 iv IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

5 Chapter 1. Overview The integration of IBM Campaign with IBM Engage combines the precision segmentation tools in Campaign with the robust, cloud-based messaging capabilities of IBM Engage. IBM Engage is part of the IBM Marketing Cloud. Use the integration to upload Campaign segmentation and contact data to Engage databases, contact lists, and relational tables. You can then apply the information from Campaign and messaging tools in Engage to target specific audiences, individually personalize each message, and reach current and potential customers through , SMS, and mobile push notifications. When the message recipients respond to Engage, you can download contact and tracking data back to Campaign to retarget message responders so that you can maintain contact throughout the customer journey. How it works The integration is based on a package of scripts that interact with Campaign flowcharts and Engage application programming interfaces (API). Download and configure the integration package to enable a secure, automated exchange of segmentation, contact, and tracking data between Campaign and Engage. Run the data upload and download scripts from a command line or automate the data exchange by adding a script to the configuration of a Campaign flowchart. v Configure the integration package to establish the connection between Campaign and Engage. v Design and run flowcharts in Campaign to determine what to send to Engage. v Design and run upload scripts to determine how to send the data to Engage and determine where the data goes. v Run download scripts to bring responses back to Campaign. The integration also takes advantage of IBM Universal Behavior Exchange (UBX) and the UBX Toolkit to bring tracking data from Engage into Campaign. Use the version-independent integration of Campaign with Engage with Campaign versions through If you install or upgrade to Campaign 10.0, you do not need to use the integration that is described here. The integration at a glance. The following diagram illustrates the various elements of the integration and the flow of data between them. Copyright IBM Corp. 2014,

6 A Campaign. Select message recipients. B Integration scripts in a flowchart trigger, which you add to a Mail List process. Upload data to Engage. C Engage. Receive data in Engage databases, contact lists, and relational tables. D Use the data from Campaign with Engage message templates to create , SMS, and mobile app messages. E Send messages in various channels. F Recipients receive the messages and respond. G Return contact and tracking data to Campaign. Depending on channel, use download scripts or UBX and the UBX Toolkit. In UBX, register Engage as an events publisher. H Use the integration download scripts and the UBX Toolkit to receive the downloaded data and add it to Campaign tables. In UBX, register Campaign as an events subscriber. 2 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

7 What you can do with the integration The integration of Campaign with Engage gives Campaign users a way to use Engage messaging tools and gives Engage users access to segmentation tools in Campaign. You can use the integration software and procedures to perform the following tasks. v Use flowcharts and integration scripts in Campaign to select and automatically upload data to Engage. Use existing Campaign scheduling features to schedule the data upload for a specific time or on a recurring basis. v Upload segmentation data from Campaign and automatically trigger outbound messaging based on pre-configured , SMS, or mobile push templates. v When you trigger outbound messages with a data upload, you can add a campaign code or other label to the mailing name for better response tracking. v Upload the output of a Campaign flowchart to update the contents of one or more existing contact lists, databases, or relational tables in Engage. You can specify a contact list or database by ID or by name. v Define a new contact list in Engage when you upload the output of a Campaign flowchart. v Use flowcharts and scripts in Campaign to select and upload SMS contact and consent data to Engage. In Engage, send SMS messages that are addressed and personalized with the uploaded segmentation data. v Use integration download scripts and existing Campaign scheduling features to download contact data and tracking data from Engage. Schedule the data download for a specific time or on a recurring basis. v Use IBM Universal Behavior Exchange (UBX) and the UBX Toolkit to download SMS and mobile push tracking data from Engage. What you cannot do with the integration New in this release Some aspects of the integration of Campaign with Engage limit what you can do in each application with the data that you share between them. v You cannot upload offer information from Campaign to Engage. The integration of Campaign with Engage does not support Campaign offers. v You cannot use the integration to send SMS messages until you purchase SMS messaging for IBM Marketing Cloud and IBM provisions your Engage organization for SMS messaging. See Chapter 3, Prerequisites, on page 11. v You cannot use the integration to send mobile app messages until you enable your IBM Marketing Cloud account for mobile push and implement your mobile app with IBM Marketing Cloud. See Chapter 3, Prerequisites, on page 11. v You cannot use the integration as a data migration tool. The integration is designed only to upload the output of a single Campaign flowchart to Engage and to download selected contact and tracking data from Engage to Campaign. IBM periodically updates the integration of IBM Campaign and Engage to improve and expand what you can do with the integration of the two applications. This release introduces the following new features and capabilities. v Expanded support for SMS messaging Chapter 1. Overview 3

8 This release enables you to upload contact data without the need few a custom mapping file. You can send SMS messages automatically after you upload SMS contact data. v Expanded support for mobile push notifications. This release enables you to upload contact data with configurable sync fields. You can send push notifications automatically after you upload contact data. v Configurable sync fields for contact upload to support non-keyed databases in Engage You can define a synchronization field in the integration configuration properties and selectively override the field settings when you run an integration script from the command line or as part of a flowchart trigger. v Send Time Optimization support for When you upload contact data to Engage, you can now include a parameter that instructs Engage to enable Send Time Optimization. v Separate proxy server support for HTTP and FTP If your corporate data security plans demand separation between your corporate data and the public Internet, you can connect to IBM Engage through either an HTTP proxy or an FTP proxy. Your choice. v SMTP Authentication for sending error logs As part of the integration configuration, you can now specify the credentials that are required to access the SMTP server that you use to send error reports for tracking download. v Expanded response tracking through the UBX Toolkit You can now download tracking data for all messaging channels through the UBX Toolkit and IBM Universal Behavior Exchange (UBX). Resources to support the integration The Campaign to Engage integration provides various types of support to help you use the products together and resolve problems that might occur. v The IBM Campaign and IBM Engage Version-independent Integration Guide provides descriptions and procedures for concepts and tasks that are specific to the integration. For concepts and tasks that apply to Campaign, Engage, UBX, or the UBX Toolkit separately from the integration, see the general product documentation that is available for each application. v Product documentation for IBM Engage is available in the IBM Marketing Cloud Knowledge Base at You must provide valid login credentials to access the IBM Marketing Cloud Support Portal. v Product documentation for Campaign is available on the IBM Knowledge Center at product_welcome_kc_campaign.dita v Product documentation for IBM Universal Behavior Exchange (UBX) is available on the IBM Knowledge Center at kc_welcome_ubx.dita 4 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

9 v Product documentation for the UBX Toolkit is available on the IBM Knowledge Center at v The integration scripts include detailed help on the command line through the -h or -help option. v The property files and example files that are provided as part of the integration contain detailed comments that explain how to customize the integration for your working environment. Chapter 1. Overview 5

10 6 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

11 Chapter 2. Planning The first phase of integrating IBM Campaign with IBM Engage requires satisfying requirements in both product environments for network communication, application access, and data management. To ensure a successful integration in your environment, review and complete all system and security requirements for Campaign and Engage before you install and configure the integration files. Consider the effort, user permissions, and resources that are required to satisfy these requirements in your working environment. Security considerations for Campaign and Engage IBM Campaign and IBM Engage control application access in slightly different ways. Planning how to control access to the integration of Campaign and Engage requires an understanding of both products and how they can operate together. As you plan to implement the integration of Campaign and Engage in your environment, consider the following issues. v User accounts, roles, and permissions that are defined in Campaign are separate from users and permissions that are defined in Engage. There is no single sign-on between the two products. Marketing users require separate user accounts to access Campaign and Engage. v The integration scripts require a special user account so that they can operate automatically. This user is referred to as the integration user. v In Engage, use shared databases instead of private databases so that all members of your organization can access them. Content in private databases is not available to other users or to the integration scripts. Related concepts: Firewall preparations on page 21 Security in Campaign IBM Campaign installs with IBM Platform. Security for both applications is based on user permissions that are set for each application. In IBM Campaign and IBM Marketing platform, you define logins for individual marketing users and set permissions on them. The permissions limit what each user can do within Campaign. You can create various security policies and roles to manage user permissions. You set policies on top level folders within Campaign. the top-level policies, in combination with user permissions, restrict which objects in Campaign users can access and what they can do with them. For more information on security in IBM Campaign, see the IBM Campaign Administrator's Guide. Copyright IBM Corp. 2014,

12 Security in IBM Engage For more information on security in IBM Engage, see the IBM Marketing Cloud Knowledgebase. Related tasks: Configuring access to Engage on page 22 Data management for Campaign and Engage To use Campaign and Engage together, you must understand where your data lives. You need to know what your IT security and privacy officers are comfortable uploading to the Cloud and publishing in . You also need to anticipate the types of segmentation and personalization that you need to effectively reach your customers. The integration of IBM Campaign and IBM Engage depends heavily on the exchange of information between the two applications and how that data exchange is managed. It is important to remember that IBM Campaign is installed locally, behind corporate security firewalls. Engage is a cloud-based service that is accessed through secure login. In Campaign, you can design flowcharts to create rich segmentation over the data in any database to which Campaign is connected. The segmentation includes data from external data imports and activity from multiple channels, such as direct mail, call center activity, and . You can send the segmentation output to a file or database table, where fulfillment processes for different channels can pick up the list of contacts and use them. The output can also contain other database fields for personalization purposes. Engage mailings and programs work with either queries or contact lists. A contact list is a list of rows within an Engage database. The database can be populated manually, through an API, or through web forms. A query is a set of criteria that can be based on any data that is available to Engage, whether in databases or relational tables. Programs in Engage can also use Universal Behaviors to decide whether to add a particular contact to the program. The Campaign integration with Engage allows marketing users to upload or download database data from Engage, upload relational table data, and download tracking events from Engage tracking. Flowcharts can also add contacts to a contact list based on Campaign segmentation and integration scripts. Some local Campaign data must be uploaded to the cloud in order for Engage to work. The following examples are typical of the kind of data that either exists in the cloud-based systems or must be uploaded to those systems. v Data for keys that you define in your Engage database. v Data that is required to personalize the messages that you send. For example, if you want to address the contact by first name and title in your messages, you need to have first name and title stored in your database. v Any Universal Behavior data that you are planning on taking advantage of in programs. Universal behavior data is stored in Engage and cannot be downloaded to the Campaign database. v Any data that is collected through Engage web forms. 8 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

13 Note: If you plan to use data from Campaign in messages that involve SMS, Mobile Push Notification, CRM integration, or Engage Universal Behaviors you must upload the data to a non-keyed Engage database. Data that does not need to go into the cloud includes any data that is not in the categories that are described above. For example, you might need a postal code to determine whether an individual contact is near a participating retail outlet, or you might want to check purchase history to determine whether an individual is a high, medium, or low value customer. You can use Campaign to make those determinations locally, behind the firewall, and upload only the contact list that results from the query. You do not need to upload the postal code or the purchase history to Engage to use that data in your segmentation criteria. Related concepts: What to upload from Campaign on page 30 Where to put uploaded data in Engage on page 30 Integration database tables, ETL, and partitioning The Campaign integration with Engage populates different database tables for auditing and tracking. Consult with your database administrator to discuss how long you need to keep the data for querying. Depending on the volume of activity for your account, the tables can grow large over time. Each integration table shares some characteristics. v The primary key is an identity or sequence column. The IDs in the primary keys reflect the order in which rows were inserted. v The tables have a datetime/timestamp column to indicate the time at which a particular event happened. v The rows in each table are inserted once and the integration does not update them after the initial insert. v There are no predefined indexes, foreign keys, or check constraints other than the primary key. If you are not using recipient address as the audience level in Campaign, you can add one or more columns to the tracking tables. However, your data must include a way to look up audience level for any contact. You must configure the integration to download the values for those columns from your Engage database. When you add columns, do not use unique indexes or constraints because you might prevent data from being inserted. The integration scripts do not automatically purge or archive the tables. Your administrator can schedule archiving or purging of the data. A typical purging scheme might set up range partitioning on the datetime/timestamp field, with partitions for each month or quarter. The purging plan can drop partitions when they become outdated. However, different database capabilities and performance characteristics can affect your strategy for partitioning and purging of data. How you query the data might also affect your strategy. Chapter 2. Planning 9

14 10 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

15 Chapter 3. Prerequisites The various components that play a role in the integration of Campaign and Engage each have a set of prerequisites that you must satisfy before you install and operate the integration. You must satisfy each set of prerequisites separately. Information that you might need to complete the prerequisites for Campaign or Engage is included here or in the supporting documentation for each product. Integration prerequisites for Engage Before you can use Engage with Campaign, you must establish access to Engage. You must create an IBM Marketing Cloud user account to gain access on behalf of your organization and configure a system user with access to Engage to perform integration tasks. Learn more about IBM Marketing Cloud and how to request a user account at Related concepts: Integration prerequisites for Campaign on page 15 IBM Marketing Cloud organization account IBM Engage is part of IBM Marketing Cloud. To access IBM Engage, you must provide a valid user name and password. You must have an IBM Marketing Cloud account to receive a login. IBM Engage manages user and application access to Engage through organizations that are created in Engage. You can designate one or more members of your marketing or IT team as organization administrators. An organization administrator can configure organization settings, manage users, supervise mailings, and monitor and assess mailing results. The organization administrator is also granted the user permissions within Engage that are required to configure the integration of Campaign with Engage. If you are a current IBM Engage customer, you can use your existing account login to access Engage to configure the integration. If you are a Campaign user who wants to use IBM Engage, your business organization must establish an account with IBM Marketing Cloud. To request credentials to access IBM Engage, contact your IBM representative. Creating the integration user IBM Campaign automatically accesses data management and messaging features in the Engage environment as a standard Engage user over a secure HTTPS connection. In the context of the IBM Campaign and IBM Engage integration, this user is referred to as the integration user. Copyright IBM Corp. 2014,

16 Before you begin Access IBM Engage to complete this task. You must have a valid IBM Marketing Cloud login to access Engage. You must be an organization administrator to create the integration user. About this task Accessing Engage as the integration user provides IBM Campaign with a way to submit access credentials to IBM Engage without the need for manual intervention. To fully configure the integration user, you must manually log in as the integration user at least once so that you can define a persistent user password. You must configure the integration user to have permissions to upload and download data, add and remove contacts, and to send mailings. You must also associate the user with an account that can receive system notifications and credentials. Specify an account that you can access easily and monitor frequently. The integration user does not require access to the IBM Marketing Cloud Support Portal. Procedure 1. In Engage, go to Settings > User Accounts. Click Create User Account. Accept the default settings except as noted in the following steps. 2. On the Create User page, complete the User Information fields. a. In the User section, enter a user name and enter a password that conforms to the password standards that are defined on the page. Select Do not enforce password expiration policies for this user. Note: The password is a temporary password that is valid for 7 days. After you configure the integration user, you must log in to Engage within 7 days to define a permanent password. b. Enter a name for the integration user. The name can be any name. c. In the Role field, select Standard User. d. In the Contact fields, provide contact information that the system uses to provide notifications. Enter an address that you can access and monitor readily. Important account credentials are delivered to the address that you specify. e. In the Localization section, enter a time zone and default language. Enter the time zone that is appropriate for where the Campaign Analytic server is located. f. In the Defaults section, enter a name, address, and reply address that the system uses to define the sender of the marketing that you send. 3. Click Save. After you save, you can define other aspects of the integration user. 4. In the User Permissions section, select the following options to define permissions for the integration user. v Data access. For this permission, select Add/Remove Contacts from Contact Lists and Edit Queries. v Allow user to upload content to Stored Files and Mailing Templates 12 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

17 5. Click Save. 6. Go to Settings > Organization Settings. You must be an organization admin to access this menu. The Organization Settings window opens. 7. In the Application Account Access section, click Add Application. Enter a name to identify the integration as an external application that can access Engage data. Click Add. 8. Click Add Account Access. The Add Account Access window opens. 9. In the Application field, select the name that you assigned for the integration in Step 7. In the User Account field, select the user name that you entered in Step 2. Click Add. 10. Monitor the notification address that you defined for the integration application until you receive an notification. The notification contains the application name that you defined the integration application and a refresh token. 11. In the Application Account Access section, click the name that you assigned to the integration application. A Client ID and Client Secret display. Record the values for future use. 12. Log out of Engage. Log back in to Engage with the user name and password that you defined for the integration user in Step 2. a. Go to Settings > User Profile. b. In the User section, enter the current password for the integration user and define a new password. The new password is the permanent password for the integration user. c. Click Save. Results The new integration user displays as a standard user on the Enabled tab of the User Accounts page. Following information is defined for the integration user. v User name v Password v Client ID v Client Secret v Refresh token Record the information in a secure location. The information is required to configure access between Campaign and Engage. If you configured the user to ignore password expiration policies as required in Step 2, you are not prompted to change this password again. What to do next The integration user runs the integration scripts. You must specify the user name and password that you define for the integration user in the sp.properties configuration file. The integration user can operate only on shared objects in Engage. When you create objects in Engage, such as databases, contact lists, or mailings, be certain to create them as shared objects. Chapter 3. Prerequisites 13

18 SMS enablement To send SMS messages from IBM Engage, you must complete certain preparations to enable your Engage organization for SMS. You must be an organization administrator to complete some of the steps in the process. The Provisioning Team for the IBM Marketing Cloud must enable your organization for SMS. Then, you must log into Engage and complete additional steps to prepare your organization for SMS messaging. v Create and enable an Engage database for SMS. The database must be a non-keyed database. v Configure SMS integration between Engage and the SMS Campaign Manager. Each Engage organization can have only one database that is enabled for SMS. If you also plan to send mobile push notifications you can enable a single database for SMS and Mobile App Messages. However, you can also enable one database for SMS and another database for Mobile App Messages. For more information regarding how to enable your IBM Marketing Cloud organization for SMS messaging, see the description of SMS in the IBM Marketing Cloud Knowledge Base at _Silverpop_Mobile_Messaging. Mobile push enablement To send mobile push notifications from IBM Engage, you must complete certain preparations to enable your Engage organization for Mobile App Messages. You must be an organization administrator to complete some of the steps in the process. The Provisioning Team for the IBM Marketing Cloud must enable your organization for Mobile App Messages. Various individuals contribute to making it possible to send mobile push notifications from Engage, including mobile app developers, the Engage organization administrator, and mobile marketers. The entire process includes the following general steps. v The Provisioning Team enables Mobile App Messages for your organization. v Mobile app developers build and register your mobile app. v Download the SDK. Implement the SDK within the mobile app. v Customize the app, as needed. v Create an Engage database for Mobile App Messaging. The database must be a non-keyed database. v Set up the mobile app in IBM Marketing Cloud. Each Engage organization can have only one database that is enabled for Mobile App Messaging. If you also plan to send SMS messages, you can enable a single database for SMS and Mobile App Messaging. However, you can also enable one database for SMS and another database for Mobile App Messages. 14 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

19 For more information regarding how to enable your IBM Marketing Cloud organization for Mobile App Messages, see the description of the process in the IBM Marketing Cloud Knowledge Base at mobile/mobile_app_messages. Integration prerequisites for Campaign Before you can use Engage with Campaign, you must update the IBM Marketing Software environment, including the installations of IBM Platform and IBM Campaign. If you are an Engage user who is beginning to use IBM Campaign, you must install and configure IBM Campaign in your local computing environment. Campaign requires that you also install and configure IBM Marketing Platform. v If Campaign is not installed in your local environment, you must install Campaign. v Define Campaign users with appropriate roles and permissions. v Identify the data that you need to upload to Engage. v Download and install the integration package on the Campaign Analytics Server. For a full list of installation and configuration requirements for Campaign, see the IBM Campaign Installation Guide or the IBM Campaign Upgrade Guide. Related concepts: Integration prerequisites for Engage on page 11 IBM Campaign installation requirements To use Engage messaging tools with Campaign segmentation tools, you must install and configure IBM Campaign. Campaign requires that you also install and configure IBM Marketing Platform. The IBM Campaign integration with IBM Engage is supported on IBM Campaign version to For more information about how to install Campaign, see the IBM Campaign Installation Guide. To integrate Campaign with Engage, you must complete the following tasks. v Configure the Campaign system tables and schema. v Define roles and permissions for Campaign users. For information on installing and configuring IBM Campaign, see the IBM Campaign Installation Guide and the IBM Campaign Administrator's Guide. Integration prerequisites for UBX You can use UBX and the UBX Toolkit to download tracking data from Engage. To use UBX you must have a UBX user account. Access to UBX user accounts requires entering a user name and password that IBM creates for each UBX user account. Chapter 3. Prerequisites 15

20 Contact IBM to request a UBX user account. As part of the installation and configuration process, you register Campaign and Engage as endpoints in UBX and configure event syndication between them. Integration prerequisites for the UBX Toolkit The UBX Toolkit depends on UBX and on files that you install in your local environment. You must establish the UBX account and complete the UBX Toolkit installation and configuration before you can download tracking data for SMS messages and mobile push notifications. To access UBX, IBM must create and provision a UBX account on your behalf. To request that IBM to create and provision your UBX account, contact the UBX Account Provisioning team by at ubxprovisioning@wwpdl.vnet.ibm.com or request access to UBX at signup.do?source=ibm-ubxprovision. Installing and operating the UBX Toolkit requires access to various systems in your local network environment. Establishing this access typically requires network or database administrative privileges. For a full list of installation and configuration requirements for the UBX Toolkit, see the UBX Toolkit Users Guide on IBM Knowledge Center here: 16 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

21 Chapter 4. Installation and configuration Installing the integration files The integration of Campaign with Engage depends on a collection of files that you download from IBM developerworks to the environment in which Campaign is installed. You install the files on the Campaign Analytics server. You perform all of the installation and configuration tasks, except for firewall modifications, in the local Campaign environment. To install the IBM Campaign integration with IBM Engage, download the integration package from IBM DevWorks and extract the archive into a directory in your existing Campaign installation. Before you begin Complete the integration planning and prerequisites for Campaign and Engage. Procedure 1. Go to IBM devworks and download the installation package for your operating system. Table 1. Integration Installation Packages Operating System Windows UNIX or Linux Installation download package IBM_Campaign_Integration_with_IBM_Engage_1.3_Windows.zip IBM_Campaign_Integration_with_IBM_Engage_1.3_Unix-Linux.tar.gz 2. On the Campaign Analytics server, extract the compressed archive into a folder under../campaign/partition/partition1/. The folder where you install the files is considered the <CS_HOME> directory. 3. In <CS_HOME>, configure the setenv file. This file is in the bin directory. a. Copy and rename example_setenv.bat to setenv.bat or example_setenv.sh to setenv.sh. b. Configure the setenv file as instructed by comments in the file. 4. In <CS_HOME>, configure jdbc.properties. This file is in the conf directory. a. Copy and rename example_jdbc.properties to jdbc.properties. b. Configure jdbc.properties as instructed by comments in the file. 5. In <CS_HOME>, configure config.properties. This file is in the conf directory. a. Copy and rename example_config.properties to config.properties. b. Configure config.properties as instructed by comments in the file. 6. In <CS_HOME>, configure sp.properties. This file is in the conf directory. You must be familiar with the configuration of the integration user to complete this step. a. Copy and rename example_sp.properties to sp.properties. b. Configure sp.properties as instructed by comments in the file. Copyright IBM Corp. 2014,

22 7. In <CS_HOME>, make a copy of example_logback.xml. This file is in the conf directory. a. Rename the copy as logback.xml. b. (Optional) Update the <max History> tag. By default, this tag is set to 14. This setting maintains a log history of 14 days. You can change this value to suit your requirements. 8. For UNIX or Linux environments only, change directory to the bin directory, then run chmod +x *.sh. What to do next Create database tables to accept data that is downloaded from Engage. Related tasks: Creating tables for data download on page 19 Configuring connections between Campaign and Engage on page 20 CS_HOME directory The directory where you install the scripts, property files, and other software to support the Campaign integration with Engage files is referred to as <CS_HOME>. The integration files must be installed in a folder under../campaign/partition/ partition1/, on the Campaign Analytic server. Note the path to the <CS_HOME> folder. You specify an absolute or relative path to this folder when you run the integration scripts. Related tasks: Downloading tracking data with a script on page 62 Related reference: contactupload on page 33 tableupload on page 36 contactdownload on page 50 trackingdownload on page 61 Upgrading an existing integration IBM periodically upgrades the Campaign to Engage integration to fix observed issues and to introduce new capabilities. Before you begin To preserve your current configurations, back up your existing Campaign to Engage integration installation. The upgrade replaces the existing files with new files. Procedure 1. Backup the current <$CS_HOME> directory. You will need to use the backup files to replicate your configuration settings. 18 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

23 Configuring access to JDBC 2. Download the compressed installation file archive and extract the files into <$CS_HOME>. The new files overwrite the existing files. Windows: IBM_Campaign_Integration_with_IBM_Marketing_Cloud_1.3_Windows.zip Linux or UNIX: IBM_Campaign_Integration_with_IBM_Marketing_Cloud_1.3_Unix-Linux.tar.gz 3. In the conf directory, open example_sp.properties. Add the new proxy properties to your sp.properties file. v v v v v v sp.proxy.url URL for the web proxy server. sp.proxy.username User name to access the web proxy server. sp.proxy.password Password to access the web proxy server. sp.proxy.ftp.url=url for the FTP proxy server. sp.proxy.ftp.username= User name to access the FTP proxy server. sp.proxy.ftp.password= Password to access the FTP proxy server. 4. In the ddl directory, run the appropriate version of the cs_tab_upgrade_ _xxx.sql script for your database. v v v DB2: cs_tab_upgrade_ _db2.sql Oracle: cs_tab_upgrade_ _ora.sql MS SQL Server: cs_tab_upgrade_ _sqlsvr.sql Use the jdbc.properties file to configure JDBC access to enable data transfer between IBM Campaign and IBM Engage. About this task To configure properties in this file, you must know the database driver class and the JDBC URL for the Campaign database that contains the data that you upload to Engage. You must also know the name and password for the system user that is used to access the Campaign database. Procedure Comments in jdbc.properties provide guidance for configuring each property. The jdbc.properties file is in the conf directory of CS_HOME. Creating tables for data download To enable Campaign to receive contact and tracking data from Engage, you must create new database tables to receive the downloaded data. The integration package includes several DDL scripts that you can use to create the required tables. Before you begin Confirm that the integration files are installed in a folder on the Campaign Analytics server. The folder that contains the integration files is considered the <CS_HOME> directory. Locate the ddl folder. Procedure 1. On the Campaign Analytics server, navigate to the ddl folder in the <CS_HOME> directory. Chapter 4. Installation and configuration 19

24 2. Use your database client to run the DDL scripts against the database or schema that holds the Campaign system tables. v v v Microsoft SQL server: cs_tab_sqlsvr.sql Oracle: cs_tab_ora.sql IBM DB2: cs_tab_db2.sql Running the DDL script against the Campaign database extends the Campaign database schema to include the new tables. Results The following tables are created in the Campaign database schema. Tracking table Description More information SP_Attachment SP_BounceReply Records when an attachment is downloaded or viewed. Records of unsuccessful message delivery. SP_Attachment on page 95 SP_BounceReply on page 96 SP_Click Records for link clicks in messages. SP_Click on page 96 SP_Conversion Records of Engage conversion events. SP_Conversion on page 97 SP_Forward Records of messages that were forwarded. SP_Forward on page 98 SP_Open Records of message opens. SP_Open on page 99 SP_OptIn Records that are marked as opted-in. SP_OptIn on page 100 SP_OptOut Records that are marked as opted-out. SP_OptOut on page 101 SP_Sent Records of messages sent. SP_Sent on page 102 SP_Suppressed SP_UploadAudit Records of recipients for whom messages are suppressed. Record of all data uploads and related API calls. SP_Suppressed on page 102 SP_UploadAudit on page 103 The SP_UploadAudit table is updated when marketers run the contactupload or tableupload script to upload data and segmentation to Engage. The remaining tables are updated when marketers run the trackingdownload script to download tracking data from Engage. Related tasks: Installing the integration files on page 17 Configuring connections between Campaign and Engage The Campaign integration with Engage includes various configuration files that you modify to establish and support secure upload and download of contact and tracking data. The configuration files are provided as part of the download package. 20 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

25 About this task Configuring the connection between Campaign and Engage involves the following steps. v Preparing the corporate firewall. Typically, corporate IT or network administrators perform this task. v Configuring data exchange properties. v Configuring access to Engage. Optionally, you can configure a proxy server between Campaign and Engage. Related tasks: Installing the integration files on page 17 Firewall preparations The integration scripts, and the Campaign flowcharts that use the scripts as triggers, run on the Campaign Analytic server, behind your corporate firewall. Network administrators must configure the firewall to allow the Campaign Analytic server to communicate with the Engage servers that are installed in the cloud-based IBM Engage messaging infrastructure. Consulting with your network administrators to plan how to support communication between Campaign and Engage is a critical step in the integration planning process. The integration cannot operate unless the corporate firewall is configured to allow Campaign to securely exchange data with the Engage servers. The integration scripts communicate with Engage over HTTPS and SFTP. To support these communication methods, network administrators must open ports in the firewall as follows. v HTTPS: Port 443 v SSH: Port 22 IBM Marketing Cloud designates specific Engage servers for use by your organization. In the integration configuration, the sp.properties file defines the Engage server addresses. Administrators require these addresses to update the firewall configuration. The sp.properties file is in the conf directory. The sp.properties file contains the sp.ftp.port setting that defines the SSH port through which the integration transmits and receives data over SFTP. By default, this setting is set to port 22. Comments in the sp.properties file explain how to configure the various configuration settings. Related concepts: Security considerations for Campaign and Engage on page 7 Configuring data exchange properties Use the config.properties file to configure and manage data exchange between IBM Campaign and IBM Engage. You can also configure properties in this file to specify how the system reports and responds to errors. Chapter 4. Installation and configuration 21

26 Procedure Comments in config.properties provide guidance for configuring each property. The config.properties file is in the conf directory of CS_HOME. Configuring access to Engage Use the sp.properties file to define the integration user and the servers that manage data transfer between IBM Campaign and Engage. Procedure Comments in sp.properties provide guidance for configuring each property. The sp.properties file is in the conf directory of CS_HOME. Related concepts: Security in IBM Engage on page 8 Proxy server connections You can configure the integration to support communication between Campaign and Engage through a proxy server. If your corporate data security plans demand separation between your corporate data and the public Internet, you can connect to IBM Engage through an HTTP proxy or a FTP proxy. The sp.properties configuration file includes optional configuration properties sets of configurations that you can populate to route traffic through HTTP or FTP proxy servers. 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. If authenticated access to the proxy server is required, the user name and password for the proxy are usually assigned by your network administrator or IT staff. You can configure each proxy server independently. If you use the same proxy server for HTTP and FTP, enter the same values for both sets of configuration properties. If you use a single proxy server but do not enter values for FTP configurations, the server passes only HTTP traffic, not FTP traffic. The sp.properties file is in the conf directory of <CS_HOME>. The proxy server credentials are different from the credentials for the integration user. The following diagram illustrates where the proxy server fits in the connection between Campaign and Engage. The following diagram illustrates where the proxy server fits in the connection between Campaign and Engage. 22 IBM Campaign Version-independent Integration with IBM Engage: Integration Guide

27 Connecting through an HTTP proxy To route traffic through an HTTP proxy, enter values for the sp.proxy configurations. About this task To upload segmentation data and download contact and tracking data through an HTTP proxy server, enter a URL for the proxy server. For example: sp.proxy.url= If you do not specify a URL, the system does not route upload and download traffic through the proxy server. If you enter a proxy server URL but do not enter a proxy server user name and password, the proxy server processes upload and download traffic without requiring authentication. Procedure 1. In the conf directory, open sp.properties in a text editor. 2. In the Optional Properties section, modify the following properties. Comments in the file provide guidance for updating each property. v v v sp.proxy.url Specify the URL for the web proxy server. sp.proxy.username Specify the user name that is used to access the web proxy server. Leave blank if authenticated access is not required. However, if you specify a user name, you must also specify a password and a URL. sp.proxy.password Specify the password that is used to access the web proxy server. Leave blank if authenticated access is not required. However, if you specify a password, you must also specify a user name and a URL. 3. Save sp.properties and verify the connection. Note: You must restart the Campaign Analytics server for the configuration changes to take effect. Chapter 4. Installation and configuration 23