AppCloud Decisions are steps in the Campaign Canvas that directly control the path a contact takes as they flow through a campaign. AppCloud Decision steps delegate the decision making to an external system, which responds with a "yes" or "no" for each contact, determining which path the contacts should take.
Quickstart
AppCloud Decisions follow the same instantiation-execution model as described in the Write Apps for Eloqua's AppCloud™ document. The following sections describe AppCloud Decision-specific details and provide the endpoints needed to develop an AppCloud Decision service. If you are not familiar with the general flow for the instantiation-execution model, you should read that first.
Eloqua signs all outgoing calls with OAuth 1.0a so the receiving system can validate that the call was sent by Eloqua. Refer to the OAuth 1.0a spec or OAuth 1.0 RFC for more information.
CreateURL call and response
Eloqua's call to the CreateURL:
POST https://example.com/awesomeapp/decide/create?instance=123
{}
AwesomeApp's response is a DTO describing the fields Eloqua should transmit when the service in executed:
{
"recordDefinition" :
{
"ContactID" : "{{Contact.Id}}",
"EmailAddress" : "{{Contact.Field(C_EmailAddress)}}"
}
}
Cloud API call from AwesomeApp
When a user makes changes through the Configure URL that requires an updated recordDefinition DTO, AwesomeApp must call out to Eloqua's Cloud API with that updated DTO:
PUT https://secure.eloqua.com/api/cloud/1.0/decisions/instances/123
{
"recordDefinition":
{
"ContactID" : "{{Contact.Id}}",
"EmailAddress" : "{{Contact.Field(C_EmailAddress)}}",
"field1" : "{{Contact.Field(C_field1)}}",
"field2" : "{{Contact.Field(C_field2)}}",
"field3" : "{{Contact.Field(C_field3)}}"
}
}
Notification URL Call and Response
Eloqua's call to the Notification URL transmits the requested fields in the items parameter:
POST https://example.com/awesomeapp/decide/notify?instance=123&asset=456
{
"offset" : 0,
"limit" : 1000,
"totalResults" : 2,
"count" : 2,
"hasMore" : false,
"items" :
[
{
"ContactID" : "1",
"EmailAddress" : "fred@example.com",
"field1" : "stuff",
"field2" : "things",
"field3" : "et cetera"
},
{
"ContactID" : "2",
"EmailAddress" : "john@example.com",
"field1" : "more stuff",
"field2" : "other things",
"field3" : "and so on"
}
]
}
AwesomeApp responds with a 204 response, indicating that the response will be asynchronous, followed by an import to Eloqua's Bulk API, where AwesomeApp specifies a sync action. For AppCloud Actions, the sync action is either "yes", "no", or "errored". AwesomeApp will need to create multiple imports for the different statuses, with contacts that should follow the "no" path in one import and contacts that should follow the "yes" path in another. Note that the maximum import size per batch is 50,000: if you have more than 50,000 contacts, break your data up into multiple imports.
Bulk API Import
- Create the bulk import definition, setting the status to yes. The "destination" field refers to the AppCloud Action service's instance - in this example, the instance ID is 123:
POST https://secure.eloqua.com/api/bulk/2.0/contacts/imports ?
{
"name" : "AwesomeApp Decision Response Bulk Import",
"updateRule" : "always",
"fields" : {
"emailAddress" : "{{Contact.Field(C_EmailAddress)}}"
}
"syncActions" : [
{
"destination" : "{{DecisionInstance(123)}}",
"action" : "setStatus",
"status" : "yes"
}
],
"identifierFieldName" : "emailAddress"
}
Eloqua's response will be a 201 Created response that includes a uri parameter, which you use to identify the import:
201 Created
{
"name" : "AwesomeApp Decision Response Bulk Import",
"updateRule" : "always",
"fields" : {
"emailAddress" : "{{Contact.Field(C_EmailAddress)}}"
},
"identifierFieldName" : "emailAddress",
"syncActions" : [
0 : {
"destination" : "{{DecisionInstance(123)}}",
"action" : "setStatus",
"status" : "yes"
}
],
"isSyncTriggeredOnImport" : false,
"isUpdatingMultipleMatchedRecords" : false,
"uri" : "/contacts/imports/6",
"createdBy" : "DocsExample",
"createdAt" : "2014-03-06T13:59:00.6600046Z",
"updatedBy" : "DocsExample",
"updatedAt" : "2014-03-06T13:59:00.6600046Z"
}
- Send Eloqua the data for import as a using the uri:
POST https://secure.eloqua.com/api/bulk/2.0/contacts/imports/6/data
[
{
"emailAddress" : "fred@example.com"
},
{
"emailAddress" : "sylvie@example.com"
}
]
- Synchronize the data for import:
AwesomeApp's request:
POST https://secure.eloqua.com/api/bulk/2.0/syncs ?
{
"syncedInstanceUri" : "/contacts/imports/6"
}
Eloqua's Response:
201 Created
{
"syncedInstanceURI" : "/contacts/imports/6",
"status" : "pending",
"createdAt" : "2014-01-01T13:59:07.1375620Z",
"createdBy" : "DocsExample",
"uri" : "/syncs/6"
}
- You can then use the sync's uri (/syncs/6) to check the status of the sync:
GET https://secure.eloqua.com/api/bulk/2.0/sync/6
For a full description of the sync status codes, see: Bulk API Sync Status Codes
When the sync is complete, Eloqua's response will resemble:
200 OK
{
"syncedInstanceURI" : "/contacts/imports/6",
"syncStartedAt" : "2014-01-01T13:59:07.1375620Z",
"syncEndedAt" : "2014-01-01T13:59:14.1375620Z",
"status" : "success",
"createdAt" : "2014-01-01T13:59:07.1375620Z",
"createdBy" : "DocsExample",
"uri" : "/syncs/6"
}
Next Steps
Now that you're familiar with the setup for AppCloud Decisions, you can check out the other AppCloud Service configurations at: