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

28 You can encrypt values in jdbc.properties and sp.properties simultaneously or encrypt each file separately. Procedure Depending on your operating system, run encryptconfig.bat (Windows) or encryptconfig.sh (UNIX or Linux). v To encrypt jdbc.properties and sp.properties simultaneously, run the script as: <CS_HOME>/bin/encryptConfig. Example: <CS_HOME>\bin\encryptconfig.bat v To encrypt the files separately. Run encryptconfig with the -f parameter as: <CS_HOME>/bin/encryptconfig -f <absolute or relative path to CS_HOME>/conf/<properties file>. Example: <CS_HOME>/bin/encryptConfig.sh -f <CS_HOME>/conf/sp.properties The script encrypts values only in the property file that you specify with the -f option. Related tasks: Manually downloading tracking data on page 64 Related reference: Script for downloading tracking data on page 61 Creating a custom encryption key To apply increased local control over the encryption of sensitive configuration values, you can create a custom encryption key. This task is optional, but does provide an added layer of security. About this task When you create a custom encryption key, you change the password that the encryption script uses to hide sensitive configuration values. If you decide to create a custom encryption key, you must perform this procedure before you run the encryptconfig script. Define the value for the custom encryption key in a flat file. The file is considered the Encryption Key File and system administrators must restrict access to it. Enter the path to this file as a setting in the setenv file. Note: If you change the value of the Encryption Key File, you must remove the current encryption, repeat this procedure to create a new custom encryption key, and run encryptconfig again. If you do not repeat all of the steps in this process, the integration scripts will fail. Procedure 1. In a text editor, create a strong password for the encryption script and save the file as a text file. The file that you create is the Encryption Key File. Save the file in a folder outside of the bin directory. Restrict access to the directory in which you save the file. 2. In the bin directory of <CS_HOME>, edit the setenv file to specify the path to the Encryption Key File. Modify the ENCRYPTION_KEY_FILE setting, as follows. 24 IBM Campaign and IBM Silverpop Engage: Integration Guide

29 Windows (setenv.bat): set ENCRYPTION_KEY_FILE="- Dcom.ibm.emm.integration.silverpop.EncryptionKeyFile=<path to file>\<encryptionkeyfile>" UNIX or Linux (setenv.sh): ENCRYPTION_KEY_FILE=- Dcom.ibm.emm.integration.silverpop.EncryptionKeyFile=<path to file>/<encryptionkeyfile> Results The new custom password is used to encrypt values in jdbc.properties and sp.properties. What to do next Run the encryptconfig script to encrypt the configuration settings. Removing encryption from configuration properties Some situations require that you remove the encryption from encrypted properties. For example, to change the value for the Encryption Key File, you must remove encryption from all currently encrypted values before you can proceed. About this task Encrypted values can be found in jdbc.properties and sp.properties. The encrypted values appear as random strings. Procedure 1. In jdbc.properties and sp.properties, locate the encrypted values. Replace each encrypted value with its correct unencrypted value. 2. Save the file. On Windows, if you were using a custom encryption key and then stopped using the key, close all command prompts. Results After you complete this task, the configuration values appear without encryption. Chapter 3. Installing the Campaign integration with Engage 25

30 26 IBM Campaign and IBM Silverpop Engage: Integration Guide

31 Chapter 4. Data upload from Campaign to Engage Table 2. Overall data upload considerations Uploading contact data and segmentation from Campaign to Engage requires specific preparations and flowchart configurations. Use scripts that are provided with the integration to upload only the data that is required to compose, transmit, and track personalized messages in Engage. You can automate communication with your customers by configuring data uploads that trigger Engage mailings after uploads from Campaign. The scripts can direct the uploaded data to Engage databases, contact lists, and relational tables. You can run the scripts manually from a command line or automatically when you run a Campaign flowchart. The following table lists general issues and requirements that you must satisfy when you upload Campaign data and segmentation to Engage. Task Where More information Review the data that you plan to upload. Campaign What to upload from Campaign Prepare destinations for the uploaded data. Engage Where to put uploaded data in Engage on page 29 IBM Silverpop Knowledge Base at portal.silverpop.com. Create a placeholder offer. Campaign Placeholder offer for the Mail List process on page 29 Match field names in Campaign and Engage. Match date formats in Campaign and Engage. Use flowcharts in Campaign to segment data. Upload data automatically with flowcharts that contain a Mail List process and trigger that includes an upload script. Engage Mapping Campaign fields to Engage fields on page 33 Campaign Matching date formats on page 35 Campaign Automatically uploading data from Campaign to Engage on page 43 Manually uploading data from Campaign to Engage on page 43 What to upload from Campaign Through the integration of Campaign with Engage, you can upload data segmentation and contact data that you define in Campaign to databases, contact lists, and relational tables that you define in Engage. Upload only the data that you require to compose and send personalized messages to your target audience. To use data that is available in Campaign with the messaging features in Engage, you must upload the following types of segmentation and contact data. v Data for any keys that you define in the Engage database that you are using to support a mailing. v Any data that you use to personalize the messages that you send. v address information. Copyright IBM Corp. 2014,

32 For data that is used for messages, Engage databases expect address information to be available in a field named . You must map the field in your Campaign table that provides address information to the field in the Engage database to which you are uploading Campaign data. For Campaign data that is used in messages that involve SMS, Mobile Push Notification, CRM integration, or Engage Universal Behaviors, upload the Campaign data only to a non-keyed database in Engage. Do not upload data for these applications to a database that defines a specific unique identifier (UID). When you upload data from Campaign to a non-keyed database in Engage, you must use a custom mapping file. To upload segmentation data from Campaign customer files to an Engage database or contact list, use the contactupload script. To upload Campaign dimension table data to an Engage relational database, use the tableupload script. You can run the contactupload or tableupload script manually from the command prompt. You can also configure Campaign flowcharts to run either script as a flowchart trigger to upload the flowchart output automatically to Engage. Both scripts upload Campaign data in a tab-separated file. The first line in the tab-separated file must contain the field names for the Campaign data. The Campaign field names must match column names in the Engage database. If the column names in Campaign do not match, you have several options to either rename the fields or map them to the corresponding fields in Engage. The preferred approach is to rename the Campaign fields as you map them to various flowchart processes. Other options include defining derived fields or custom mapping files, if necessary. Related concepts: Data management for Campaign and Engage on page 8 Where to put uploaded data in Engage on page 29 Data required for SMS consent on page 68 Related reference: contactupload on page 39 tableupload on page 41 Upload preparation and requirements Uploading data from Campaign to Engage requires certain preparations and imposes specific requirements. Before you upload contact data and segmentation to Engage, confirm that you can meet the requirements and are ready you proceed. To upload contact data and segmentation from Campaign, ensure that the database field names in Campaign match the corresponding field names in Engage. You have several options to make certain that the field names match. When you upload date information from Campaign to Engage, the two applications must format the date information in the same way. Configuring a Campaign flowchart to upload contact data in a form that Engage can accept requires that you add a Mail List process to the flowchart. The Mail List process requires a Campaign offer. Although the Campaign integration with 28 IBM Campaign and IBM Silverpop Engage: Integration Guide

33 Engage does not support Campaign offers, you must define an empty placeholder offer to satisfy the requirements of the Mail List process. Placeholder offer for the Mail List process The Campaign integration with Engage uses a Mail List process to create the tab-separated file that the upload scripts upload to Engage. The design of the Mail List process requires a reference to a Campaign offer. To meet this requirement, you must create a placeholder offer that does not display an offer to message recipients. The placeholder offer is an empty offer. You can turn contact history off for the offer because it does not appear to message recipients. Note: The standard Campaign integration with Engage does not support Campaign offers. To create the placeholder offer, you must log in to Campaign with a user role that has permissions to Add Offers. When you create the offer, you must provide an offer name. For easier offer management, create a name that clearly relates the offer to the Campaign integration with Engage. For example, CampaignEngageOffer. The offer is automatically associated with a Campaign security policy and Campaign assigns a system-generated offer code. For more information about creating offers, see the IBM Campaign User's Guide. Where to put uploaded data in Engage In Engage, you can define several ways to store and segment data that you upload from Campaign. The destination for the data upload determines which upload script to run and how to configure the script. You can upload data from Campaign to any of the following types of data collections in Engage. Table 3. Destinations for uploaded data in Engage Destination Databases Description Engage provides Single Opt-in and Double Opt-in databases. They contain information about contacts that you can use to address and personalize messages that you send with Engage. Although you can upload contact information to a double-opt in database, the new records are not marked as opt-in until the message recipients complete the double opt-in process. You specify the database ID in an upload script. Chapter 4. Data upload from Campaign to Engage 29

34 Table 3. Destinations for uploaded data in Engage (continued) Destination Contact lists Description You can define one or more contact lists within a single Engage database. Each contact list defines a subgroup of message recipients and data that is related to them. You can upload data from Campaign directly to a contact list. When you upload data to a contact list, you are also adding the data to the parent Engage database. You specify the contact list ID or name in an upload script. If the contact list that you specify does not already exist in Engage, the upload script creates a new contact list. Relational tables An Engage relational table can associate multiple lines of data with a single database record. For example, in a relational table you can map records for multiple purchases, event attendances, or rewards to each message contact that is represented in the table. Typically, you upload contact data and segmentation from Campaign dimension tables to Engage relational tables. You specify the table ID in an upload script. Related concepts: Data management for Campaign and Engage on page 8 What to upload from Campaign on page 27 Mapping Campaign fields to Engage fields on page 33 Matching date formats on page 35 Related tasks: Uploading SMS contact data from Campaign to Engage on page 69 Finding contact list, database, and relational table IDs in Engage Engage assigns each database, contact list, and relational table a unique ID. You can specify this ID when you upload data from Campaign. For contact lists only, you can also specify the contact list name. About this task You can find the ID for a database, contact list, or relational table in Engage. The ID is described in the additional details for each type of data collection. Procedure 1. On the Data tab in Engage, navigate to the database, contact list, or relational table that you want to specify. The names display as links on the Databases, Contact Lists, or Relational Tables tabs. 2. Click the name of the database, list, or table that you want to identify. 3. Click Show Additional Details. The ID value displays on the right side of the summary window. Related reference: contactupload on page 39 tableupload on page IBM Campaign and IBM Silverpop Engage: Integration Guide

35 Script for downloading contact data on page 53 Script for downloading tracking data on page 61 Finding mailing IDs in Engage When you configure the contactupload script to trigger a mailing in Engage, you can specify the mailing ID for the mailing that you want to send. You must access Engage to determine the appropriate mailing ID. Procedure 1. On the Content tab in Engage, got to View Mailings and click Templates. The Mailings and Templates page opens and displays a list of available mailings as links. 2. In the list of mailings, hold the cursor over a mailing name. The mailing ID displays in a tooltip. 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 Engage keys and Campaign audience levels Campaign audience levels and Engage keys are related concepts. Understanding how each concept is used to identify contacts is important to using the integration effectively. In Campaign, tables that are accessed in a flowchart are associated with an audience level. The audience level is a unique key that might identify a single person, a household, or an entity, such as a business. Campaign administrators can define multiple audience levels as needed. Although a table must have a primary audience level, it can also have one or more secondary audience levels. In Engage, a database can have one or more key fields, or no key field at all. The keys that you define in an Engage database depends on the messaging channels and Engage features that you plan to use. An organization might have a single database or multiple databases, and each database can have different key fields. If you define a key field in a database, the key determines the messaging channels and Engage features that you can use with the database. For maximum flexibility in using Campaign data in multiple messaging channels, upload Campaign data to a single Engage database that does not define a key field. Consider the following issues when you select a database to receive data that you upload from Campaign. v You must provide values from Campaign for the key fields that you define in Engage. The fields do not need to be audience levels in Campaign. However, the values must be present in the output file that you generate from your flowchart. Chapter 4. Data upload from Campaign to Engage 31

36 v If you plan to use Campaign data exclusively for messaging, you can define a field that is called as a unique identifier (UID) in the Engage database that receives the uploaded data. The field name in Campaign must be . However, after you define as the key field for the database, you cannot use the database with additional channels later. v If you plan to use Campaign data for SMS, Mobile Push Notification, CRM integration, or Engage Universal Behaviors, you must upload to a single, non-keyed database in Engage. These features do not support working with multiple databases. Do not define a UID in a database that you use with these features. v When you upload data from Campaign to a non-keyed database, you must create a custom mapping file and specify the file as an upload parameter. v When you download opt-in or opt-out data, or tracking data from Engage, you can download additional fields from your database. To use the additional tracking data in flowcharts for further segmentation, you must ensure that the tracking data includes either the data for your audience level fields or other data that you can use in your flowchart to look up the audience ID for a particular contact. When to upload to a non-keyed database If you plan to use data from Campaign in messages that involve SMS, Mobile Push Notification, CRM integration, or Engage Universal Behaviors, upload the Campaign data to a single non-keyed database. Do not define a unique identifier (UID) for the database. When you upload data from Campaign to a non-keyed database in Engage, you must use a custom mapping file. In the mapping file, define how the fields in the Campaign database provide data that populates corresponding fields in the Engage non-keyed database. You can base the custom mapping file on example_mappingfile.xml that is available in the conf directory of the integration package. Modify the mapping file to include the <SYNC_FIELDS> property that is defined in example_smsmappingfile.xml. Use the <SYNC_FIELDS> property to define the field in Campaign that provides information that identifies each contact. Related concepts: Examples of typical upload triggers on page 47 Creating a custom mapping file for upload to a non-keyed database When you upload Campaign segmentation data to a non-keyed Engage database, you must designate a field that provides information that identifies each user. To specify the identifier field, use the <SYNC_FIELDS> property from example_smsmappingfile.xml in the conf directory. Procedure 1. Go to the conf directory in <CS_HOME>. 2. Copy example_mappingfile.xml. Rename the example file and save it in <CS_HOME>, or save it in another directory. Note the name and location because you must specify the path when you use it in an upload script. 32 IBM Campaign and IBM Silverpop Engage: Integration Guide

37 3. Open the mapping file in a text or XML editor. 4. In the conf directory, open example_smsmappingfile.xml in a text or XML editor. 5. In example_smsmappingfile.xml, copy the <SYNC_FIELDS> property and paste it into the mapping file that you copied. Place <SYNC_FIELDS> immediately before the <mapping> section. Results When you upload Campaign data to a non-keyed Engage database, specify the modified mapping file as a parameter in the upload script. In <SYNC_FIELDS>, the value of the <name> field must be something that is present in the uploaded Campaign data that uniquely identifies each contact. Related reference: Chapter 8, Reference: Mapping files, on page 73 Mapping Campaign fields to Engage fields You must match or map the field names in Campaign to the corresponding field names in Engage. The Campaign integration with Engage supports several methods to match or map field names in the uploaded data. Use the following methods, listed in the table in order of simplicity, to match the field names in Campaign and Engage. Table 4. Methods to match fields Matching method Change field names in Campaign. As you add flowchart processes to a Campaign flowchart, define Campaign Field Names that match the field names in Engage. As necessary, match all field names before you configure the Mail List process to create the tab-separated upload file. The first row of the upload file defines the column names for the data that you upload. Use derived fields in Campaign. If you cannot rename fields as you map tables to a flowchart, you can define derived fields that can map the names. For example, derived fields provide a means to resolve differences in date formats when you upload dates to an Engage relational table. Because you assign a name to the derived field, you can match a name that is defined in Engage. Create a custom mapping file. In cases where renaming fields or creating derived fields are not sufficient, you can configure a custom mapping file. The integration download package contains examples of custom mapping files that you can use as a model. More information Mapping field names in a flowchart on page 34 See the IBM Campaign User's Guide for more information about creating derived fields. Mapping fields with a custom XML file on page 34 Chapter 4. Data upload from Campaign to Engage 33

38 The method that you use can depend on your database name conventions, the upload destination in Engage, or the type of messaging. For example, you must use a custom mapping file when you upload data for use in SMS messages or mobile push notifications. Related concepts: Where to put uploaded data in Engage on page 29 Mapping field names in a flowchart When you map customer tables to a flowchart, you can change the name that Campaign uses to identify the fields in the table. You must match the field name that Campaign uses for a field to match the field name that is defined in the Engage database. About this task Campaign provides a series of related screens to map new tables and remap existing tables. When you specify a table name and field information, you can change the IBM Campaign Field Name to match a corresponding field in an Engage database. Changing the name of the field in the flowchart configuration is the simplest way to match field names in Campaign to field names in Engage. Changing the name in the table mapping does not change the field name in your customer database. Procedure 1. Edit the flowchart that you are using to select the data to upload to Engage. 2. From the Admin menu in the flowchart toolbar, select Tables. 3. Specify a table. Do either of the following steps. a. Select an existing table that contains the data that you want to map and remap the table. b. Add a table and select a table type Click Next. 4. Select Map to Existing Table in Selected Database, select the data source and click Next. 5. Select a source table. The source fields in the table that you select are mapped automatically to fields in the base record table that you are creating. To change the automatic mappings, use the field manipulation controls to add and move fields to the new table. Click Next. 6. In the IBM Campaign Field Name column, click the name of the field that you want to rename. Enter a name that exactly matches the corresponding field name in Engage. 7. Configure audience levels, if necessary and continue to click Next until you advance to the last configuration screen. 8. Click Finish. Mapping fields with a custom XML file In cases where changing the Campaign field name in the flowchart configuration is not feasible, you can create custom mapping files that explicitly define the relationship between Campaign fields and fields in Engage. 34 IBM Campaign and IBM Silverpop Engage: Integration Guide

39 About this task In particular, configure a custom mapping file to upload Campaign data to a non-keyed Engage database in the following applications: v SMS messages v Mobile Push notifications v CRM integrations v Engage Universal Behaviors A mapping file provides column names that are indexed to the sequence of values as they appear in the tab-separated list that is uploaded to Campaign. The first row of the tab-separated list provides column names. The mapping file defines the column names in the same order. The mapping file also provides information about how to process the list of values. Mapping files can become outdated due to changes to the database by multiple users over time. Changes in the configuration of the Mail List process that is used to upload data can also cause the mapping file to be inaccurate. Before you use a mapping file, confirm that the field mapping is still correct. A mapping file is a parameter to contactupload and tableupload. You can assign any name to this file. The parameters that are given to the scripts specify the location and name of the mapping file. The Campaign integration with Engage provides two example mapping files that you can use as models to create a custom mapping file. v example_mappingfile.xml example for upload to databases and contact lists v example_smsmappingfile.xml example for upload to support SMS messaging The SMS mapping file contains additional fields so that you can provide values for recipient consent. Using a mapping file is required when you use contactupload and tableupload to provide consent data from Campaign for use in SMS messages that are sent with Engage. Procedure Matching date formats 1. Go to the conf directory in <CS_HOME>. 2. Copy the mapping file that you want to modify. You can rename the example file and save it in <CS_HOME>, or you can save it in another directory. Note the name and location because you must specify the path when you use it in an upload script. 3. In a text or XML editor, open the mapping file. The file contains extensive comments to guide you in creating the custom mapping file for your application. 4. Save your changes. When you configure an upload script, you can use the -m (or --mapfile) option to specify the location of the mapping file. If the Campaign data that you are uploading includes date information, you must take additional steps to preserve the date format. In some cases, you might need to convert the date to a format that Engage supports. Chapter 4. Data upload from Campaign to Engage 35

40 Dates can be formatted in many different ways. If Campaign and Engage do not use the same date format, Engage might not correctly interpret the uploaded date information. The system might generate an error or an incorrect date. The Campaign integration with Engage provides the following ways to ensure that date information from Campaign is uploaded correctly to Engage. v You can set a default date format for all data uploads as a configuration property. However, date formats that you define in a custom mapping file override the default date format. v You can define date formats other than the default format as derived fields in the Campaign flowchart that you use to select the data in your customer tables. For example, defining derived fields is the only way correct date formats that do not match when you upload dates to Engage relational tables. Review your customer database to determine the format of date information that you might want to use in Engage. Determine the most common format and configure it as the default date format. Define custom date formats as necessary when you prepare the data upload. Related concepts: Where to put uploaded data in Engage on page 29 Default date format for uploads To help ensure that date values upload to Engage in the expected format, you can define a default date format in the config.properties file. By default, the config.properties file is in the conf directory where the integration files are saved on the Campaign Analytics server. The default date format is saved as the value for the importlist.dateformat configuration. The default setting for importlist.dateformat is MM/dd/yyyy. For example, a date in this format displays as 06/15/2014. You can change this value to match the date format that is most common in your customer database. The date format that you select as the default format must match one of the date formats that is supported by Engage. Uploading dates with derived fields You can upload dates that do not follow the organization default date format by defining a derived field to upload the date with a different date format. About this task You can define a custom date format with a derived field to pass date information to an Engage relational table. Derived fields are variables that do not exist in a data source and are created from one or more existing fields, even across different data sources. You can use a macro in Campaign to define a derived field that provides date values in a way that Engage can recognize, based on the date format used by a field in your customer database tables. For more information about working with derived fields, see the IBM Campaign User's Guide. 36 IBM Campaign and IBM Silverpop Engage: Integration Guide

41 Derived fields for uploading dates to Engage must define the following elements. v Campaign field that you want to map. v Date format for the Campaign field. v Output date format. The output date format must match a date format that is supported in a Engage database or relational table. To use a derived field to upload a date field to Engage, you can use the DATE_FORMAT macro in a flowchart process configuration. The macro uses the following syntax. DATE_FORMAT(date_string, input_format, output_format [, max_length]) date_string input_format output_format Campaign field that provides the date. Date format of the Campaign field. Date format in Engage. max_length (Optional) Limit the length of the date. The default is 32 characters. For example, you can define a derived field as, DATE_FORMAT(customer.purchDate, DELIM_M_D_Y, "%m/%d/%y" ). v customer.purchdate is the field in your customer database v DELIM_M_D_Y describes a date format of month, day, year, separated by some type of delimiting character. The character can vary, depending on the database that supports your customer tables. v %m/%d/%y defines the date output. This format displays March 17, 2014 as 03/17/2014. You can define derived fields in the Mail List process that generates the tab separated file for upload to Engage. Procedure 1. In the flowchart that selects the data that you want to upload to Engage, edit the Mail List process. 2. In the Mail List process, click the Personalization tab and click Derived Fields. The Create Derived Fields screen opens. 3. Give the derived field a name. 4. Click Formula Helper. Open the Date and Time Functions, and double click DATE_FORMAT. The DATE_FORMAT macro displays in the Expression field as DATE_FORMAT() 5. In the Available Fields section, select the field that provides the date that you want to upload. Click Use to add the field to the Expression field. 6. Configure the expression. DATE_FORMAT takes 3 required arguments. The arguments must appear inside the parentheses, as follows: DATE_FORMAT(<date_string>, <input_format>, "output_format") a. Move the field name to be inside the parentheses into the position defined as date_string. Chapter 4. Data upload from Campaign to Engage 37

42 b. Define input_string. By default format is DELIM_M_D_Y. (Month, Day, Year separated by a delimiter character). To see a list of possible date formats, see the embedded help in the Formula Helper for the DATE function. c. Define output_format. The output characters must appear between the quotation marks. For a list of output options, see the embedded help in the Formula Helper for the DATE_FORMAT function. The date format must be a format that is supported by Engage. d. Click Check Syntax to confirm that there are no errors in the expression. 7. Click OK. 8. On the Personalization tab, add the new derived field to the list of fields in the Export Fields field. Click OK. Results When you run the flowchart, the output file contains the date information in a format that Engage can accept. Additional identifiers in mailing names The contactupload script provides an option to add additional information to the names of mailings that you trigger automatically after a data upload. You can use the identifiers for tracking and retargeting message responses. You can use the contactupload script to automatically trigger an Engage mailing when you upload data to an Engage contact list. The mailing is based on an existing Engage mailing template that assigns a mailing name. The contactupload script provides an option to add additional information to the mailing name when you trigger a mailing after a data upload. For example, you can add a campaign code that you define in Campaign to the name of the mailing that Engage sends. You can use this additional information to distinguish between multiple mailings. The mailing name, including the additional identifier, is included as part of response data downloads. The mailing name is added to the MailingName field in the integration tracking tables. After downloading the data, including the mailing name, you can run additional processes to segment the response data based on the additional identifier that you added to the mailing name. Related concepts: Example: Upload to a contact list and trigger a mailing with a modified mailing name on page 49 Related reference: contactupload on page 39 Scripts for uploading data from Campaign to Engage The integration of IBM Campaign with IBM Silverpop Engage uses two scripts to upload data that you select in Campaign and upload over secure FTP to Engage databases, contact lists, and relational tables. Where you store the uploaded data in Engage determines the script that you must use. 38 IBM Campaign and IBM Silverpop Engage: Integration Guide

43 The integration of Campaign with Engage provides the contactupload script and the tableupload script. Each script includes several options for specifying the source and the destination of the upload. You can run the scripts manually from the command prompt or run them programmatically by incorporating them into Campaign flowchart triggers. So, how you configure the script in the trigger determines how and to where Campaign data is uploaded to Engage. contactupload Use contactupload.bat (Windows) or contactupload.sh (UNIX or Linux) to upload a tab-separated file that contains contact and segmentation data from IBM Campaign to databases and contact lists in IBM Silverpop Engage. Confirm that the column names that you select in Campaign match the corresponding column names in the Engage database. You can change column names when you map tables to a flowchart. Use the ability to change column names in Campaign to match the names in Engage. If you cannot match the names, you must use other methods, such as derived fields or custom mapping files to establish the match. If you use a custom mapping file, you must reference it as a parameter in the contactupload script. The contactupload script is located in the bin directory of the <CS_HOME> directory. The <CS_HOME> directory is the folder on the Campaign Analytics server where the integration files are installed in../campaign/partition/ partition[n]/<cs_home> Run the contactupload script from a command line on the Campaign Analytics server. You must have access to the Campaign Analytics server and user permissions that allow you to run scripts. You can specify an Engage contact list by its list ID or by its name. Contact list names must conform to Engage contact list name requirements and must contain only ASCII characters. If the list name includes spaces, you must enclose the name in quotation marks. You can also create a new contact list by specifying a contact list name that is not already in use by your organization in Engage. Usage contactupload (-i <inputfile>) (-l <datbaseid> [-p <contactlistids> -t <import_type>] -m <mappingfile>) [-e <templateid> -g <recipientlistid> -r -c <configpropertiesfile> -s <sppropertiesfile> -j <jdbcpropertiesfile> -k <campaigncode>] Option Description -i --inputfile (Required) Path to the tab-separated file that contains the list of values to be uploaded to Engage. Absolute or relative path to <CS_HOME>. -l --listid ID of the Engage database that receives the uploaded values. Specify the ID as defined in the Engage interface. Do not use with custom mapping file (-m). Does not upload values to child databases. Chapter 4. Data upload from Campaign to Engage 39

44 Option Description -m --mapfile Absolute or relative path to a file (.xml) that defines the mapping between fields in the input file and fields in the Engage database. Specify the database ID in the mapping file. Optionally, specify contact list ID values. Required for SMS messaging. Do not use with: (-l), (-t), (-p). -t --ImportType If no value is specified, the system adds and updates records in the specified Engage database with data from the input file (-i). All input values are considered Opt-In contacts. If you specify (-t OPT_OUT), the uploaded records that match existing records are added as Opt-Out contacts. Do not use if you specify a custom mapping file (-m). -p --contactlistids Use to upload contact data to one or more contact lists that are defined in Engage. Specify the ID or name of the contact list to which you are uploading. Upload to multiple lists by providing a comma-separated list (no spaces) of contact list IDs or names. If you pass one or more contact list names, the script gets a list of all shared contact lists for your organization from Engage and matches to existing list IDs. If the script finds a match to an existing contact list, the script uploads to the list. If the script does not find an existing list that matches the list name that you pass, the script calls an API to create a new shared contact list in Engage with the name that you passed in the script. Contact list names cannot start with a digit, must contain only ASCII characters, and must conform to Engage list naming requirements. List names that include spaces must be enclosed by quotation marks. Do not use this option if you specify a custom mapping file (-m). -e --MailingTemplateID When specified, Engage sends a mailing after the segmentation data is uploaded and added to the database that you specify with the (-l) option. Enter the mailing template ID of the template that defines the mailing configuration. The template must specify the same contact list as you specify with the (-p) option or the (-m) option. When uploading data to multiple contact lists, use the (-g) option to identify the list of message recipients. See also the (-k) option to prepend a campaign code to the mailing name. Not supported for SMS messaging. -g --RecipientListID Use when uploading values to multiple contact lists and sending an (-e). Specify the ID or name of the contact list that defines the single list of message recipients. If you pass one or more contact list names, the script gets a list of all shared contact lists for your organization from Engage and matches to existing list IDs. If the script finds a match to an existing contact list, the script uploads to the list. With the (-g) option, if the script does not find an existing recipient list that matches the list name that you pass, the script fails and reports an error. Not supported for SMS messaging. -r --removecontactdata When specified, the system removes values in a contact list and replaces them with the values that are contained in the uploaded tab-separated file. You must specify the contact list IDs with either the (-p) option or in a mapping file (-m). 40 IBM Campaign and IBM Silverpop Engage: Integration Guide

45 Option Description -c --configpropertiesfile Path to the config.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location. [Default: <CS_HOME>/conf/configuration.properties.] Paths with spaces must be enclosed in quotation marks. -s --sppropertiesfile Path to the sp.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location. [Default: <CS_HOME>/conf/sp.properties.] Paths with spaces must be enclosed in quotation marks. -j --jdbcpropertiesfile Path to the jdbc.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location. [Default: <CS_HOME>/conf/jdbc.properties. Paths with spaces must be enclosed in quotation marks. -k --campaigncode When used with the (-e) option, you can add information to the name of an Engage mailing as a prefix. You can use this option to distinguish between mailings if you upload data to send multiple mailings. For example, you can add a campaign code that you define in Campaign to the mailing name. However, the additional identifier can be any string that you define. The additional information that you add is preserved as part of the mailing name during data download. The mailing name that you define is available in the MailingName field in the integration tracking tables. The format of the mailing name is <campaigncode> <mailing template name> <timestamp>. Related concepts: Examples of typical upload triggers on page 47 What to upload from Campaign on page 27 CS_HOME directory on page 16 Additional identifiers in mailing names on page 38 SMS Opt-in and Opt-out synchronization between Campaign and Engage on page 72 Related tasks: Finding contact list, database, and relational table IDs in Engage on page 30 Finding mailing IDs in Engage on page 31 Automatically uploading data from Campaign to Engage on page 43 tableupload Use tableupload.bat (Windows) or tableupload.sh (UNIX or Linux) to upload a tab-separated file that contains contact and segmentation data from IBM Campaign to a relational table in IBM Silverpop Engage. You must create the Engage relational table to which you are uploading data before you run the script to upload data from Campaign. Note: The tableupload script does not accept table names as input, nor does it create a new table if the table does not already exist in Engage. Relational tables can accept data from Campaign dimension tables or data tables that you create in Campaign. Relational tables are useful for storing multiple Chapter 4. Data upload from Campaign to Engage 41

46 records that are related to a single record. For example, for each individual that is represented in the Campaign table, you can store the list of purchases for the past year or the list of preferred travel destinations. Confirm that the column names that you select in Campaign match the corresponding column names in the Engage database. You can change column names when you map tables to a flowchart. Use the ability to change column names in Campaign to match the names in Engage. If you cannot match the names, you must use other methods, such as derived fields or custom mapping files to establish the match. If you use a custom mapping file, you must reference it as a parameter in the tableupload script. The tableupload script is in the bin directory of the <CS_HOME> directory. The <CS_HOME> directory is the folder on the Campaign Analytics server where the integration files are installed in../campaign/partition/partition[n]/<cs_home> Run the tableupload script from a command line on the Campaign Analytics server. You must have user access to the Campaign Analytics server and permissions to run scripts. Usage tableupload (-i <inputfile>) (-l <tableid> -m <mappingfile>) [-c <configpropertiesfile> -s <sppropertiesfile> -j <jdbcpropertiesfile>] Option Description -i --inputfile (Required) Path to the tab-separated file that contains the list of values to be uploaded to Engage. Absolute or relative path to <CS_HOME>. -m --mapfile Absolute or relative path to a file (.xml) that defines the mapping between fields in the input file and fields in the Engage database. Specify the database ID in the mapping file. Optionally, specify contact list ID values. Do not use with: (-l), (-t), (-p). -l --listid ID of the Engage relational table that receives the uploaded values. Specify the ID as defined in the Engage interface. Do not use with custom mapping file (-m). -c --configpropertiesfile Path to the config.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location. [Default: <CS_HOME>/conf/configuration.properties.] Paths with spaces must be enclosed in quotation marks. -s --sppropertiesfile Path to the sp.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location. [Default: <CS_HOME>/conf/sp.properties.] Paths with spaces must be enclosed in quotation marks. -j --jdbcpropertiesfile Path to the jdbc.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location. [Default: <CS_HOME>/conf/jdbc.properties. Paths with spaces must be enclosed in quotation marks. Related concepts: Examples of typical upload triggers on page 47 What to upload from Campaign on page 27 CS_HOME directory on page IBM Campaign and IBM Silverpop Engage: Integration Guide

47 Related tasks: Finding contact list, database, and relational table IDs in Engage on page 30 Finding mailing IDs in Engage on page 31 Manually uploading data from Campaign to Engage To manually upload data from Campaign to Engage, run the contactupload or tableupload script from a command line on the Campaign Analytics server. About this task Running the contactupload script manually can be useful during testing and troubleshooting before you automate data uploads by adding the script to triggers in Campaign flowcharts. Procedure 1. Open a command line. 2. Change directory to the bin directory in your <CS_HOME> directory. 3. Run either contactupload or tableupload with the options that you require. Help is available for the scripts on the command line. Enter -h or --help. Automatically uploading data from Campaign to Engage Automatically uploading Campaign data to an Engage database involves a series of procedures that involve a flowchart that contains a Mail List process and a flowchart trigger. Running the flowchart creates a tab-separated list of field values that is uploaded to Engage automatically when the flowchart run finishes. About this task Table 5. Automatic upload configuration tasks Using a Campaign flowchart and a stored trigger to automatically upload data from Campaign to Engage involves the general steps that are listed in the following table. The trigger that you add to the Mail List process contains the contactupload script. The trigger configuration determines what you upload to Engage. See the upload trigger examples for how to configure triggers for typical upload scenarios. Task In Campaign, create or edit a flowchart. Modify the flowchart as needed to select the information that you want to upload to Engage. Match Campaign field names to Engage field names. Create a flowchart trigger that references an upload script and the tab-separated file that is generated by the Mail List process. More information See the IBM Campaign User's Guide for information about creating and configuring flowcharts. Flowchart design for data upload to Engage on page 44 Creating a flowchart trigger for automatic data upload on page 45 See also, the trigger examples for various upload scenarios. Chapter 4. Data upload from Campaign to Engage 43

48 Table 5. Automatic upload configuration tasks (continued) Task Add a Mail List process to the flowchart. Connect upstream processes as inputs to the Mail List process. Configure the Mail List process. Add a trigger to define what to upload. Save and run the flowchart. When the run finishes, the upload script triggers an upload of the flowchart output to the specified destination in Engage. More information Configuring a Mail List process for automatic data upload to Engage on page 46 Where to put uploaded data in Engage on page 29 What to do next Log in to IBM Silverpop Engage to compose and send messages based on the data that you uploaded. After you send the messages, download contact and tracking data to evaluate the response to your message and plan the next steps. Related concepts: Examples of typical upload triggers on page 47 Related tasks: Uploading SMS contact data from Campaign to Engage on page 69 Related reference: contactupload on page 39 Flowchart design for data upload to Engage The flowcharts that you create to select data for upload to Engage use the same flowchart processes and follow the same design practices as flowcharts that you create for other purposes. However, several additional considerations apply when you design a flowchart to upload data to Engage. v The names of the database fields that you select with the Campaign flowchart must exactly match corresponding fields in Engage. You must be familiar with the Engage databases and tables that you want to populate. As necessary, assign Campaign Field Names that match the field names in Engage. v Flowcharts that you use to upload data to Engage must contain a Mail List process that generates output as a tab-separated file. Add the Mail List as the final process in the flowchart. v Because uploading data is often an automated process, flowcharts that you use to upload data to Engage contain a trigger to run an upload script as soon as a flowchart run completes. Related tasks: Creating a flowchart trigger for automatic data upload on page 45 Configuring a Mail List process for automatic data upload to Engage on page IBM Campaign and IBM Silverpop Engage: Integration Guide

49 Creating a flowchart trigger for automatic data upload In a Campaign flowchart, you can create a stored trigger that incorporates an upload script. You can configure the script to trigger a data upload to an Engage database, contact list, or relational table each time the flowchart run finishes. Before you begin Confirm that you have permissions to create triggers in Campaign. Check with your Campaign administrator. Procedure 1. When you edit a flowchart, open the Options icon and select Stored Triggers. The Stored Trigger Definitions window opens. 2. Click New Item. The data fields for the new trigger appear on the right of the window. 3. You can select a folder to save the trigger to in the Save Under list. Note: The folder location governs which users can access the trigger, based on the folder's security policy. 4. Enter a name for the trigger in the Name field. v You cannot use spaces in the string, but you can use underscores ( _ ). v This name must be unique within the folder where you save it. 5. If you are creating a trigger in the top-level folder, select a security policy, or keep the default. 6. You can enter a description of the trigger in the Note field. You can provide a free-form text description of the trigger for documentation purposes. You also might want to keep a modification history of who modified the trigger, when, and what changes were made. 7. In the Command field, enter the contactupload or tableupload script. The choice of script and how you configure the script parameters determine whether the flowchart output uploads to an Engage database, one or more contact lists, or to a relational table. Note the name and location of the input file that you specify with the -i option. You must specify the same file as the output of a Mail List process when you add the trigger to a flowchart to automatically upload data to Engage. For example, to upload to an Engage database in Windows, you might enter: <CS_HOME>\bin\contactUpload.bat -i C:\IBM\Campaign\partitions\ partition1\dataexport\spflowchart1.tsv -l To upload to a relational table in UNIX or Linux: <CS_HOME>/bin/ tableupload.sh -i /data/ibm/campaign/partitions/partition1/dataexport/ SPFlowchart1.tsv -l <CS_HOME> represents the directory on the Campaign Analytics server where you installed the Campaign integration with Engage files. 8. Click Save and Close. What to do next Configure a Mail List process to automatically upload contact data to Engage. Related concepts: Chapter 4. Data upload from Campaign to Engage 45

50 Flowchart design for data upload to Engage on page 44 Configuring a Mail List process for automatic data upload to Engage In a Campaign flowchart, you can add a Mail List process to assemble the output of upstream flowchart processes into a tab-delimited file that can be uploaded to Engage. To support automatic data upload to Engage, the Mail List process works with a stored flowchart trigger. About this task In a flowchart, you can connect one or more configured processes to the Mail List process. The processes that you connect must produce output cells, which serve as input to the Mail List process. For example, a Select process produces a list of IDs, so its output can serve as input to the Mail List process. Procedure 1. Open a Campaign flowchart for editing. Either add a Mail List process to the flowchart or configure an existing Mail List process. 2. Connect one or more configured processes as input to the Mail List process. Select input cells that, when you run the flowchart, provide the data that you want to upload to Engage. Important: All of the cells that you select as input cells must have the same audience level. 3. Double-click the Mail List process in the flowchart workspace. The process configuration dialog opens. 4. Use the Fulfillment tab to specify the input to the list and to specify the form of the output. a. From the Input list, specify the cells to use as the data source for the list. Note: The Multiple Cells option is available only if the input process generates multiple cells or if more processes feed into the contact process. b. By default, Enable Export To is selected by default. Leave Enable Export To selected, and configure the following options: v Select File from the Enable Export To list. Provide a file name and other details, including where to save the file. Make a note of the file name and location. v Specify the output file as a Delimited File and select Tab as the delimiter. Select Include Labels in Top Row. v Select Replace All Records to indicate how to handle updates to the output file. This option removes any existing data from the file and replaces it with the new information. c. Select Send Trigger(s), and choose the trigger that you want to send. The selected trigger is listed in the Send Trigger(s) field. Note: Always place a question mark (?) after the trigger command so that, if the trigger fails, a red X displays on the Mail List process to inform you of the problem. 5. On the Treatment tab, select the placeholder offer. 46 IBM Campaign and IBM Silverpop Engage: Integration Guide

51 6. On the Personalization tab, specify which fields to add to the upload file. For example, add a field that provides an address. v The Export Field list indicates which fields to write to the output list. v If you selected a file on the Fulfillment tab, the Export Field list is empty and you must specify which fields to output. v When you select Candidate Fields, you can click the arrow next to an item to expand it. Use Ctrl+Click or Shift+Click to select multiple fields. v To view the values in a field, select the field and click Profile. v Use the Add and Remove controls to adjust the contents of the list. v The order of the fields in the Export Fields list determines the order that the data is written out. 7. On the Log tab, clear Log to Contact History Tables. You must have the appropriate permissions to enable or disable the contact history log options. 8. (Optional) Use the General tab to assign a name and descriptive notes to the process. 9. Click OK. Related concepts: Flowchart design for data upload to Engage on page 44 Examples of typical upload triggers Preparation and procedures for uploading Campaign data to Engage is the same for all types of data except for the configuration of the trigger that you add to the Mail List process in a flowchart. The trigger is based on the contactupload script or the tableupload script. How you configure the script depends on the type of data that you want to upload and on the destination of the data in Engage. 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. The following sections provide examples of how to configure the flowchart trigger in typical upload scenarios. Related concepts: When to upload to a non-keyed database on page 32 Related tasks: Automatically uploading data from Campaign to Engage on page 43 Related reference: contactupload on page 39 tableupload on page 41 Example: Upload to an Engage database To configure a flowchart to automatically upload Campaign data to an Engage database, add a flowchart trigger that contains the contactupload script to the Mail List process. The script must reference the database ID. Chapter 4. Data upload from Campaign to Engage 47

52 In the trigger, configure contactupload as follows. contactupload -i <inputfile> -l <databaseid> For example: <CS_HOME>\bin\contactUpload.bat -i..\<a folder>\fc_out.tsv -l When the flowchart run finishes, the trigger runs the script and the system uploads the tab separated input file to the specified Engage database. Example: Upload to a contact list To upload Campaign data to a single Engage contact list, run the contactupload script from a command line on the Campaign Analytics server or as part of a flowchart trigger. You must specify the ID or name of the contact list and the parent database of the contact list. In the trigger, configure contactupload as follows. contactupload -i <inputfile> -l <databaseid> -p <contactlistid> For example: <CS_HOME>\bin\contactUpload.bat -i..\<a folder>\fc_out.tsv -l p When the flowchart run finishes, the trigger runs the script and the system uploads the tab separated file that contains the flowchart output to the Engage database. Only the database rows that are specified in the contact list are modified. Example: Upload to a contact list identified by name You can run the contactupload script to upload data to an existing Engage contact list that you identify by name, instead of by list ID. Run the contactupload script from a command line on the Campaign Analytics server or as part of a flowchart trigger. In a flowchart trigger, configure contactupload as follows. contactupload -i <inputfile> -l <databaseid> -p <contact list name> For example, <CS_HOME>\bin\contactUpload.bat -i\<a folder>\fc_out.tsv -l p CustomerAprilBday In this example, the flowchart logic selects customers that celebrate birthdays during the month of April so that you can send a Happy Birthday . The contact list that is specified by ( p) is not unique, but it is easy to remember that it is one of twelve lists that you might create in advance in an Engage database. When the flowchart runs, the contactupload script finds an existing contact list with the same name. The script uploads the customer data to the existing contact list. Example: Upload and create a new contact list When you upload data from Campaign to Engage, you can create a new contact list by specifying a contact list name that is not already used within your Engage 48 IBM Campaign and IBM Silverpop Engage: Integration Guide

53 organization. Run the contactupload script from a command line on the Campaign Analytics server or as part of a flowchart trigger. In a flowchart trigger, configure contactupload as follows. contactupload -i <inputfile> -l <databaseid> -p <contact list name> For example, <CS_HOME>\bin\contactUpload.bat -i\<a folder>\fc_out.tsv -l p "newcust_wkof " In this example, the flowchart logic selects new customers that were registered during the previous week so that you can send a welcome . Because the contact list name that is specified by ( p) includes a specific date, the name does not match any existing contact list. When the flowchart runs, the contactupload script cannot find an existing contact list with the same name. It calls an Engage API to create a new contact list to receive the data for the new customers. If you run the same flowchart again, the new upload overwrites the existing list because the script now sees a name match and uploads the data to the list. Notice that because the new contact list name includes a space, you must enclose the name in quotation marks. Example: Upload to a contact list and trigger a mailing You can upload Campaign data to an Engage contact list and automatically send an Engage mailing that references the updated contact list. To trigger the mailing in Engage when the upload completes, specify a mailing template ID when you configure the contactupload script. In the trigger, configure contactupload as follows. contactupload -i <inputfile> -l <databaseid> -p <contactlistids> -e <templateid> To determine the mailing template ID, log in to Engage, go to the list of mailings, and hold the cursor over the mailing name. The ID displays in a tooltip. Example: <CS_HOME>\bin\contactUpload.bat -i..\<a folder>\fc_out.tsv -l p e When the flowchart run finishes, the system uploads the tab separated file that contains the flowchart output to Engage. If the mapping file specifies contact lists as the upload destination, only the rows that are specified in the various contact lists are modified. When the upload is complete, Engage processes the new contact list and transmits messages to the specified recipients, based on the information in the updated contact list. Example: Upload to a contact list and trigger a mailing with a modified mailing name You can configure the contactupload script to trigger a mailing that is identified by additional information in the mailing name. Chapter 4. Data upload from Campaign to Engage 49

54 You can run the contactupload script that triggers a mailing from several different flowcharts or from the same flowchart at multiple times. Each flowchart run might generate a different segment or can be associated with a different campaign. To distinguish the resulting mailings, you can append additional information to the mailing name. The script also appends a timestamp to the name. In each flowchart trigger, configure contactupload as follows. contactupload -i <inputfile> -l <databaseid> -p <contactlistids> -e <templateid> -k <campaigncode> For example, to send and identify a limited time promotional mailing to Gold customers, configure a flowchart trigger as follows. <CS_HOME>\bin\contactUpload.bat -i..\<a folder>\fc_out.tsv -l p e k goldcust When the flowchart runs, the script uploads selected customer data and triggers a preconfigured personalized to Gold customers. The mailing name format is <campaign code> <mailing template name> <timestamp>. For example, goldcust WeeklyDealsNSteals 04:01:15:01:59. When Gold customers respond, you can download the contact data. The unique mailing name is available in the MailingName field in the integration tracking tables to support additional post-processing. Related concepts: Additional identifiers in mailing names on page 38 Example: Upload to multiple contact lists To upload Campaign data to multiple Engage contact lists, run the contactupload script from a command line on the Campaign Analytics server or as part of a flowchart trigger. Specify the multiple contact lists by entering a comma-separated list of contact list IDs as a parameter for contactupload. In the trigger, configure contactupload as follows. contactupload -i <inputfile> -l <databaseid> -p <contactlistids> Example: <CS_HOME>\bin\contactUpload.bat -i..\<a folder>\fc_out.tsv -l p 98765,43211,10298 Do not include spaces after the commas when you specify contact list IDs for the p option. When you run the flowchart, the system uploads the tab-separated file that contains the flowchart output to the Engage database. Only the database rows that are specified in the various contact lists are modified. 50 IBM Campaign and IBM Silverpop Engage: Integration Guide

55 Example: Upload to multiple contact lists and trigger a mailing You can upload Campaign data to multiple Engage contact lists and automatically send an Engage mailing that references one of the updated lists. To trigger the mailing in Engage when the upload completes, specify a mailing template ID when you configure the contactupload script. In the trigger, configure contactupload as follows. contactupload -i <inputfile> -l <databaseid> -p <contactlistids> -e <templateid> -g <recipientlistid> Example:..\bin\contactUpload.bat -i..\<a folder>\fc_out.tsv -l p 98765,43211, e g Do not include spaces after the commas when you specify contact list IDs for the p option. After the flowchart run finishes, the system uploads the tab-separated file that contains the flowchart output to the Engage database. Only the rows that are specified in the various contact lists are modified. When the upload is complete, Engage updates all of the contact lists that are specified with the -poption and sends the mailing that you specify with the -e option to the contact list that you specify with the -g option. Example: Upload data to an Engage relational table You can use the tableupload script to upload data from Campaign dimension tables to an Engage relational table. In the trigger, configure tableupload as follows. tableupload -i <inputfile> -l <tableid> For example: <CS_HOME>\bin\tableUpload.bat -i..\<subfolder>\fc_dt_out.tsv -l When the flowchart run finishes, the system uploads the tab separated file that contains the flowchart output to the Engage relational table. The contents of the relational table are now available for use in Engage mailings or queries. Note: You cannot trigger an Engage mailing automatically after you upload data to a relational table. Example: Upload data as specified in a mapping file When you upload Campaign data to Engage, you can use a mapping file to map field names in Campaign to fields in an Engage database or relational table. In the file, you specify the target database, contact list, or relational table. Optionally, you can specify multiple contact lists for the upload. In the trigger, configure contactupload as follows. contactupload -i <inputfile> -m <mapping_file> Chapter 4. Data upload from Campaign to Engage 51

56 For example: <CS_HOME>\bin\contactUpload.bat -i..\<sub-folder>\fc_out.tsv -m..\<sub-folder>\map_fc_out.xml For upload to a relational table: <CS_HOME>\bin\tableUpload.bat\ -i\<sub-folder>\fc_out.tsv -m..\<sub-folder>\map_fc_out.xml When the flowchart run finishes, the system uploads the tab separated file that contains the flowchart output to Engage. If the mapping file specifies contact lists as the upload destination, only the rows that are specified in the various contact lists are modified. Related concepts: Data required for SMS consent on page 68 Related reference: Chapter 8, Reference: Mapping files, on page 73 Example: Upload mapped data and trigger a mailing When you upload Campaign data to Engage and specify a mapping file, you can also trigger an Engage mailing after the upload completes. This option is available only when you upload to a single contact list. In the trigger, configure contactupload as follows. contactupload -i <inputfile> -m <mapping_file> -e <templateid> For example: <CS_HOME>\bin\contactUpload.bat -i..\<subfolder>\fc_out.tsv -m..\<subfolder>\map_fc_out.xml -e When the flowchart run finishes, the system uploads the tab separated file that contains the flowchart output to Engage. If the mapping file specifies contact lists as the upload destination, only the rows that are specified in the various contact lists are modified. Note: If the mapping file references multiple contact lists, you must use the -g option to indicate which contact to use with the mailing that you specify with the -e option. When the upload is complete, Engage processes the new contact list and sends the mailing that you specified with the -e option, based on the information in the updated contact list. 52 IBM Campaign and IBM Silverpop Engage: Integration Guide

57 Chapter 5. Contact data download Engage provides contact data that identifies records for individuals who have opt-in or opted-out of messaging. Contact data also includes records for messages that could not be delivered successfully. The Campaign integration with Engage provides the contactdownload script that you can use to export contact data from Engage to Campaign. You can automate contact data download by adding the contactdownload script to a flowchart trigger. Script for downloading contact data Run the contactdownload script to download contact data as a tab-separated file that can be used as input to a campaign flowchart. To download contact data manually, run the contactdownload script from a command line on the Campaign Analytic server. To download contact data automatically, you can add the script to a flowchart process as a flowchart trigger. The configuration of the contactdownload script determines what data to download, how much data to download, and where to save the tab-separated download output file. You must specify the Engage database, contact list, or query that provides the contact data. Specifying the type, quantity, and location of the downloaded data is optional. The contactdownload script is in the bin directory of the <CS_HOME> directory. Usage contactdownload -l <listid> [-t <exporttype> -o <outputfile> -d <duration> -c <configpropertiesfile> -s <sppropertiesfile>] Option Description -l --listid ID of the Engage database or contact list that provided contact and personalization data for the mailing about which you are downloading contact data. Specify the ID as defined in the Engage interface. -t --exporttype Defines the type of contact data to export from Engage. Specify one of the following (not case-sensitive): ALL Export entire database or contact list (from the -l option). OPT_IN Contacts marked as opted in. OPT_OUT Contacts marked as opted out UNDELIVERABLE Contacts identified as undeliverable messages. Note: OPT_IN, OPT_OUT, and UNDELIVERABLE apply only to messaging. Copyright IBM Corp. 2014,

58 Option Description -o --outputfile Path, including file name, to the tab-separated file that contains the download. Directory structure must exist in advance of the download. If you do not provide a value for the -o option, the system saves the data in the directory that is specified in config.properties under local.download.dir. The system generates a file name as follows:export_<listid>_<type>_<date:yyyymmddhhmmss>.tab -d --duration The system exports from Engage only records that were modified after a specific time. You specify the time by indicating the number of hours previous to the time of the current run of the contactdownload script. -c --configpropertiesfile Path to the config.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location.[default: <CS_HOME>/conf/configuration.properties.] Paths with spaces must be enclosed in quotation marks. -s --sppropertiesfile Path to the sp.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location. [Default: <CS_HOME>/conf/sp.properties.] Paths with spaces must be enclosed in quotation marks. Related concepts: CS_HOME directory on page 16 SMS Opt-in and Opt-out synchronization between Campaign and Engage on page 72 Related tasks: Finding contact list, database, and relational table IDs in Engage on page 30 Finding mailing IDs in Engage on page 31 Downloading SMS data from Engage to Campaign on page 70 Downloading contact data Automatically downloading Campaign data to an Engage database involves a series of procedures. The process defines what to download, configures a flowchart to run the download, and makes the downloaded data available in the Campaign database. About this task Table 6. Contact data download tasks Automatically downloading contact data from Engage requires that you add a trigger to a flowchart. The trigger contains the contactdownload script. How you configure the trigger determines what you download from Engage and where to find the downloaded data. The following table outlines the automatic contact data download process. Task Configure the download. Define a trigger that contains the contactdownload script. More information Creating a flowchart trigger for contact data download on page IBM Campaign and IBM Silverpop Engage: Integration Guide

59 Table 6. Contact data download tasks (continued) Task Create a flowchart to download data. Add and edit a Schedule process. Select downloaded contact data. More information Configuring a Schedule process for contact data download on page 58 Selecting downloaded contact data on page 59 Use a Select process to make the selected data available to downstream processes. Results After you configure the Schedule and Select processes, you can save and run the flowchart. You can schedule the flowchart to download contact data on a recurring basis. You can also run the flowchart manually. For example, you might run the flowchart manually during the initial configuration to test the download performance. Running the flowchart triggers the following sequence. 1. The Schedule process runs contactdownload as a trigger. You can configure the script to specify a name and location for the download output file, or you can accept the default name and location, as set in config.properties. 2. The contactdownload script retrieves the available contact data from Engage and creates the download output file in the default location or in the location that you specify with the -o option. 3. The Select process, which you map through a base table to the download output file, selects the downloaded data from the file, and passes it to downstream flowchart processes. What to do next Determine which downstream process to connect to the Select. For example, connect to a Segment process to create a segment so that other Campaign users and processes can use the data. For more information about flowcharts, see the IBM Campaign User's Guide. Creating a flowchart trigger for contact data download In a Campaign flowchart, you can create a stored trigger that incorporates the contactdownload script. You can configure the script to trigger a contact data download from an Engage database, contact list, or query. The script creates a tab-separated file that you can map to a Campaign base record table for use by flowchart processes, such as a Select process. Before you begin You must have permissions in Campaign to create triggers. About this task When you configure automatic download of contact data from Engage, you specify a stored trigger that runs the contactdownload script. How you configure contactdownload in the trigger determines what you download from Engage. See Chapter 5. Contact data download 55

60 the download trigger examples for typical download scenarios. Procedure 1. Edit a Campaign flowchart. Open the Options icon and select Stored Triggers. The Stored Trigger Definitions window opens. 2. Click New Item. The data fields for the new trigger appear on the right of the window. 3. You can select a folder to save the trigger to in the Save Under list. The folder location governs which users can access the trigger, based on the folder's security policy. 4. Enter a name for the trigger in the Name field. v You cannot use spaces in the string, but you can use underscores ( _ ). v This name must be unique within the folder where you save it. 5. If you are creating a trigger in the top-level folder, select a security policy, or keep the default. 6. You can enter a description of the trigger in the Note field. You can provide a free-form text description of the trigger for documentation purposes. You also might want to keep a modification history of who modified the trigger, when, and what changes were made. 7. In the Command field, enter the contactdownload script. You must include the -l option to specify the database, contact list, or query that provides the contact data. You can specify a name and a location for the download file that the script generates. You can also specify options to control the type and amount of data that is downloaded. You might create several different triggers to perform different types of downloads. To illustrate the trigger configuration options, see the trigger examples. 8. Click Save and Close. Results When you configure a flowchart process that supports triggers, such as the Schedule process, the new trigger is available as a stored trigger. What to do next In a flowchart, configure a Schedule process with a trigger that is based on the contactdownload script. Finding query IDs in Engage To use the contactdownload script to download query data from Engage, you must specify the query ID. You must access Engage to determine the appropriate query ID. Procedure 1. On the Data tab in Engage, go to Queries and click View. The View Data page opens and displays a list of queries as links. 2. In the list of queries, hold the cursor over a query name. The query ID displays in a tooltip. 56 IBM Campaign and IBM Silverpop Engage: Integration Guide

61 Download trigger examples Preparation and procedures for downloading contact data depends on the configuration of the trigger that you add to the Schedule process in a flowchart. The trigger is based on the contactdownload script. How you configure the script depends on the type of data that you want to download and where you want to store the downloaded data. The following sections provide examples of how to configure the flowchart trigger in typical download scenarios. Example: Downloading all available contact data You can run the contactdownload script to download all of the available contact data in an Engage database, contact list, or query. The ID of the database, list, or query is a required input to contactdownload. If you run contactdownload and do not specify an export type, the script downloads all available data for the specified contact list. However, you can also explicitly download all of the contact data in a database or contact list by specifying ALL as the export type. In the trigger, configure contactdownload as follows. contactdownload -l <listid> contactdownload l <listid> -t ALL (optional) Example: <CS_HOME>\bin\contactDownload.bat -l Example: Defining a static output file name and custom location When you run the contactdownload script, you can use the -o option to specify where to save the tab-separated download file, instead of the default download directory. By default, the local download directory is <CS_HOME>/AppData. In the integration configuration, the local.download.dir property defines a location for the file, if you do not specify a location with the -o option. The system generates a name for the contact download file in the following format. The time stamp changes every time you download. Export_<listID>_<export_type>_<yyyymmddhhMMss>.TAB Example: Export_12345_OPT_OUT_ TAB If you configure a flowchart to download contact data automatically, you can use the -o option to define a static file name that you can specify in the Schedule process trigger. In the trigger, configure contactdownload as follows. contactdownload l <listid> -o <outputfile> Example: <CS_HOME>\bin\contactDownload.bat -l t OPT_IN -o..\ _add\export_optin.tab Chapter 5. Contact data download 57

62 In this example, records for individuals who want to be contacted by are included in the Export_OptIN file, which is saved in the _add folder. This folder is an example of a custom folder. It is not part of the default directory structure. Example: Downloading a specific type of contact data When you run the contactdownload script, you can specify the type of data to download. Only records that are marked as the type of data that you specify are added to the tab-separated download file. You specify the type of contact data to download with the -t option. This option takes the following values. v ALL v OPT_IN v OPT_OUT v UNDELIVERABLE Note: OPT_IN, OPT_OUT, and UNDELIVERABLE apply only to messaging. In the trigger, configure contactdownload as follows. contactdownload l <listid> -t <export_type> Example: <CS_HOME>\bin\contactDownload.bat -l t OPT_OUT Example: Downloading contact data received during a specific time When you run the contactdownload script, you can specify how much data to download by limiting results for a specific number of hours previous to running the script. Only records that are modified during the time that you specify are added to the tab-separated download file. You limit the time to include in the download with the -d option. You can use this option in conjunction with other options to narrow your results. In the trigger, configure contactdownload as follows. contactdownload l <listid> -d <duration> Example: <CS_HOME>\bin\contactDownload.bat -l t OPT_OUT -d 168 The script generates the tab-separated download file in the default download directory. In this example, the file contains only opt-out records that changed during the previous week (168 hours = 1 week). Configuring a Schedule process for contact data download In a Campaign flowchart, add a Schedule process that contains a flowchart trigger that runs the contactdownload script. The script downloads contact data from Engage and stores the downloaded data as a tab-delimited file that can be mapped to a Campaign table. About this task You configure a Schedule process for automatic data download from Engage only so that it can trigger the contactdownload script after the process runs. You do not 58 IBM Campaign and IBM Silverpop Engage: Integration Guide

63 schedule anything when you use the Schedule process in this way. Place the Schedule process at the beginning of the flowchart so that it is the first process to run. Procedure 1. Edit a Campaign flowchart. From the process palette, drag a Schedule process into the flowchart. 2. In the Schedule to Run field, select Once Only. 3. Select Send Trigger(s) After Each Run and select a trigger that is configured to download the type and quantity of data that you want, and that places the download file where you want it. You can select multiple triggers in a comma-separated list. The download triggers must be based on the contactdownload script. The configuration of the script determines the type, quantity, and location of the downloaded data. Note: Always place a question mark (?) after each trigger command so that, if the trigger fails, a red X displays on the Schedule process to inform you of the problem. 4. Click OK. What to do next In a flowchart, configure a Select process to select data from the tab-separated download output file. Selecting downloaded contact data The contactdownload script downloads contact data from Engage into a tab-delimited download output file. You can use a Select process to make the data in the download output file available in Campaign. Before you begin Locate the download output file that you want to use as input to the Select process. If you configured the contactdownload script with the -o option, go to the specified location. Otherwise, go to the default local download directory as specified in the local.download.dir property in config.properties, which is in the conf folder. About this task You must use the download output file as a data source for the Select process. Map the tab-delimited download output file to a base record table and then select the table as an input to the Select process. Procedure 1. Edit the flowchart where you added the Schedule process and contact download trigger. From the process palette, drag a Select process into the flowchart. 2. Map the download output file to a base record table. You must specify the following characteristics. Note: To help ensure that Campaign allocates field widths in the base record table correctly, run the contactdownload trigger with the option -tall to Chapter 5. Contact data download 59

64 populate the table before you map it. Make certain that least one row of the downloaded data has typical data in each column. v You are mapping to an existing file. v Select Delimited File. v The field delimiter is TAB. v Indicate that the first row of data contains field names. For more information about mapping a base record table to an existing delimited file, see the IBM Campaign Administrator's Guide. 3. Select the base record table as an input to the Select process. 4. Connect the Select process to the Schedule process. What to do next Connect the Select process to downstream flowchart processes. Precautions for mapping the download output file to tables When you map a delimited file to a base record table, Campaign configures column widths automatically. Errors can result if the table widths are not appropriate for the data that is downloaded. Campaign detects field width automatically, based on the contents of the field. By default, Campaign examines the first and last 50 lines of a delimited file. It allocates field width based on the largest value it finds within those lines. However, in large delimited files, a subsequent field might exceed the estimated length, which can cause an error. To avoid possible column width problems, run the contactdownload script to populate the download output file. At least one row of the download file must contain data in every field so that Campaign can properly set column widths. For example, to download the list of individuals in an Engage database (37510 in this example), run the contactdownload script as follows. <CS_HOME>\bin\contactDownload.bat -l t ALL After you populate the download output file, Campaign can allocate column widths more accurately, based on typical values. You can run the script later to download a more restricted set of records. 60 IBM Campaign and IBM Silverpop Engage: Integration Guide

65 Chapter 6. Tracking data download Engage records various pieces of information related to the transmission, delivery, and response to the messages that you send through Engage. The Campaign integration with Engage provides the trackingdownload script to download the tracking data that Engage collects. You can also configure the integration to track data that Engage does not track by default. Run the trackingdownload script to download contact data from all of the Engage databases that you have created or from a single Engage database. The trackingdownload script downloads all tracking data that Engage received since the previous download. The trackingdownload script stores the downloaded tracking data in the Campaign system tables. The Campaign integration with Engage provides DDL scripts to create additional tables in the same schema as the Campaign system tables to accept the tracking data that Engage provides. The system tracks any errors that it encounters when it adds tracking data to the Campaign system tables. To determine corrective action, you can review an error file and a generated file that lists rows that were not inserted into the database. You can also configure the system to automatically send reports by to notify you when errors begin to accumulate. Script for downloading tracking data Use trackingdownload to move tracking data from IBM Silverpop Engage to tracking tables in the IBM Campaign schema. Tracking data downloads include all tracking data received since the previous download. You can specify a single Engage database to view tracking data for only that database. If you do not specify a database, trackingdownload downloads all tracking data from all databases. By default, the trackingdownload script is located in the bin directory of the <CS_HOME> directory. The <CS_HOME> directory is the folder on the Campaign Analytics server where the integration files are installed. It can be any folder that you choose or create. You can run the trackingdownload script from a command line on the Campaign Analytics server. You can also configure a cron job or Windows scheduler task to run the script. You must have access to the Campaign Analytics server and user permissions that allow you to run scripts. Usage trackingdownload [-l <listid> -c <configpropertiesfile> -s <sppropertiesfile> -j <jdbcpropertiesfile>] Option Description -l --listid ID of the Engage database or contact list that provided contact and personalization data used in the mailing that you are tracking. Specify the ID as defined in the Engage interface. Copyright IBM Corp. 2014,

66 Option Description -c --configpropertiesfile Path to the config.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location.[default: <CS_HOME>/conf/configuration.properties.] Paths with spaces must be enclosed in quotation marks. -s --sppropertiesfile Path to the sp.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location. [Default: <CS_HOME>/conf/sp.properties.] Paths with spaces must be enclosed in quotation marks. -j --jdbcpropertiesfile Path to the jdbc.properties file. Absolute or relative path to <CS_HOME>. Specify a path when this file is renamed or is not in the default location. [Default: <CS_HOME>/conf/jdbc.properties. Paths with spaces must be enclosed in quotation marks. Related concepts: CS_HOME directory on page 16 Related tasks: Encrypting the integration configurations on page 23 Finding contact list, database, and relational table IDs in Engage on page 30 Finding mailing IDs in Engage on page 31 Tracking data provided by Engage Engage tracks specific details about the messages that you compose and send through Engage. The Campaign integration with Engage makes that information available in the Campaign system tables so that you can use the data in Campaign flowcharts. During the initial setup and configuration of the integration, you run custom DDL scripts to add tables to the Campaign system tables. The trackingdownload script automatically downloads and inserts Engage tracking data into the tracking tables. By default, Engage tracks and can export the following types of message-related actions. v Messages sent v Messages opened v Messages that were forwarded v Clickthroughs v Attachments that were viewed or downloaded v Message bounces v Recipients for whom messages were suppressed v Record of Engage conversion events v Opt-in v Opt-out 62 IBM Campaign and IBM Silverpop Engage: Integration Guide

67 Adding additional tracking information You can configure the Campaign integration with Engage to download additional tracking information to Campaign. To receive the extra tracking data, you must modify the tracking tables that are created in the Campaign schema and update the integration configuration. About this task For example, to identify the audience level from Campaign, you might define an additional tracking field called customerid. To use customerid as an additional tracking field, you must add a customerid field to the integration tracking fields. You must also modify the integration configuration properties to specify the customerid as a field to be exported for additional tracking. Procedure v Ensure that the Engage database includes the tracking information that you want to add. v Modify the integration tracking tables in the Campaign schema. Use your database client to add the column that you want to add to all of the integration tracking tables (except sp.uploadaudit). The field name must be identical in the Campaign schema, Engage database, and in the integration configuration. v Modify config.properties to identify the additional field as a field that can serve a tracking field. 1. Go to <cs_home>/bin/config.properties. Open the file in a text editor. 2. Search for # export.additional.tracking.fields=. Remove the comment character # to enable the configuration. 3. Enter the column name of the additional field as the value for export.additional.tracking.fields. To add multiple fields, enter the column names as a comma-separated list. 4. Save your changes. Results Engage includes the additional field as one of the -related elements that it tracks, and the additional data is downloaded and inserted into the integration tables. When you include the field in a data upload, Engage can return a value for the additional field as tracking data. If you do not include the additional tracking field in the upload, the field appears in the tracking data but the value in the extra column is null. Database management concerns and precautions Adding additional tracking fields to your database can have unintended effects. Consult with your database administrator to prevent problems. Be careful about how many fields that you add and how you configure each field. Consider the following issues. v Avoid adding fields where you expect to create one row for every message that you send. The wider that you make the table, the more space each row requires. v Do not add constraints to the fields that you add. v Do not add unique indexes on the fields that you add. Chapter 6. Tracking data download 63

68 v Reconsider how often you archive data or schedule data clean up. The added fields can increase the overall size of the database. The effect of the additional fields on your database depends on your business practices and messaging volumes. v Determine how often to run the trackingdownload script. Consider how often you send messages and the amount of tracking data that they might generate. Manually downloading tracking data You can run the trackingdownload script from a command line on the Campaign Analytics server. Run the script manually to verify that the configurations for the integration are properly set and to verify the connection to Engage. About this task When you run the trackingdownload script, the system indicates in the command console that the run was successful. Look in the console for any reported errors. Note: Running trackingdownload to verify system configurations and the connection to Engage is recommended before you encrypt the integration configurations. Procedure Run the trackingdownload script, as follows. <CS_HOME>\bin\trackingDownload.bat or <CS_HOME>/bin/trackingDownload.sh Results Script run results are reported explicitly when the run completes by printing a count of errors, warnings, and an overall status. Data that is received from Engage is added to the various integration tracking tables in the Campaign schema. Related concepts: CS_HOME directory on page 16 Related tasks: Encrypting the integration configurations on page 23 Automatically downloading tracking data You can automatically download tracking data from Engage by running the trackingdownload script as a cron job or Windows scheduler task. Before you begin Before you run the trackingdownload script, ensure that the required tracking tables have been created in the Campaign schema. To create the tables, run the custom DDL scripts that are provided with the integration download package. 64 IBM Campaign and IBM Silverpop Engage: Integration Guide

69 About this task Each time the trackingdownload script runs, it downloads various types of tracking data and inserts into the appropriate tracking tables. Each download includes all of the tracking data that was received since the previous run of the script. Depending on how you have configured the script, the download includes data from all available databases, or a single database that you specify in the script. Procedure Run the trackingdownload script as a cron job or Windows scheduler task. In Windows, ensure that your action uses cmd /c:. Use double quotation marks around the entire command. For example: "cmd /c C:\IBM\EMM\Campaign\partitions\partition1\campSP\bin\ trackingdownload.bat" Example: Download tracking data from a specific Engage database To download tracking data from a specific Engage database, specify the database ID with the -l option. Specify the database that provided contact and personalization data that is used in the mailing that you are tracking. trackingdownload -l <listid> Example: <CS_HOME>\bin\trackingDownload -l In this example, the script downloads all available tracking data from the Engage database that is identified with ID Example: Downloading tracking data from all Engage databases To download tracking data from all available Engage databases, do not specify a specific database ID with the -l option. Run the trackingdownload script, as follows. <CS_HOME>\bin\trackingDownload Error reporting for tracking data In some cases, tracking data cannot be inserted into the tracking tables in Campaign. The trackingdownload script stores the rows that cannot be downloaded in a file. Rows that cannot be written to the tracking tables are stored in <CS_HOME>/AppData/trackingDataError. Depending on how many errors you encounter, the file can become large. The system sends an error report by when the amount of error data exceeds a configured threshold. You can also save files that were downloaded and successfully inserted into the database. However, saving all of the successful downloads might require careful management of your disk space, due to the potentially large number of records. Chapter 6. Tracking data download 65

70 The Campaign integration with Engage provides several configurations to manage tracking data error handling and reporting. The configurations are in the config.properties file, which is in the bin directory of the integration files. You can use the following configuration settings to manage error reporting for your installation. Error files are saved in a compressed format. Configuration property dbinsert.errors.report.alert.records.num dbinsert.errors.report.alert.error.files.size dbinsert.errors.report.smtp.host dbinsert.errors.report.to dbinsert.errors.report.from dbinsert.errors.report.body dbinsert.errors.report.subject dbinsert.keep.processed.files dbinsert.errors.report.class local.download.dir Description Threshold for sending error alerts. Specify the cumulative size of the accumulated error alerts that triggers a report. Specify the server that sends SMTP alerts. Specify address to receive alerts. Specify a From: address for alert messages. Content of alert messages. Subject line for alert messages Indicate if the system stores all processed files locally Specifies a class to be called when the download script completes. Local directory that receives downloaded tracking data. 66 IBM Campaign and IBM Silverpop Engage: Integration Guide

71 Chapter 7. SMS messaging with Campaign and Engage The IBM Campaign integration with IBM Silverpop Engage provides the ability to segment and upload contact information from Campaign for use in SMS messaging campaigns that you run in Engage. You can use Engage queries to extract a range of information from SMS responses and download the query results to Campaign for further processing. You can send SMS messages through Engage in any of the following ways. v Immediately v Schedule at a future date v Automate and Send as recurring The Campaign integration with Engage does not support automatically triggering an SMS campaign by uploading contact data. Requirements for SMS messaging To contact your customers with SMS messages through Engage, you must satisfy certain requirements and become aware of restrictions that are related to SMS messaging. For more information about SMS messaging through Engage go to Purchase requirement for SMS messaging To send SMS messages through Engage, you must purchase SMS support separately. When you purchase support for SMS messaging, IBM Silverpop provisions your account for SMS messaging. Contact your IBM representative to learn more about how to purchase SMS support and begin the provisioning process. Consent requirements for SMS messaging SMS is an international communication medium. It is subject to various international laws and conventions. You must familiarize yourself with the applicable laws that pertain to contact by SMS in the markets that you want to reach. For example, you cannot contact individuals in the United States without obtaining permission in advance for contact by SMS messages. It is a violation of MMA Compliance to send SMS messages without proper consent from the recipient. Although you can upload SMS contact information from your customer tables through Campaign, you cannot send SMS messages unless you also provide SMS consent data. The Campaign integration with Engage provides a custom XML mapping file for use when you upload SMS contact information to Engage. The mapping file contains tags that you can use to provide the required consent data. Copyright IBM Corp. 2014,

72 SMS number format When you specify a phone number for SMS messaging, you must provide the number in the correct format. Because SMS messages can be directed anywhere in the world, you must provide the phone number in international format. Review the SMS contact information in your customer database to ensure that SMS phone number information for each recipient. The phone number, including numbers for recipients in the United States, must include the international country code. To send SMS messages through Engage, the SMS number cannot include non-numeric characters. The elements of the number cannot be delimited by dashes, periods, or slashes. SMS database requirement In Engage, your organization can create only one database for SMS messaging. When you run the contactupload and contactdownload scripts for SMS data, you must specify the dedicated SMS directory. The database for SMS must be a non-keyed Engage database. Use the custom mapping fileexample_smsmappingfile.xml when you upload to the SMS database. Text to Join To send SMS messages through Engage, you must configure a Text to Join program in Engage. Data required for SMS consent SMS messaging requires recipient consent. To provide the required consent information, you must add several specific fields to the data upload. You can define these fields with the custom mapping file that the integration provides for SMS messaging. A record in an Engage SMS database has one of the following statuses. v no consent v opted-in v opted-out If you upload contact data without also uploading the required consent, the record is marked no consent. If the opt-in consent exists in the Campaign database, you can use the custom mapping file to upload the information to Engage. In the mapping file, you must define a consent field that provides the CONSENT_STATUS_CODE. The only allowed values for CONSENT_CODE are OPTED-IN or OPTED-OUT. The values must be in uppercase and written in the exact phrase. Engage can send SMS messages only to recipients whose record is marked OPTED-IN. Optionally, if your database records the date and method of consent, you can define fields for the following fields. v CONSENT_DATE: Date on which consent was updated. The default value is the date of the upload. 68 IBM Campaign and IBM Silverpop Engage: Integration Guide

73 v CONSENT_SOURCE: Text description of where the consent was obtained. The default value is List Import. Related concepts: What to upload from Campaign on page 27 Example: Upload data as specified in a mapping file on page 51 Related reference: Chapter 8, Reference: Mapping files, on page 73 Uploading SMS contact data from Campaign to Engage Automatically uploading SMS data to an Engage database involves a series of separate procedures. These procedures involve a flowchart that contains a Mail List process and a flowchart trigger. Running the flowchart creates a tab-separated list of field values that is uploaded to Engage without human intervention. Before you begin Configure the SMS mapping file to provide the SMS consent data that Engage requires to send SMS messages. The example_smsmappingfile.xml is in the conf directory. The file contains extensive comments that provide instructions for how to provide information that Engage requires for SMS messaging. To use the file, make a copy of the file and rename it. For example, you might remove the prefix, example_, and save the file in the same directory. About this task To upload contact data for use in SMS messaging campaigns, add the contactupload script to a flowchart trigger. How you configure the trigger depends on what you want to upload to Engage. You must specify a custom mapping file to upload information for SMS. The integration provides an example mapping file for this purpose. When you run the contactupload script to provide SMS data, specify the -m option to reference the SMS mapping file. Note: You cannot trigger Engage to run an SMS campaign immediately after you upload SMS contact information. Therefore, you cannot specify the -e or g options for the contactupload script when you upload SMS data. Using a Campaign flowchart and a stored trigger to automatically upload data from Campaign to Engage involves the general steps that are listed in the following table. These steps are substantially similar to procedures that are used to upload contact data for messaging. Chapter 7. SMS messaging with Campaign and Engage 69

74 Table 7. Automatic upload configuration tasks Task In Campaign, create or edit a flowchart. Modify the flowchart as needed to select the information that you want to upload to Engage. Match Campaign field names to Engage field names. Create a flowchart trigger with the contactupload script. You must use the -m option to specify a custom mapping file. More information See the IBM Campaign User's Guide for information about creating and configuring flowcharts. Flowchart design for data upload to Engage on page 44 Creating a flowchart trigger for automatic data upload on page 45 The trigger must reference the tab-separated file that is generated by the Mail List process. Add a Mail List process to the flowchart. Connect upstream processes as inputs to the Mail List process. Configure the Mail List process. Add a trigger to define what to upload. Save and run the flowchart. When the run finishes, the upload script triggers an upload of the flowchart output to the specified destination in Engage. Configuring a Mail List process for automatic data upload to Engage on page 46 Where to put uploaded data in Engage on page 29 Related concepts: Where to put uploaded data in Engage on page 29 Related tasks: Automatically uploading data from Campaign to Engage on page 43 Downloading SMS data from Engage to Campaign To download SMS data from Engage, use the contactdownload script. You can download SMS data that you select with a queries that you design and run in Engage. Before you begin In Engage, create and run a query to extract the information that you want to download. For example, use a query to identify recipients who have opted-out of SMS messaging, or a list of SMS recipients that responded to a program. About this task To obtain SMS tracking results, you must design and run queries in Engage. For more information about how to structure and run a query for SMS data, see Each query has a unique ID. You can reference the query ID in the contactdownload script to download the query results. You must access Engage to determine the query ID. In the list of queries, hold the cursor over the query name. The query ID displays as a tooltip. You must explicitly specify an export type. For SMS data, you must configure the -t option as ALL. 70 IBM Campaign and IBM Silverpop Engage: Integration Guide

75 Table 8. Contact data download tasks Note: OPT_IN, OPT_OUT, and UNDELIVERABLE apply only to messaging. The trackingdownload script does not retrieve tracking data for SMS messaging. Task Configure the download. Define a trigger that contains the contactdownload script. Create a flowchart to download data. Add and edit a Schedule process. Select downloaded contact data. More information Creating a flowchart trigger for contact data download on page 55 Configuring a Schedule process for contact data download on page 58 Selecting downloaded contact data on page 59 Use a Select process to make the selected data available to downstream processes. Results After you configure the Schedule and Select processes, you can save and run the flowchart. To download contact data on a recurring basis, you can run the flowchart according to a schedule. You can also run the flowchart manually. For example, you might run the flowchart manually during the initial configuration to test the download performance. Running the flowchart triggers the following sequence. 1. The Schedule process runs contactdownload as a trigger. You can configure the script to specify a name and location for the download output file, or you can accept the default name and location, as set in config.properties. 2. The contactdownload script retrieves the available contact data from Engage and creates the download output file in the default location or in the location that you specify with the -o option. 3. The Select process, which you map through a base table to the download output file, selects the downloaded data from the file, and passes it to downstream flowchart processes. What to do next Determine which downstream process to connect to the Select. For example, connect to a Segment process to create a segment so that other Campaign users and processes can use the data. For more information about flowcharts, see the IBM Campaign User's Guide. Related reference: Script for downloading contact data on page 53 Chapter 7. SMS messaging with Campaign and Engage 71

76 SMS Opt-in and Opt-out synchronization between Campaign and Engage To ensure that consent records for SMS are as up to date as possible, you can update opt-in and opt-out requests for SMS that you receive through various channels. To synchronize SMS subscription data between Campaign and Engage, upload and download opt-in and opt-out updates regularly. Managing opt-in and opt-out records for SMS requires specific steps. The OPT_IN and OPT_OUT options for the contactupload and contactdownload scripts do not apply to SMS messaging. Instead, you must use the custom SMS mapping file that is provided as part of the Campaign integration with Engage download package. The first time that you add contact information for a recipient, the record is marked as an Opt-in record. If the individual did not consent to be contacted by SMS, you must subsequently mark the record as an Opt-out. You cannot add a record as an Opt-out record. You can identify a record as an Opt-out only after you enter it as an Opt-in. To keep SMS subscriptions up to date, you can schedule Campaign flowcharts that trigger the contactupload and contactdownload scripts to run automatically. Use the instructions in the example_smsmappingfile in the conf directory to update SMS consent status. In Engage, schedule queries that update opt-in and opt-out status so that the most current information is available for download to Campaign. Related reference: Chapter 8, Reference: Mapping files, on page 73 contactupload on page 39 Script for downloading contact data on page IBM Campaign and IBM Silverpop Engage: Integration Guide

77 Chapter 8. Reference: Mapping files The IBM Campaign integration with IBM Silverpop Engage provides sample mapping files that you can use as a models for custom mapping files in yourenvironment. example_mappingfile The example_mappingfile is in the../<cs_home>/conf directory. <!-- Licensed Materials - Property of IBM IBM Campaign Materials Configuration file for IBM Campaign integration with Silverpop Engage (c) Copyright IBM Corporation US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. --> <!-- This is an example mapping file. A mapping file is a parameter to contactupload and tableupload. You can assign any name to this file and save it in any location. The parameters given to contactupload and tableupload specify the location and name of the file. --> <LIST_IMPORT> <LIST_INFO> <!-- The LIST_INFO section is required. --> <ACTION>ADD_AND_UPDATE</ACTION> <!-- Actions ADD_AND_UPDATE and REPLACE are supported import actions. Use ADD_AND_UPDATE with contactupload or tableupload to add new data to a database, contact list, or relational table or to update existing data. Use REPLACE with tableupload only. Enter REPLACE to remove all data from a relational table and replace it with new data. --> <LIST_VISIBILITY>1</LIST_VISIBILITY> <!-- Do not change this value. --> <!-- LIST_VISIBLIITY must be set to 1, which allows the data to be added to shared databases and relational tables. --> <FILE_TYPE>1</FILE_TYPE> <!-- Do not change this value --> <!-- FILE_TYPE must be set to 1 to allow upload of.tsv files. --> <LIST_ID>Update this value</list_id> <!-- You must update this value. --> <!-- Set LIST_ID to match the id of the database, contact list, or relational table that you are uploading to.--> <LIST_DATE_FORMAT>MM/dd/yyyy</LIST_DATE_FORMAT> <!-- The date format must match the date format that is used in the data that you are uploading. --> <HASHHEADERS>true</HASHHEADERS> <!-- Do not change this value. --> <!-- HASHHEADERS must be set to true, which treats the first row to provide the column names. --> Copyright IBM Corp. 2014,

78 </LIST_INFO> <CONTACT_LISTS> <!-- The CONTACT_LISTS section is optional. Enter values in this section to upload data to one or more contact lists. --> <!-- Enter the contact list ID (5 digit value)for each contact list that receives data as part of the upload. --> <CONTACT_LIST_ID>update this value</contact_list_id> <CONTACT_LIST_ID>update this value</contact_list_id> <!-- Add more contact list IDs as required. --> </CONTACT_LISTS> <MAPPING> <!-- The MAPPING section is required. Provide one <COLUMN> section for each column in the.tsv file. --> <!-- Within each <COLUMN>, define INDEX, NAME, and INCLUDE. <!-- Define <INDEX> as a value that corresponds to the order of columns in the.tsv file. For example, the first column in the.tsv file matches the first column in the mapping file. Assign 1 as the <INDEX> value. For the second column, assign 2 as the <INDEX> value. Continue for the remaining columns in the.tsv file. --> <!-- Define <NAME> to match the column name of the database in Engage. --> <!-- Define <INCLUDE> as either True or False. True: The column is uploaded to Silverpop. False: The column is not included in the upload to Silverpop --> <!-- Example columns below. Edit to match your data. REQUIRED: The column that provides recipient addresses must be named " ". --> <COLUMN> <INDEX>1</INDEX> <NAME>CustID</NAME> <INCLUDE>true</INCLUDE> </COLUMN> <COLUMN> <INDEX>2</INDEX> <NAME>LastName</NAME> <INCLUDE>true</INCLUDE> </COLUMN> <COLUMN> <INDEX>3</INDEX> <NAME>FirstName</NAME> <INCLUDE>true</INCLUDE> </COLUMN> <COLUMN> <INDEX>4</INDEX> <NAME> </NAME> <INCLUDE>true</INCLUDE> </COLUMN> <COLUMN> <INDEX>5</INDEX> <NAME>NumericField</NAME> <INCLUDE>true</INCLUDE> </COLUMN> 74 IBM Campaign and IBM Silverpop Engage: Integration Guide

79 <COLUMN> <INDEX>6</INDEX> <NAME>DateField</NAME> <INCLUDE>true</INCLUDE> </COLUMN> </MAPPING> </LIST_IMPORT> example_smsmappingfile You must configure a mapping file for SMS messaging. The example_smsmapping file contains tags that are specific to SMS messaging. The file is in is in the../<cs_home>/conf directory. <!-- Licensed Materials - Property of IBM IBM Campaign Materials Configuration file for IBM Campaign integration with Silverpop Engage (c) Copyright IBM Corporation US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. --> <!-- This is an example mapping file for use with SMS messaging. A mapping file is a parameter to the contactupload script. You can assign any name to this file and save it in any location. The parameters that you give to contactupload specify the location and name of the file. --> <LIST_IMPORT> <LIST_INFO> <!-- LIST_INFO section is required --> <ACTION>ADD_AND_UPDATE</ACTION> <!-- Actions ADD_AND_UPDATE and OPT_OUT are supported import actions. Use ADD_AND_UPDATE with contactupload to add new SMS-related data, or update existing data, in an Engage database and one or more Engage contact lists. Use OPT_OUT with contactupload to update existing contacts who have opted out and should not receive SMS messages. The.tsv file that is uploaded must specify the value of the CONSENT_STATUS_TYPE as "OPTED_OUT". --> <LIST_VISIBILITY>1</LIST_VISIBILITY> <!-- Do not change this value --> <!-- LIST_VISIBLIITY must be set to 1 so that the data can be added to shared databases --> <FILE_TYPE>1</FILE_TYPE> <!-- Do not change this value --> <!-- FILE_TYPE must be set to 1 to allow upload of.tsv files --> <LIST_ID>Update this value</list_id> <!-- You must update this value. --> <!-- Set LIST_ID to match the id of the database that you are uploading to. --> <LIST_DATE_FORMAT>MM/DD/yyyy</LIST_DATE_FORMAT> <!-- The date format must match the date format that is used in the data that you are uploading. --> Chapter 8. Reference: Mapping files 75

80 <HASHEADERS>true</HASHEADERS> <!-- Do not change this value. --> <!-- HASHHEADERS must be set to true, which treats the first row to provide the column names. --> </LIST_INFO> <CONTACT_LISTS> <!-- The CONTACT_LISTS section is optional. Enter values in this section to upload data to one or more contact lists. --> <!-- Enter the contact list ID (5 digit value)for each contact list that receives data as part of the upload. --> <CONTACT_LIST_ID>Update this value</contact_list_id> <CONTACT_LIST_ID>Update this value</contact_list_id> <!-- Add more contact list IDs as required. --> </CONTACT_LISTS> <CONSENT> <!-- CONSENT section is required --> <CHANNEL>SMS</CHANNEL> <!-- CHANNEL section is required. --> <!-- Do not change this value. --> <TEXT_TO_JOIN_PROGRAM_ID>Update this value</text_to_join_program_id> <!-- You must update this value. --> <!-- Enter the Text to Join ID (6 digits) for the SMS program.--> <OVERRIDE_ON_NO_CHANGE>true OR false</override_on_no_change> <!-- Define whether or not to update consent information for matched records when you upload new consent data. This setting applies when the import action is ADD_AND_UPDATE. --> True: Replace existing consent data during data upload. Update Consent Date, Consent Source, and Consent Status. False: Do not change consent data for existing matched records. </CONSENT> <SYNC_FIELDS> <!-- SYNC_FIELDS section is required --> <SYNC_FIELD> <NAME>Update this value</name> <!-- You must update this value. --> <!-- Specify the field in the.tsv file that provides the SMS phone number. In Engage, this field has the Field Type: SMS Phone Number --> </SYNC_FIELD> </SYNC_FIELDS> <MAPPING> <!-- The MAPPING section is required. Provide one <COLUMN> section for each column in the.tsv file. --> <!-- Within each <COLUMN>, define INDEX, NAME, and INCLUDE. --> <!-- SMS messaging requires recipient consent. To designate fields that provide consent data, define <IS_CONSENT>. You must define a consent field that provides the CONSENT_STATUS_CODE. Optionally, if your 76 IBM Campaign and IBM Silverpop Engage: Integration Guide

81 database records the date and method of consent, you can define fields for CONSENT_DATE and CONSENT_SOURCE. --> <!-- Define <INDEX> as a value that corresponds to the order of columns in the.tsv file. For example, the first column in the.tsv file matches the first column in the mapping file. Assign 1 as the <INDEX> value. For the second column, assign 2 as the <INDEX> value. Continue for the remaining columns in the.tsv file. --> <!-- Define <NAME> to match the column name of the database in Engage. --> <!-- Define <INCLUDE> as either True or False. True: The column is uploaded to Engage. False: The column is not included in the upload to Engage --> <!-- Define <IS_CONSENT> as either True or False. Required for the field that provides CONSENT_STATUS_CODE. True: The field is related to recipient opt in. False: The column is not related to recipient opt in. --> <!-- Example columns below. Edit to match your data. REQUIRED: Although this mapping file is used with SMS text messages, you must define a column in the.tsv file that maps to the column in the Engage database for addresses. The column must be named " ". --> <COLUMN> <INDEX>1</INDEX> <IS_CONSENT>true</IS_CONSENT> <!--Required --> <NAME>CONSENT_STATUS_CODE</NAME> <INCLUDE>true</INCLUDE> </COLUMN> <COLUMN> <INDEX>2</INDEX> <IS_CONSENT>true</IS_CONSENT> <!--Optional --> <NAME>CONSENT_SOURCE</NAME> <INCLUDE>true</INCLUDE> </COLUMN> <COLUMN> <INDEX>3</INDEX> <IS_CONSENT>true</IS_CONSENT> <!--Optional --> <NAME>CONSENT_DATE</NAME> <INCLUDE>true</INCLUDE> </COLUMN> <COLUMN> <INDEX>4</INDEX> <!--Required --> <NAME> </NAME> <INCLUDE>true</INCLUDE> </COLUMN> <COLUMN> <INDEX>5</INDEX> <NAME>Enter a Name</NAME> <INCLUDE>true or false</include> </COLUMN> <COLUMN> <INDEX>6</INDEX> <NAME>Enter a name</name> <INCLUDE>true or false</include> </COLUMN> <COLUMN> Chapter 8. Reference: Mapping files 77

82 <INDEX>7</INDEX> <NAME>Enter a name</name> <INCLUDE>true or false</include> </COLUMN> <!-- Define additional columns as needed. --> </MAPPING> </LIST_IMPORT> Related concepts: Example: Upload data as specified in a mapping file on page 51 Data required for SMS consent on page 68 SMS Opt-in and Opt-out synchronization between Campaign and Engage on page 72 Related tasks: Creating a custom mapping file for upload to a non-keyed database on page IBM Campaign and IBM Silverpop Engage: Integration Guide

83 Chapter 9. Custom tracking tables The Campaign and Engage integration package includes several DDL scripts that you can use to create database tables to receive contact and tracking data that you download from Engage. You create the tables in the Campaign schema. The Campaign and Engage integration recognizes several different types of message responses. In the tracking tables, the responses are represented as different types of contact events. Each table contains information to describe different aspects of the message contact and tracking data that Engage provides. The type of contact event determines the type of data that a tracking table contains. Table Description More detail SP_Attachment SP_BounceReply SP_Click SP_Conversion SP_Forward Records when an attachment is downloaded or viewed. Records of unsuccessful message delivery. Records for link clicks in messages. Records of Engage conversion events. Records of messages that were forwarded. SP_Attachment on page 81 SP_BounceReply on page 82 SP_Click on page 82 SP_Conversion on page 83 SP_Forward on page 84 SP_Open Records of message opens. SP_Open on page 85 SP_OptIn SP_OptOut Records that are marked as opted-in. Records that are marked as opted-out. SP_OptIn on page 86 SP_Sent Records of messages sent. SP_OptOut on page 87 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 Event types The tracking tables provide data to describe different types of message responses. The type of response is considered an event type. The tracking tables include values for the following event types. Event type Valid value Open 0 Click Through 1 Clickstream 2 Conversion 3 Attachment 4 Copyright IBM Corp. 2014,

84 Event type Valid value Media 5 Forward 6 Opt In 7 Opt Out 8 Reply Abuse 10 Reply Change Address 11 Reply Mail Block 12 Reply Mail Restriction 13 Reply Other 14 Suppressed 15 Sent 16 Soft Bounce 98 Hard Bounce 99 Report IDs If you have configured reporting in Engage, the downloaded data includes a Report ID. If you have not configured reporting for Engage mailings, Report IDs do not appear in the tracking tables. Report IDs are assigned in various ways, depending on the type of mailing. v For event-driven Autoresponders, a single Report ID is associated with every mailing for a day. v For a recurring Automated Message, a single Report ID is associated with each occurrence of the mailing. v For a standard mailing, there is a one-to-one relationship between a Report ID and Mailing ID. Reasons for contact suppression Engage sometimes does not send a message to an address for various reasons. If Engage suppresses a message, the reason for doing so is included in the data that you downloaded from Engage. Engage provides the following reasons for contact suppression. Suppression reason Invalid System Domain 1 Invalid System Local 2 Invalid Organization Domain 3 Organization Suppression List 4 Global Suppression 5 Invalid Organization Local 6 Frequency Control 7 Database Level Suppression 8 Valid values 80 IBM Campaign and IBM Silverpop Engage: Integration Guide

85 Suppression reason Valid values Query Level Suppression 9 Mailing Level Suppression 10 SP_Attachment The SP_Attachment table contains data that Engage collects when a contact downloads an attachment or views an attached video. Column Description Valid values Data type RecordID RecipientID A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the contact that is associated with the event. RecipientType The type of message contact. 0 Regular bigint bigint nvarchar Primary Key Yes MailingID ReportID The ID of the Sent Mailing that is associated with the event. If reporting is configured in Engage, the ID of the report that is associated with the mailing. If reporting is not configured, this field is empty. 1 Forward 3 Seed 4 Inbox Monitoring bigint bigint CampaignID See Report IDs on page 80 The ID of the Group of Automated Messages that is associated with the contact event. bigint The address of the contact. address nvarchar EventType The type of contact event. nvarchar EventTimeStamp ContentID MailingName Event types on page 79 The date and time when Engage recorded the contact event. The identifier that the user specified for the attachment. The name of the mailing, as it is defined in Engage. Includes an additional identifier as a prefix, if defined during data upload. datetime nvarchar nvarchar Chapter 9. Custom tracking tables 81

86 SP_BounceReply The SP_BounceReply table contains data that Engage collects to record when messages are not delivered successfully. Column Description Valid values Data type RecordID RecipientID A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the contact that is associated with the event. RecipientType The type of message contact. 0 Regular bigint bigint nvarchar Primary Key Yes MailingID ReportID The ID of the Sent Mailing that is associated with the event. If reporting is configured in Engage, the ID of the report that is associated with the mailing. If reporting is not configured, this field is empty. 1 Forward 3 Seed 4 Inbox Monitoring bigint bigint CampaignID See Report IDs on page 80 The ID of the Group of Automated Messages that is associated with the contact event. The address of the contact. address nvarchar EventType The type of contact event. nvarchar EventTimeStamp MailingName Event types on page 79 The date and time when Engage recorded the contact event. The name of the mailing, as it is defined in Engage. Includes an additional identifier as a prefix, if defined during data upload. datetime nvarchar SP_Click The SP_Click table contains data that Engage collects to record when message recipients click links in the messages that they receive. Column Description Valid values Data type RecordID RecipientID A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the contact that is associated with the event. bigint bigint Primary Key Yes 82 IBM Campaign and IBM Silverpop Engage: Integration Guide

87 Column Description Valid values Data type RecipientType The type of message contact. 0 Regular nvarchar Primary Key 1 Forward 3 Seed 4 Inbox Monitoring MailingID The ID of the Sent Mailing that is associated with the event. bigint ReportID If reporting is configured in Engage, the ID of the report that is associated with the mailing. If reporting is not configured, this field is empty. bigint CampaignID See Report IDs on page 80 The ID of the Group of Automated Messages that is associated with the contact event. The address of the contact. address nvarchar EventType The type of contact event. nvarchar Event types on page 79 EventTimeStamp The date and time when Engage recorded the contact event. datetime Body Type The format of the message body that the contact received. 0 HTML 1 AOL nvarchar 2 TEXT 3 WEB (click-to-view) Click Name The name that the user specified for the link or Clickstream. nvarchar URL The URL that is defined for a Clickthrough or Clickstream. URL MailingName The name of the mailing, as it is defined in Engage. Includes an additional identifier as a prefix, if defined during data upload. nvarchar SP_Conversion The SP_Conversion table contains data that Engage collects to record conversion events. Column Description Valid values Data type RecordID RecipientID A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the contact that is associated with the event. bigint bigint Primary Key Yes Chapter 9. Custom tracking tables 83

88 Column Description Valid values Data type RecipientType The type of message contact. 0 Regular nvarchar Primary Key MailingID ReportID The ID of the Sent Mailing that is associated with the event. If reporting is configured in Engage, the ID of the report that is associated with the mailing. If reporting is not configured, this field is empty. 1 Forward 3 Seed 4 Inbox Monitoring bigint bigint CampaignID See Report IDs on page 80 The ID of the Group of Automated Messages that is associated with the contact event. The address of the contact. address nvarchar EventType The type of contact event. nvarchar EventTimeStamp ConversionAction ConversionDetail MailingName Event types on page 79 The date and time when Engage recorded the contact event. The action that the user specified for a conversion. The description that the user provided for a conversion. The name of the mailing, as it is defined in Engage. Includes an additional identifier as a prefix, if defined during data upload. datetime nvarchar nvarchar nvarchar SP_Forward The SP_Forward table contains data that Engage collects to record when recipients forwarded the messages that they received. Column Description Valid values Data type RecordID RecipientID A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the contact that is associated with the event. RecipientType The type of message contact. 0 Regular bigint bigint nvarchar Primary Key Yes 1 Forward 3 Seed 4 Inbox Monitoring 84 IBM Campaign and IBM Silverpop Engage: Integration Guide

89 Column Description Valid values Data type MailingID ReportID The ID of the Sent Mailing that is associated with the event. If reporting is configured in Engage, the ID of the report that is associated with the mailing. If reporting is not configured, this field is empty. bigint bigint Primary Key CampaignID See Report IDs on page 80 The ID of the Group of Automated Messages that is associated with the contact event. The address of the contact. address nvarchar EventType The type of contact event. nvarchar EventTimeStamp MailingName Event types on page 79 The date and time when Engage recorded the contact event. The name of the mailing, as it is defined in Engage. Includes an additional identifier as a prefix, if defined during data upload. datetime nvarchar SP_Open The SP_Open table contains data that Engage collects to record when recipients open the messages that they received. Column Description Valid values Data type RecordID RecipientID A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the contact that is associated with the event. RecipientType The type of message contact. 0 Regular bigint bigint nvarchar Primary Key Yes MailingID ReportID CampaignID The ID of the Sent Mailing that is associated with the event. If reporting is configured in Engage, the ID of the report that is associated with the mailing. If reporting is not configured, this field is empty. See Report IDs on page 80 The ID of the Group of Automated Messages that is associated with the contact event. 1 Forward 3 Seed 4 Inbox Monitoring bigint bigint Chapter 9. Custom tracking tables 85

90 Column Description Valid values Data type The address of the contact. address nvarchar EventType The type of contact event. nvarchar Primary Key Event types on page 79 EventTimeStamp The date and time when Engage recorded the contact event. datetime Body Type The format of the message body that the contact received. 0 HTML 1 AOL nvarchar 2 TEXT 3 WEB (click-to-view) MailingName The name of the mailing, as it is defined in Engage. Includes an additional identifier as a prefix, if defined during data upload. nvarchar SP_OptIn The SP_OptIn table contains data that Engage collects to indicate that a message recipient has opted in. Column Description Valid values Data type RecordID RecipientID A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the contact that is associated with the event. RecipientType The type of message contact. 0 Regular bigint bigint nvarchar Primary Key Yes 1 Forward 3 Seed 4 Inbox Monitoring MailingID The ID of the Sent Mailing that is associated with the event. bigint ReportID If reporting is configured in Engage, the ID of the report that is associated with the mailing. If reporting is not configured, this field is empty. bigint CampaignID See Report IDs on page 80 The ID of the Group of Automated Messages that is associated with the contact event. The address of the contact. address nvarchar EventType The type of contact event. Event types on page 79 nvarchar 86 IBM Campaign and IBM Silverpop Engage: Integration Guide

91 Column Description Valid values Data type EventTimeStamp MailingName The date and time when Engage recorded the contact event. The name of the mailing, as it is defined in Engage. Includes an additional identifier as a prefix, if defined during data upload. datetime nvarchar Primary Key SP_OptOut The SP_OptOut table contains data that Engage collects to indicate that a message recipient has opted out. Column Description Valid values Data type RecordID RecipientID A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the contact that is associated with the event. RecipientType The type of message contact. 0 Regular bigint bigint nvarchar Primary Key Yes MailingID ReportID The ID of the Sent Mailing that is associated with the event. If reporting is configured in Engage, the ID of the report that is associated with the mailing. If reporting is not configured, this field is empty. 1 Forward 3 Seed 4 Inbox Monitoring bigint bigint CampaignID See Report IDs on page 80 The ID of the Group of Automated Messages that is associated with the contact event. The address of the contact. address nvarchar EventType The type of contact event. nvarchar EventTimeStamp MailingName Event types on page 79 The date and time when Engage recorded the contact event. The name of the mailing, as it is defined in Engage. Includes an additional identifier as a prefix, if defined during data upload. datetime nvarchar Chapter 9. Custom tracking tables 87

92 SP_Sent The SP_Sent table contains data that Engage collects to record when it sent messages. Column Description Valid values Data type RecordID RecipientID A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the contact that is associated with the event. RecipientType The type of message contact. 0 Regular bigint bigint nvarchar Primary Key Yes MailingID ReportID The ID of the Sent Mailing that is associated with the event. If reporting is configured in Engage, the ID of the report that is associated with the mailing. If reporting is not configured, this field is empty. 1 Forward 3 Seed 4 Inbox Monitoring bigint bigint CampaignID See Report IDs on page 80 The ID of the Group of Automated Messages that is associated with the contact event. The address of the contact. address nvarchar EventType The type of contact event. nvarchar EventTimeStamp MailingName Event types on page 79 The date and time when Engage recorded the contact event. The name of the mailing, as it is defined in Engage. Includes an additional identifier as a prefix, if defined during data upload. datetime nvarchar SP_Suppressed The SP_Suppressed table contains data that Engage collects to record when it suppresses message transmission. Column Description Valid values Data type RecordID RecipientID A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the contact that is associated with the event. bigint bigint Primary Key Yes 88 IBM Campaign and IBM Silverpop Engage: Integration Guide

93 Column Description Valid values Data type RecipientType The type of message contact. 0 Regular nvarchar Primary Key MailingID ReportID The ID of the Sent Mailing that is associated with the event. If reporting is configured in Engage, the ID of the report that is associated with the mailing. If reporting is not configured, this field is empty. 1 Forward 3 Seed 4 Inbox Monitoring bigint bigint CampaignID See Report IDs on page 80 The ID of the Group of Automated Messages that is associated with the contact event. The address of the contact. address nvarchar EventType The type of contact event. nvarchar EventTimeStamp SuppressionReason MailingName Event types on page 79 The date and time when Engage recorded the contact event. The reason a contact was suppressed and a message was not sent. Reasons for contact suppression on page 80 The name of the mailing, as it is defined in Engage. Includes an additional identifier as a prefix, if defined during data upload. datetime nvarchar nvarchar SP_UploadAudit The SP_UploadAudit table contains data for a record of all data uploads from Campaign and related API calls. The system updates the table as it completes each step in the upload process. Column Description Valid values Data type RecordID RunID UserName A unique value to identify the contact record. Assigned when the record is added to the table. The ID of the script execution. It is used to group all steps that are related to a specific upload run. The name of the SFTP user that performs the upload. bigint bigint nvarchar Primary Key Yes Chapter 9. Custom tracking tables 89

94 Column Description Valid values Data type ScriptName Name of the upload script. tableupload nvarchar Primary Key Step FileName SPListID The upload step that is being performed by the script (upload or API name) Name of the file being processed in the step (as applicable). List or Table ID in SilverPop (when applicable) listupload upload <API name> nvarchar nvarchar nvarchar SPMailingID Mailing ID in SilverPop nvarchar StartTime The time the step started. datetime LastStatusUpdate The time of the most recent status update. Status Current status of the upload. STARTED INPROGRESS FAILED datetime nvarchar ErrorMessage Error message if the upload fails. Populated for FAILED status only. SUCCESS nvarchar 90 IBM Campaign and IBM Silverpop Engage: Integration Guide

95 Contacting IBM technical support If you encounter a problem that you cannot resolve by consulting the documentation, your company's designated support contact can log a call with IBM technical support. To ensure that your problem is resolved efficiently and successfully, you collect information before you log your call. If you are not a designated support contact at your company, contact your IBM administrator for information. Information to gather Before you contact IBM technical support, gather the following information: v A brief description of the nature of your issue. v Detailed error messages that you see when the issue occurs. v Detailed steps to reproduce the issue. v Related log files, session files, configuration files, and data files. v Information about your product and system environment, which you can obtain as described in "System information." System information When you call IBM technical support, you might be asked to provide information about your environment. If your problem does not prevent you from logging in, much of this information is available on the About page, which provides information about your IBM applications. You can access the About page by selecting Help > About. If the About page is not accessible, you can obtain the version number of any IBM application by viewing the version.txt file that is located under the installation directory for each application. Contact information for IBM technical support For ways to contact IBM technical support, see the IBM Product Technical Support website: ( Note: To enter a support request, you must log in with an IBM account. If possible, this account must be linked to your IBM customer number. To learn more about associating your account with your IBM customer number, see Support Resources > Entitled Software Support on the Support Portal. Copyright IBM Corp. 2014,

96 92 IBM Campaign and IBM Silverpop Engage: Integration Guide

97 Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information about the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan, Ltd , Nihonbashi-Hakozakicho, Chuo-ku Tokyo , Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-ibm websites are provided for convenience only and do not in any manner serve as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk. Copyright IBM Corp. 2014,

98 IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation B1WA LKG1 550 King Street Littleton, MA U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. All IBM prices shown are IBM's suggested retail prices, are current and are subject to change without notice. Dealer prices may vary. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating 94 IBM Campaign and IBM Silverpop Engage: Integration Guide

99 platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs. If you are viewing this information softcopy, the photographs and color illustrations may not appear. Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at Copyright and trademark information at Privacy Policy and Terms of Use Considerations IBM Software products, including software as a service solutions, ("Software Offerings") may use cookies or other technologies to collect product usage information, to help improve the end user experience, to tailor interactions with the end user or for other purposes. A cookie is a piece of data that a web site can send to your browser, which may then be stored on your computer as a tag that identifies your computer. In many cases, no personal information is collected by these cookies. If a Software Offering you are using enables you to collect personal information through cookies and similar technologies, we inform you about the specifics below. Depending upon the configurations deployed, this Software Offering may use session and persistent cookies that collect each user's user name, and other personal information for purposes of session management, enhanced user usability, or other usage tracking or functional purposes. These cookies can be disabled, but disabling them will also eliminate the functionality they enable. Various jurisdictions regulate the collection of personal information through cookies and similar technologies. If the configurations deployed for this Software Offering provide you as customer the ability to collect personal information from end users via cookies and other technologies, you should seek your own legal advice about any laws applicable to such data collection, including any requirements for providing notice and consent where appropriate. IBM requires that Clients (1) provide a clear and conspicuous link to Customer's website terms of use (e.g. privacy policy) which includes a link to IBM's and Client's data collection and use practices, (2) notify that cookies and clear gifs/web beacons are being placed on the visitor's computer by IBM on the Client's behalf along with an explanation of the purpose of such technology, and (3) to the extent required by law, obtain consent from website visitors prior to the placement of cookies and clear gifs/web beacons placed by Client or IBM on Client's behalf on website visitor's devices For more information about the use of various technologies, including cookies, for these purposes, See IBM's Online Privacy Statement at: privacy/details/us/en section entitled "Cookies, Web Beacons and Other Technologies." Notices 95

100 96 IBM Campaign and IBM Silverpop Engage: Integration Guide

101

102 IBM Printed in USA