IBM Campaign and IBM Silverpop Engage Version 1 Release 2 August 31, Integration Guide IBM

Transcription

1 IBM Campaign and IBM Silverpop Engage Version 1 Release 2 August 31, 2015 Integration Guide IBM

2 Note Before using this information and the product it supports, read the information in Notices on page 93. This document describes procedures and features that are supported by IBM Campaign version and higher. 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 of the integration. 1 User actions for the integration Data flow in the integration What you can do with the integration What you cannot do with the integration What s new in this release Resources to support the integration Chapter 2. Planning to integrate Campaign with Engage Security considerations for Campaign and Engage.. 7 Security in Campaign Security in IBM Silverpop Engage Data management for Campaign and Engage... 8 Integration database tables, ETL, and partitioning 9 Integration prerequisites in Engage IBM Silverpop organization account Creating the integration user Integration prerequisites in Campaign IBM Campaign installation requirements Chapter 3. Installing the Campaign integration with Engage Installing the integration files CS_HOME directory Upgrading an existing integration of Campaign and Engage 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 Connecting through a proxy server Encrypting the integration configurations Creating a custom encryption key Removing encryption from configuration properties Chapter 4. Data upload from Campaign to Engage What to upload from Campaign Upload preparation and requirements Placeholder offer for the Mail List process Where to put uploaded data in Engage Finding contact list, database, and relational table IDs in Engage Finding mailing IDs in Engage Engage keys and Campaign audience levels.. 31 When to upload to a non-keyed database Mapping Campaign fields to Engage fields Mapping field names in a flowchart Mapping fields with a custom XML file Matching date formats Default date format for uploads Uploading dates with derived fields Additional identifiers in mailing names Scripts for uploading data from Campaign to Engage contactupload tableupload Manually uploading data from Campaign to Engage 43 Automatically uploading data from Campaign to Engage Flowchart design for data upload to Engage.. 44 Creating a flowchart trigger for automatic data upload Configuring a Mail List process for automatic data upload to Engage Examples of typical upload triggers Example: Upload to an Engage database Example: Upload to a contact list Example: Upload to a contact list identified by name Example: Upload and create a new contact list. 48 Example: Upload to a contact list and trigger a mailing Example: Upload to a contact list and trigger a mailing with a modified mailing name Example: Upload to multiple contact lists Example: Upload to multiple contact lists and trigger a mailing Example: Upload data to an Engage relational table Example: Upload data as specified in a mapping file Example: Upload mapped data and trigger a mailing Chapter 5. Contact data download Script for downloading contact data Downloading contact data Creating a flowchart trigger for contact data download Finding query IDs in Engage Download trigger examples Configuring a Schedule process for contact data download Selecting downloaded contact data Chapter 6. Tracking data download.. 61 Script for downloading tracking data Tracking data provided by Engage Adding additional tracking information Database management concerns and precautions 63 Manually downloading tracking data Automatically downloading tracking data Copyright IBM Corp. 2014, 2015 iii

4 Example: Download tracking data from a specific Engage database Example: Downloading tracking data from all Engage databases Error reporting for tracking data Chapter 7. SMS messaging with Campaign and Engage Requirements for SMS messaging Purchase requirement for SMS messaging Consent requirements for SMS messaging SMS number format SMS database requirement Text to Join Data required for SMS consent Uploading SMS contact data from Campaign to Engage Downloading SMS data from Engage to Campaign 70 SMS Opt-in and Opt-out synchronization between Campaign and Engage 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.. 95 Chapter 8. Reference: Mapping files.. 73 Chapter 9. Custom tracking tables Event types iv IBM Campaign and IBM Silverpop Engage: Integration Guide

5 Chapter 1. Overview of the integration The IBM Campaign integration with Engage combines the precision segmentation tools in Campaign with the robust, cloud-based messaging capabilities of IBM Engage. Through the integration, you can upload Campaign segmentation and contact data to Engage databases, contact lists, and relational tables. Then, use the information from Campaign with messaging tools in Engage to target specific audiences, individually personalize each message, and reach current and potential customers through and SMS text messages. 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. The integration is based on a package of scripts that you download and configure to enable a secure, automated exchange of segmentation, contact, and tracking data between Campaign and Engage. You can run data upload and download scripts from a command line or automate the data exchange by adding the scripts to the configuration of Campaign flowcharts. The integration of IBM Campaign and Engage at a glance. 1. In Campaign, segment your marketing database and upload the data to Engage. 2. In Engage, send and SMS messages that incorporate the data from Campaign. 3. When customers respond, Engage tracks the responses and makes selected data available for download to Campaign. 4. In Campaign, download the contact and tracking data from Engage to custom tables that you create in the Campaign schema. Use Campaign and other applications to act on the data from Engage. User actions for the integration The integration of IBM Campaign and Engage requires you complete tasks in both applications. In Campaign, you configure and run flowcharts that segment data in your marketing database and upload it to Engage. You then use Engage to design and send and SMS messages that incorporate the Campaign data. Finally, in Campaign, you can run download scripts to add response and tracking data to Copyright IBM Corp. 2014,

6 tables in the Campaign database schema. You can run the download scripts manually or schedule them to run at a specific time or on a recurring basis. The following diagram illustrates a typical sequence of actions in Campaign and Engage. 1. Upload data. In Campaign, you must run a flowchart that has been configured to include an upload script in a flowchart trigger. You can configure the script to upload Campaign data to databases, contact lists, or relational tables in Engage. The integration does not support uploading Campaign offer information or attributes. See Chapter 4, Data upload from Campaign to Engage, on page Send and SMS messages. In Engage, design and send your marketing message. You can address and personalize the messages with the information that you uploaded from Campaign. See the IBM Silverpop Knowledge Base at portal.silverpop.com.. 3. Message responses. Message recipients receive and respond to the messages that you send. 4. Download contact and tracking data. In Campaign, run scripts to download contact and tracking data to database tables in the Campaign schema. Downloaded contact and tracking data is added to tables in the Campaign database schema. The integration provides DDL scripts that you can run to create the custom tables. See Chapter 5, Contact data download, on page 53 and Chapter 6, Tracking data download, on page IBM Campaign and IBM Silverpop Engage: Integration Guide

7 Data flow in the integration The integration of IBM Campaign and Engage provides scripts and procedures that you can use to move marketing data from Campaign to Engage. The integration uses specific Campaign flowchart configurations and Engage APIs to support automatic upload of data from Campaign to Engage. In Engage, you can use the data to address and personalize and SMS messages. When the message recipients respond, you can run custom download scripts in Campaign to download response and contact data to integration tables in Campaign. The integration package includes DDL scripts that you can run to create the download tables in the Campaign schema. The following table and diagram illustrate the typical flow of data between Campaign and Engage. 1. Upload data. Campaign uploads data to Engage over secure FTP. The composition of the segment depends on the flowchart logic. The flowchart must contain a Mail List process and a flowchart trigger that incorporates a contact or table upload script. Upload SMS contact and required consent data taken from Campaign database. For consent upload, reference a custom mapping file. Upload from Campaign only what you need to send messages. Keep the rest behind the firewall. 2. Send and SMS messages. Create an Engage organization to create and manage your Engage databases, contact lists, and relational tables. Design and run Engage queries. Send SMS through IBM Silverpop and our SMS partner, mgage. The Engage consent Chapter 1. Overview of the integration 3

8 framework manages required SMS consent. Engage does not send SMS messages without explicit recipient consent. 3. Message responses. v Engage receives notifications for opens, clicks, Opt-in, Opt-out, and unsuccessful deliveries. v Engage updates databases, contact lists and relational tables with the response data. v Engage receives data for SMS messages. Contact data for SMS is available only by creating a query and downloading the results. v Standard tracking data is available from Engage, however, you can create additional custom tracking. 4. Download contact and tracking data. Run contact and table download scripts to download contact and tracking data to database tables in the Campaign schema. You can schedule data downloads to pull contact and tracking data automatically or you can run a download manually. You can also extract SMS opt-in and opt-out data, and then download the results to the integration tracking tables. The data that you retrieve from Engage databases, contact lists, and relational tables becomes available to Campaign flowcharts and tables. What you can do with the integration The integration of IBM Campaign with Engage is intended to give Campaign users a way to use messaging tools provided by Engage. Similarly, the integration provides Engage users with a way to access segmentation tools in Campaign. The integration provides 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 Use Engage to send messages that are addressed and personalized using segmentation data from Campaign. You can configure the data upload to automatically trigger a pre-configured mailing. In conjunction with a scheduled upload, this capability enables you to send a lights-out mailing. v When you trigger a mailing 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. Then, in Engage, send SMS messages that are addressed and personalized using the uploaded segmentation data. v Use integration download scripts and existing Campaign scheduling features to download non-sms contact data and tracking data from Engage. Schedule the data download for a specific time or on a recurring basis. v Download SMS contact data (not response data) from Engage. 4 IBM Campaign and IBM Silverpop Engage: Integration Guide

9 What you cannot do with the integration What s 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 The integration does not support Mobile Customer Engagement or custom landing pages. v You cannot use the integration to send SMS messages until you purchase SMS messaging for Engage and IBM provisions your Engage account to support SMS messaging. v You cannot download tracking data for SMS messaging. The trackingdownload script does not retrieve tracking data for SMS messaging. v You cannot configure a data upload to run an SMS campaign automatically after you upload SMS contact information. You cannot use the integration to run a lights-out SMS campaign. 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 Create an Engage contact list when you upload data from Campaign. contactupload on page 39. v Select existing Engage contact lists by name when you upload data from Campaign with the contactupload script. Previously, you could specify contact lists only by their list ID. contactupload on page 39. v Use the contactupload script to add additional identifiers to the names of mailings that you trigger automatically after a data upload. The additional information can help you to distinguish between multiple mailings and can assist you in response tracking and retargeting individual responses to your messages. Additional identifiers in mailing names on page 38 and contactupload on page 39. v Connect the integration to Engage through a proxy server. Connecting through a proxy server on page 20. v View detailed descriptions of the integration tracking tables. Chapter 9, Custom tracking tables, on page 79. 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 Silverpop Engage Integration Guide provides descriptions and procedures for concepts and tasks that are specific to the Chapter 1. Overview of the integration 5

10 integration. For concepts and tasks that apply to Campaign or Engage separately from the integration, see the general product documentation that is available for each application. v Product documentation for IBM Silverpop Engage is available in the Silverpop Knowledge Base at You must provide valid login credentials to access the Silverpop Support Portal. v Product documentation for Campaign is available on the IBM Product Support Portal 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. 6 IBM Campaign and IBM Silverpop Engage: Integration Guide

11 Chapter 2. Planning to integrate Campaign with Engage The first phase of integrating IBM Campaign with IBM Silverpop 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 prerequisites 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. Information that you might need to complete the prerequisites for Campaign or Engage is included here or in the supporting documentation for each product. Security considerations for Campaign and Engage IBM Campaign and IBM Silverpop 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 Silverpop. There is no single sign-on between the two products. Marketing users require separate user accounts to access Campaign and Silverpop. 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 19 Related tasks: Connecting through a proxy server on page 20 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. Copyright IBM Corp. 2014,

12 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. Security in IBM Silverpop Engage For more information on security in IBM Silverpop Engage, see the IBM Silverpop Knowledgebase. Related tasks: Configuring access to Engage on page 20 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 Silverpop 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 of Silverpop 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. 8 IBM Campaign and IBM Silverpop Engage: Integration Guide

13 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 Silverpop web forms. 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 27 Where to put uploaded data in Engage on page 29 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 Chapter 2. Planning to integrate Campaign with Engage 9

14 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. Integration prerequisites in Engage Before you can use Engage with Campaign, you must establish access to Engage. You must create an account to gain access on behalf of your organization and configure a system user with access to Engage to perform integration tasks. Related concepts: Integration prerequisites in Campaign on page 12 IBM Silverpop organization account To access IBM Silverpop Engage, you must provide a valid user name and password. You must have an IBM Silverpop account to receive a login. IBM Silverpop Engage manages user and application access to Engage through organizations that are created in Engage. Silverpop designates 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 Silverpop customer, you can use your existing account login to access Engage to configure the integration. If you are a Campaign user who is beginning to use IBM Silverpop Engage, your business organization must establish an account with IBM Silverpop. To request credentials to access IBM Silverpop 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 Silverpop user over a secure HTTPS connection. In the context of the IBM Campaign and IBM Silverpop integration, this user is referred to as the integration user. Before you begin Access IBM Silverpop Engage to complete this task. You must have a valid Silverpop 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 Silverpop 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. 10 IBM Campaign and IBM Silverpop Engage: Integration Guide

15 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 Silverpop 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 Silverpop 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 5. Click Save. 6. Go to Settings > Organization Settings. You must be a Silverpop 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. Chapter 2. Planning to integrate Campaign with Engage 11

16 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. Related tasks: Connecting through a proxy server on page 20 Integration prerequisites in Campaign Before you can use Engage with Campaign, you must update the IBM Omni-Channel Marketing environment, including the installations of IBM Platform and IBM Campaign. 12 IBM Campaign and IBM Silverpop Engage: Integration Guide

17 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. Related concepts: Integration prerequisites in Engage on page 10 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 Silverpop Engage requires IBM Campaign version or higher. 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. Chapter 2. Planning to integrate Campaign with Engage 13

18 14 IBM Campaign and IBM Silverpop Engage: Integration Guide

19 Chapter 3. Installing the Campaign integration with Engage Installing the integration files The integration of Campaign with Engage depends on a collection of files that you download from IBM devworks 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 Silverpop 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 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 Installation download package IBM_Campaign_Integration_with_IBM_Silverpop_Engage_1.2_Windows.zip UNIX or Linux IBM_Campaign_Integration_with_IBM_Silverpop_Engage_1.2_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. Copyright IBM Corp. 2014,

20 a. Copy and rename example_sp.properties to sp.properties. b. Configure sp.properties as instructed by comments in the file. 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 17 Configuring connections between Campaign and Engage on page 18 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: Manually downloading tracking data on page 64 Related reference: contactupload on page 39 tableupload on page 41 Script for downloading contact data on page 53 Script for downloading tracking data on page 61 Upgrading an existing integration of Campaign and Engage 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. 16 IBM Campaign and IBM Silverpop Engage: Integration Guide

21 Procedure Configuring access to JDBC 1. Backup the current <$CS_HOME> directory. You will need to use the backup files to replicate your configuration settings. 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_Silverpop_Engage_1.2_Windows.zip Linux or UNIX: IBM_Campaign_Integration_with_IBM_Silverpop_Engage_1.2_Unix-Linux.tar.gz 3. In the conf directory, open example_sp.properties. Add the new proxy properties to your sp.properties file. v sp.proxy.url URL for the web proxy server. v sp.proxy.username User name to access the web proxy server. v sp.proxy.password Password to access the web proxy server. 4. In the ddl directory, run the appropriate version of the cs_tab_upgrade_ _xxx.sql script for your database. v DB2: cs_tab_upgrade_ _db2.sql v Oracle: cs_tab_upgrade_ _ora.sql v 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 Silverpop 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 3. Installing the Campaign integration with Engage 17

22 2. Use your database client to run the DDL scripts against the database or schema that holds the Campaign system tables. v Microsoft SQL server: cs_tab_sqlsvr.sql v Oracle: cs_tab_ora.sql v 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 81 SP_BounceReply on page 82 SP_Click Records for link clicks in messages. SP_Click on page 82 SP_Conversion Records of Engage conversion events. SP_Conversion on page 83 SP_Forward Records of messages that were forwarded. SP_Forward on page 84 SP_Open Records of message opens. SP_Open on page 85 SP_OptIn Records that are marked as opted-in. SP_OptIn on page 86 SP_OptOut Records that are marked as opted-out. SP_OptOut on page 87 SP_Sent Records of messages sent. SP_Sent on page 88 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 88 SP_UploadAudit on page 89 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 15 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. 18 IBM Campaign and IBM Silverpop Engage: Integration Guide

23 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 15 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 Silverpop 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 Silverpop 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 Silverpop Engage. You can also configure properties in this file to specify how the system reports and responds to errors. Chapter 3. Installing the Campaign integration with Engage 19

24 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 Silverpop 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 Silverpop Engage on page 8 Connecting through a proxy server If your corporate data security plans demand separation between your corporate data and the public Internet, you can connect to the IBM Silverpop messaging environment through a web proxy server. About this task The proxy server must support HTTPS and SFTP traffic. The sp.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 sp.properties file is in the conf directory of <CS_HOME>. Note: If authenticated access to the proxy server is required, the user name and password for the proxy are assigned by your network administrator or IT staff. 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. 20 IBM Campaign and IBM Silverpop Engage: Integration Guide

25 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 sp.proxy.url Specify the URL for the web proxy server. v sp.proxy.username Specify the user name that is used to access the web proxy server. Leave blank if authenticated access is not required. v sp.proxy.password Specify the password that is used to access the web proxy server. Leave blank if authenticated access is not required. 3. Save sp.properties and verify the connection. Note: You must restart the Campaign Analytics server for the configuration changes to take effect. Related concepts: Security considerations for Campaign and Engage on page 7 Related tasks: Creating the integration user on page 10 Verifying the proxy server connection on page 22 Chapter 3. Installing the Campaign integration with Engage 21

26 Configuring an optional separate proxy server for FTP traffic if required If your business requirements or corporate policies demand that you route FTP traffic through a separate proxy server, you can modify sp.properties to provide the required configurations. Procedure 1. In the conf directory, open sp.properties in a text editor. 2. Add the following section at the end of the file. # ==================== # FTP proxy server address. sp.proxy.ftp.url= # To route FTP traffic through an FTP proxy server, enter the URL for # the proxy server. If you do not specify a value for this property, # the system does not route FTP traffic through the proxy server. # (Example) sp.proxy.ftp.url= # * If you enter an FTP proxy server address but do not enter an FTP # proxy server user name and password, the FTP proxy server # processes FTP traffic without requiring authentication. # ==================== # FTP proxy server user name. sp.proxy.ftp.username= # If the FTP proxy server requires a user name and password for # authentication, enter the user name as the value for this property. # * If you specify an FTP proxy server user name, you must also # specify the proxy server address as the value for sp.proxy.ftp.url # and proxy server password as the value for sp.proxy.ftp.password. # ==================== # FTP proxy server password. sp.proxy.ftp.password= # If the FTP proxy server requires a user name and password for # authentication, enter the password as the value for this property. # * If you specify an FTP proxy server password, you must also # specify the proxy server address as the value for sp.proxy.ftp.url # and proxy serveruser name as the value for sp.proxy.ftp.username. # ==================== 3. Save sp.properties and verify the connection. Verifying the proxy server connection From inside your local network environment, you can use an FTP client or command-line utility to verify that you can connect the FTP server to the proxy server. The client or utility that you use to verify the connection must support SFTP. Procedure You can use curl to upload a test file, as follows:./curl -x -U proxyusername:proxypassword sftp://engageuser:engagepassword@transfer<n>.silverpop.com/upload/ file/exampletestfile In this example, <N> represents the number of the Silverpop pod to which your organization is assigned. 22 IBM Campaign and IBM Silverpop Engage: Integration Guide

27 Note: This example contains line breaks to accommodate the presentation format. Related tasks: Connecting through a proxy server on page 20 Encrypting the integration configurations When you install the Campaign integration with Engage, configuration settings, including passwords, are visible in properties files. To encrypt certain settings so that sensitive information is not visible, run the encryptconfig script. Before you begin Run the trackingdownload script before you encrypt the configuration settings. Running trackingdownload verifies system configurations and the connection to Engage and Campaign data sources. The trackingdownload script is in the bin directory of <CS_HOME>. When you run the trackingdownload script, the system indicates in the command console if the run was successful. Look in the console for any reported errors. You must run trackingdownload without errors before you encrypt property files. The encryption is based on a password-based cryptography standard. By default, the encryption uses a password that is built into the integration code. You can further secure the configuration settings by defining a different password. You can define a different password for your environment by defining a custom encryption key. Defining a custom encryption key is optional. However, you must decide whether to define a custom encryption key before you encrypt the properties settings. If you choose to create a custom encryption key, you must do so before you run the encryptconfig script. About this task The encryptconfig script is in the bin directory in the folder where you installed the integration files. The script encrypts configuration values in jdbc.properties and sp.properties. The script encrypts only values that include the terms: password, secret, refresh, or access. When you run the encryptconfig script, the script replaces the displayed values for these settings with a string of encrypted characters. File jdbc.properties sp.properties Property cs.jdbc.password: Password for the Campaign database user sp.password: Password for the integration user. sp.client.secret: System generated authentication credential. sp.refresh.token: System-generated value for establishing access to Engage. Encrypting the value of a configuration property does not prevent you from changing the value. However, each time that you change the value, you must run encryptconfig again to encrypt the new value. Chapter 3. Installing the Campaign integration with Engage 23