Service Model
With the exception of AppCloud Menus and the AppCloud Firehose, AppCloud Services follow an instantiation-execution model. When you add an AppCloud Decision or AppCloud Action step to a campaign in the Campaign Canvas, a new instance of that AppCloud Decision or AppCloud Action service is created. When that campaign reaches the Decision or Action stage, the service is executed. Similarly, when AppCloud Content is added to an email or landing page, a new instance of that AppCloud Content service is created.
Service Instantiation
- A Marketer drags the AppCloud service onto the Campaign Canvas or onto an email or landing page in the asset editor. This triggers a call from the Eloqua UI to an internal Eloqua API that will interact with your servers.
- The internal Eloqua API calls out to your service using the templated Create URL you configured when registering your App. This is a POST request, authenticated with OAuth, which contains an empty JSON object. The call provides you with the new instance's GUID.
For example, AwesomeApp has an AppCloud Decision service whose Create URL is:https://example.com/awesomeapp/decide/create?instance={instanceId}
- Eloqua calls out to this URL with an empty JSON object, replacing the templated parameters with the service instance ID and app installation ID.
Your application should respond with default details in a Record Definition Data Transfer Object (DTO). For example, for an AppCloud Decision service, the response might resemble:
"recordDefinition" :{
"ContactID" : "{{Contact.Id}}",
"EmailAddress" : "{{Contact.Field(C_EmailAddress)}}"
}
This tells Eloqua to send the contacts' Contact ID and email address when the service is executed. For detailed instructions, see the documentation specific to each service type.
The Marketer can then configure the instance using your service's UI by clicking on the "Edit" button on the service instance. Eloqua opens a browser window to the Configure URL for the service. Note: this call to the Configure URL comes directly from the marketing user's browser, rather than from the Eloqua API. If you need to restrict access, you can do so here by requiring the user be on a specific VPN, for example.
If the Marketer has made changes, your API should call back to Eloqua using a PUT request with an updated DTO specifying the new record definition. For example, if the Marketer created an AppCloud Decision step that required field1, field2, and field3, the PUT request would resemble:
PUT https://secure.eloqua.com/api/cloud/1.0/decisions/instance/{instanceId}
"recordDefinition":
{
"ContactID" : "{{Contact.Id}}",
"EmailAddress" : "{{Contact.Field(C_EmailAddress)}}",
"field1" : "{{Contact.Field(C_field1)}}",
"field2" : "{{Contact.Field(C_field2)}}",
"field3" : "{{Contact.Field(C_field3)}}"
}
Execution
When the AppCloud service is activated, either by contacts flowing through a campaign or a visit to a landing page, this batch of contacts is tagged with an execution ID that tracks its progress.
This step varies depending on the service type, but in general, the Eloqua internal API calls out to the Service's notification URL, and transmits a the information you specified during the configuration phase. In the above example, then, the recordDefinition includes the contact's ID, email address, field1, field2 and field3. The call to the notification URL would then resemble:
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" : "sylvie@example.com",
"field1" : "more stuff",
"field2" : "other things",
"field3" : "and so on"
}
]
}
This follows the format defined during the create URL and configure URL calls during the Instantiation phase.
- If your service is unavailable, Eloqua will retry five times. If you specified Maximum Record size of 0 when you configured your App, or the record definition sent during the instantiation phase contains no fields, the DTO contains an empty JSON object. Otherwise, the call sends a DTO containing contact data, with a maximum limit to the number of records as specified in the service configuration. If there are more records than the maximum limit, Eloqua will keep sending requests until all the data is transmitted.
- You can then choose to return the same response for all the contacts in the batch, or tailor your responses to each contact.
To individualize your responses for each contact, the desired HTTP response status code is a 204, followed up with an Import call using Eloqua's Bulk API. You must specify sync actions during the import. The appropriate sync actions vary according to the service type. Refer to the Bulk API documentation and the service-specific documentation (linked below) for more information Eloqua receives the import. For service instances associated with a campaign, those contacts flow through to the next stage.
Services
The AppCloud™ Developer Platform currently supports five services. Additional services will be included in future releases. While the general interaction pattern for all services is similar, each service has its own particularities. Follow the links below for in-depth descriptions and explanations of the interaction patterns, requests, and calls necessary to implement each AppCloud service.