Responsys Campaign Integration

MCPS Campaign Job Type is used for integration with Marketing Campaign Orchestration tool such as Responsys. This document describes the campaign jobtype metadata object in MCPS and the rest of configurations required to make audiences available for campaigns run in Responsys.

Sample request to create CAMPAIGN Job

{
  "tenantId": 288,
  "name": "CxuCampaign",
  "versionTS": 1564431646316,
  "description": "Campaign test",
  "active": true,
  "lastModifiedBy": "MCPS_TEST_TENANT:MCPS_TEST_ADMIN_USER",
  "createdTS": 1564431646316,
  "jobId": "CxuCampaign100",
  "jobData": {
    "ctype": ".CampaignJobData",
    "templateInfo": {
      "workflowComponents": [
        {
          "left": "SINK",
          "right": "ResponsysSink_csv"
        }
      ]
    },
    "additionalInfo": {
      "importJobInfo": "{\"materializedAudienceName\":\"CXU_QA_Audience_100\",\"externalSegmentId\":1564431294,\"externalExportJobId\":1564431294,\"audienceName\":\"CXU_QA_Audience_100\",\"description\":\"CXU_QA_Audience_100\",\"listName\":\"test\",\"filterMetadata\":\"\",\"importJobId\":\"178829\",\"fields\":[{\"fieldName\":\"FIRST_NAME\",\"fieldType\":\"STR4000\"},{\"fieldName\":\"LAST_NAME\",\"fieldType\":\"STR4000\"},{\"fieldName\":\"BATCH_ID\",\"fieldType\":\"INTEGER\"}],\"configuration\":{\"name\":\"CXU_QA_Audience_100\",\"description\":\"Configuration for IMPORT JOB\",\"category\":\"\",\"jobType\":\"\",\"subType\":\"UploadMultiExtension\",\"templateUniqueCode\":\"UploadMultiExtension\",\"bpmJobStatus\":null,\"expirationDate\":null,\"isFromCX\":\"yes\",\"pages\":[{\"selected\":\"responsysFTP\",\"connectionTypes\":[{\"server\":\"files.dc2.responsys.net\",\"path\":\"/home/cli/pm_scp/download\",\"userName\":\"pm_scp\",\"type\":\"responsysFTP\"},{\"userName\":\"\"},{\"userName\":\"\"}],\"pageName\":\"SOURCECONNECTIVITY\",\"configuredBy\":\"USER\",\"visibility\":\"EDITABLE\"},{\"fieldDelimiter\":\"comma\",\"fieldEnclosure\":\"QUOTE_2\",\"firstLineContainsColumnNames\":\"YES\",\"characterSet\":\"UTF-8\",\"inboundFile\":{\"prefix\":\"NONE\",\"fileName\":\"ExtAud.*\",\"suffix\":\"NONE\",\"extension\":\"csv\"},\"fileEncryptedPGP_GPG_KEY\":\"NO\",\"fileEncryptedPGP_GPG_KEY_VALUE\":\"\",\"fileSigned_PGP_GPG_KEY\":\"NO\",\"fileSigned_PGP_GPG_KEY_VALUE\":\"\",\"pageName\":\"SOURCESPECIFICATION\",\"configuredBy\":\"USER\",\"visibility\":\"EDITABLE\"},{\"pageName\":\"TARGETDEFINITION\",\"configuredBy\":\"USER\",\"visibility\":\"EDITABLE\",\"subPages\":[],\"profileList\":\"test\",\"targetProfileExtension\":\"CXU_QA_Audience_100\",\"externalSegmentId\":\"1564431294\",\"externalExportJobId\":\"1564431294\",\"isAppChannelList\":\"NO\",\"autoGenerateTargetPET\":\"NO\",\"sourceFileHasPersonalizeData\":\"NO\",\"includeOptedOut\":\"NO\",\"supplementalData\":{\"folderId\":\"\",\"supplementalTableId\":\"\"},\"automaticPETGeneration\":{\"templateProfileExtension\":\"\",\"oneProfileExtensionForEachSourceFile\":\"\",\"folderId\":\"\",\"expirationDays\":\"\",\"targetPETNameRule\":{\"type\":\"useSourceFileName\",\"nameSpecification\":{\"name\":\"\",\"suffix\":\"\"}}}},{\"pageName\":\"DATARULES\",\"configuredBy\":\"USER\",\"visibility\":\"EDITABLE\",\"subPages\":[],\"importDateFormat\":\"yyyy-MM-dd HH24:mi:ss\",\"recordMatchRule\":\"IGNORE_RECORD\",\"recordNoMatchRule\":\"IMPORT\",\"matchCriteria\":{\"key1\":\"CUSTOMER_ID_\"},\"importIntoProfileList\":\"YES\",\"profileListHandling\":{\"matchCriteria\":{\"key1\":\"CUSTOMER_ID_\"},\"recordMatchRule\":\"IGNORE_RECORD\",\"recordNoMatchRule\":\"IMPORT\",\"rejectRecordFieldEmptyRule\":{\"email\":\"NO\",\"mobile\":\"NO\",\"postal\":\"NO\"},\"importDateFormat\":\"yyyy-MM-dd HH24:mi:ss\",\"emailFormatHTML\":\"H\",\"emailFormatText\":\"T\",\"defaultOptOption\":\"Opt out\",\"optInStatus\":\"I\",\"optOutStatus\":\"O\",\"mobileNumberUploadFormat\":{\"mobileNumberUploadType\":\"E164\",\"mobileCountryCode\":\"US\"},\"enableFilteringAgainstLatestLoadName\":\"NO\"},\"supplementalDataRules\":{\"type\":\"MERGE\",\"mergeRule\":{\"usePrimaryKey\":\"YES\",\"mergeField\":\"CUSTOMER_ID_\",\"recordMatchRule\":\"OVERWRITE\",\"recordNoMatchRule\":\"IMPORT\"}}},{\"pageName\":\"FIELDMAPPING\",\"configuredBy\":\"USER\",\"visibility\":\"EDITABLE\",\"subPages\":[],\"fields\":[{\"incomingField\":\"FIRST_NAME\",\"matchField\":\"FIRST_NAME\",\"targetTable\":\"\"},{\"incomingField\":\"LAST_NAME\",\"matchField\":\"LAST_NAME\",\"targetTable\":\"\"},{\"incomingField\":\"CUSTOMER_ID_\",\"matchField\":\"CUSTOMER_ID_\",\"targetTable\":\"\"},{\"incomingField\":\"BATCH_ID\",\"matchField\":\"BATCH_ID\",\"targetTable\":\"\"}],\"profileListFields\":[{\"incomingField\":\"CUSTOMER_ID_\",\"matchField\":\"CUSTOMER_ID_\",\"targetTable\":\"test\"}]},{\"pageName\":\"NOTIFICATION\",\"configuredBy\":\"USER\",\"visibility\":\"EDITABLE\",\"subPages\":[],\"email\":\"pratyu.t@oracle.com\",\"notify\":\"NO\",\"notifyByEmail\":\"NO\"},{\"pageName\":\"SCHEDULE\",\"configuredBy\":\"USER\",\"visibility\":\"EDITABLE\",\"subPages\":[],\"scheduleDetails\":{\"scheduleType\":\"none\",\"recurring\":{\"startDate\":\"\",\"startTime\":\"\",\"endDetails\":{\"hasEndDate\":\"NO\",\"endDate\":\"\"},\"recurringDetails\":{\"recurringType\":\"hourly\",\"hourly\":{\"everyHours\":\"\"},\"daily\":{\"everyDays\":\"\"},\"weekly\":{\"days\":[]},\"monthly\":{\"monthlyDetailType\":\"\",\"fixedday\":{\"dayOfTheMonth\":\"\",\"lastDayOfMonth\":\"NO\"},\"specificday\":{\"when\":\"\",\"weekday\":\"\"}}}},\"runonce\":{\"date\":\"\",\"time\":\"\"}}}]}}"
    },
    "mcpsQueryId": "Responsys",
    "ttlInSeconds": 36000000,
    "campaignId": "Responsys"
  },
  "notifications": []
}

Responsys Integration Configuration flow

Step 1: Responsys sink instance is configured for user - either as OOTB or UI allows user to provide the required parameters such as API endpoint, PEM and create Responsys sink instance.

Endpoints

{
  "tenantId": 288,
  "name": "ResponsysSink",
  "versionTS": 1559164937365,
  "description": "Responsys sink",
  "active": true,
  "createdTS": 1559063796310,
  "componentDefinitionId": "ResponsysSink",
  "uniqueInstanceId": "ResponsysSink_csv",
  "parameters": {
    "referenceName": "ResponsysSink_csv",
    "campaignId": "${campaignId}",
    "authApiUrl": "https://login5.responsys.net/rest/api/v1.3/auth/token",
    "authApiUser": <yourusername>,
    "authApiPassword": <yourpassword>,
    "importApiUri": "/rest/internalapi/v1.3/extaudience/",
    "path": "sftp://pm_scp@files.dc2.responsys.net/home/cli/pm_scp/download",
    "fileName": "QATEST1",
    "fileCompressionFormat": "none",
    "pem": "-----BEGIN RSA PRIVATE KEY----- <yourpem> ----END RSA PRIVATE KEY-----"
  }
}

Step 2: User creates and saves MCPS Queries for segmentation

Note: Expected output of MCPSQuery is the audience list. Typical output attributes of this query will have the identifier fields for Responsys such as Responsys Customer ID, First Name, Last Name, Email address.

Step 3: Responsys list, Responsys connect job configuration

1. User selects Responsys list.

   Note: CXUnity UI can fetch list of Resposnys lists using Responsys API. This will be preferred approach for a seamless integration.

2. User creates connect job on Responsys or chooses an existing Responsys connect job to fetch the exported data file.

   • NOTE: CXUnity UI can create a connect job in Responsys or fetch list of existing connect jobs from Responsys., using Responsys API. This will be preferred approach for seamless integration.
   • When user saves the connect job, they get back an importJobId. This jobId must be saved along with the entire request payload in job.additionalInfo (key = importJobInfo, value = string json) as described in next step.

3. Connect Job will have the following:

   • "BATCH_ID" (type INTEGER) that must be added to the fields on the connect job.
   • NOTE: The value of BATCH_ID is supplied by MCPS when the campaign job is run.
   • BATCH_ID value comes back to MCPS during the event feed from Responsys. This is how the campaign is tracked.
   • externalSegmentId (must be unique)
   • externalExportJobId (must be unique)
   • audienceName must be unique (user entered or epoch timestamp)
   • fileName and extension - should match the one in the MCPS Responsys sink. The fileName in the connect job should have a wild card at the end to account for timestamp suffixes e.g. AudienceFile.*
   • matchCriteria must specify which Responsys field to match on
   • fields - attributes in CSV file. (=has incoming fields (aka MCPS fields), match field (aka RSYS field),
   • scheduleType (always set to "none")

Step 4: MCPS Campaign job configuration

1. User creates Campaign Job. Campaign Job metadata has these fields:

   • Responsys sinkInstanceId
   • MCPSQueryId
   • Fields corresponding to output attributes in the MCPSQuery.
   • AdditionalInfo->ImportJobInfo - This is saved connect job request job with the importjobId (key = importJobInfo, value = string json)
   • campaignId (Optional field, kept to allow triggering of campaigns programmaticaly in future)
2. The newly created campaign jobs and/or sinkInstances and all changes to existing metadata need to be published.
3. MCPS Campaign Job exports the output of MCPSQuery as a CSV file to the destination specified in SinkInstance.
4. MCPS Campaign job also triggers Responsys connect job using the importJobId. Responsys connect job will then ingest the MCPS exported data into Responsys list (specified in Responsys connect job)
5. User can then log into Responsys and select the imported audience on one of the campaigns and launch the campaign.

Step 5: Campaign Reporting configuration

For campaign reporting in CXUnity/MCPS, campaign launch data must be ingested in MCPS.

1. Responsys user can create campaign events file every 4 hours on their FTP server.
2. CXUnity User creates MCPS ingest job to grab Responsys events files and ingest campaign events data.

Mapping for this ingest job will be provided as OOTB mapping template (See ingest mapping templates section below)

Step 6: Responsys Profile Ingest configuration (Also, See ingest mapping templates section below)

From the segment output exported to Responsys, Responsys will ingest profile records that match with their profile data. Records that do not have entry in Responsys will be ignored by Responsys. In order to improve this match rate, user must import entire Responsys user population to CXUnity and should continue to import deltas.

Configuration steps:

1. User creates a profile list export connect job in Responsys. User puts this job on a set schedule to export selected list profile data to the specified location.
2. User creates a profile ingest job on MCPS for Responsys. User sets this job on a set schedule, co-ordinated with the job completion in point 1 above.

Mapping for this ingest job will be provided as OOTB mapping template (See ingest mapping templates section below).

Ingest Mapping template

For ingesting Responsys Campaign events data and Responsys Profiles data.

Endpoint

Learn more

Jobs API