Developing for campaign responses
This tutorial provides a walkthrough of considerations when developing an app and service for Campaign Responses. The campaign response endpoints generally work the same as other Bulk API endpoints, however there are some unique considerations. The following guidelines are meant to instruct developers on how to best use the campaign response endpoints. In this tutorial:
- Understanding workflows
- Developing apps and services
- Calling the endpoints
- Troubleshooting
Understanding workflows
As an app provider, your implementation of your app workflow may be unique. Here is an example workflow of how developers could use these endpoints:
- Contacts enter app service step and Eloqua notifies app.
- App retrieves campaign responses from Eloqua with a campaign response definition.
- App sends campaign responses to a CRM.
- App responds back to Eloqua with a campaign response import definition for every successful campaign response created in the CRM.
- App uses a sync action to move contacts along.
Developing apps and services
The following are guidelines to ensure that apps and services that are used to send campaign responses to CRM are optimized correctly:
-
Ensure Records per Notification is set to 0
During Action Service registration, we recommend that the Records per Notification should be is set to 0 given you are always going to be exporting campaign responses in a separate sync.
Calling the endpoints
POST
/api/bulk/2.0/campaignResponses/exports
General endpoint usage
In the filter, your service instance ID is specified. If your service instance ID has not been selected to consume campaign responses, a validation error will be returned.
This export requires records to be in the step. In the filter, a valid execution ID is also required, and the validation error will be returned if there is not a valid execution ID.
{
"name": "Example Campaign Response Export",
"fields": {
"CampaignResponseId": "{{CampaignResponse.Id}}",
"MemberStatus": "{{CampaignResponse.Field(MemberStatus)}}",
"CampaignMembershipId": "{{CampaignResponse.Field(IntegrationReturnValue)}}",
"CreatedAt": "{{CampaignResponse.CreatedAt}}",
"CRMCampaignId": "{{CampaignResponse.Campaign.Field(CRMCampaignId)}}",
"EloquaCampaignId": "{{CampaignResponse.Campaign.Id}}",
"EloquaCampaignName": "{{CampaignResponse.Campaign.Field(CampaignName)}}",
"LeadId": "{{CampaignResponse.Contact.Field(C_OracleFusionLeadID)}}",
"ContactId": "{{CampaignResponse.Contact.Field(C_OracleFusionContactID)}}",
"EmailAddress": "{{CampaignResponse.Contact.Field(C_EmailAddress)}}"
},
"filter": "STATUS('{{ActionInstance(7BE704D3AF604775AD416E8D0A5AB212).Execution[12345]}}') = 'pending'"
}
Date ranges
By default, when creating campaign response export definitions, you will get 30 days of campaign responses. This is the limit of how far in the past campaign responses can be retrieved.
If you want to retrieve anything other than 30 days, developers can use a date range in the filter to filter results to be anything less than 30 days. If a date filter is greater than 30 days, a validation error will be returned.
Here's an example of a campaign response export definition using a date range filter.
{
"name": "Example Campaign Response Export with date filter",
"fields": {
"CampaignResponseId": "{{CampaignResponse.Id}}",
"MemberStatus": "{{CampaignResponse.Field(MemberStatus)}}",
"CampaignMembershipId": "{{CampaignResponse.Field(IntegrationReturnValue)}}",
"CreatedAt": "{{CampaignResponse.CreatedAt}}",
"CRMCampaignId": "{{CampaignResponse.Campaign.Field(CRMCampaignId)}}",
"EloquaCampaignId": "{{CampaignResponse.Campaign.Id}}",
"EloquaCampaignName": "{{CampaignResponse.Campaign.Field(CampaignName)}}",
"LeadId": "{{CampaignResponse.Contact.Field(C_OracleFusionLeadID)}}",
"ContactId": "{{CampaignResponse.Contact.Field(C_OracleFusionContactID)}}",
"EmailAddress": "{{CampaignResponse.Contact.Field(C_EmailAddress)}}"
},
"filter": "STATUS('{{ActionInstance(7BE704D3AF604775AD416E8D0A5AB212).Execution[12345]}}') = 'pending' AND '{{CampaignResponse.CreatedAt}}' > '2017-09-01 13:41:20.985'"
}
POST
/api/bulk/2.0/campaignResponses/imports
General endpoint usage
You must specify your service instance id with the serviceInstanceId property and this must match the selected service instance to consume campaign responses, or else a validation error will be returned. We recommend using the CampaignMembershipId from the CRM for the IntegrationReturnValue Campaign Response field. The existence of the IntegrationReturnValue Campaign Response field value is how we know not to send this Campaign Response record in the future, so a value should be imported to this field for every campaign response record that is successfully created in CRM.
Both the CampaignResponseId and IntegrationReturnValue fields are required in a campaign response import. Additionally, these are the only two fields allowed in a campaign response import.
This endpoint could be used to test if your instance has been selected to consume campaign responses, and block activating a canvas if it has not. For example, the requiresConfiguration property on the DTO could be set to false, requiring the User to click the instance configuration. Within configuration, there could be a Validate instance selected to consume campaign responses button, which could initiate a campaign responses import with the service instance ID to confirm if it is successful. If successful, the app could set requiresConfiguration to true and unblock activation. If not successful, instructions could be provided on how to set the instance to consume campaign responses.
It is important to note that there are various campaign responses that could exist for a contact. In the scenario where there are multiple campaign responses for a contact and one of those responses errors, app providers must determine how to handle that error.
Troubleshooting
If you experience any difficulty using the campaign response endpoints, see the following troubleshooting tips.
Ensure the selected service instance within a Campaign or Program canvas is in a draft or deactivated state before changing the selection
If the selected service instance is in an Active canvas, the selection cannot be changed. To change the instance to consume campaign responses, the canvas the current selection is located must be deactivated.
What happens if contacts are reaching the step, but do not have any campaign responses?
If contacts reach the step, but do not have any campaign responses, records with contact fields are sent and all campaign response fields are blank for these records.