AppCloud Content allows marketers to source pieces of content in Eloqua emails and Landing Pages, from an external source. This is the new and improved version of Eloqua's Cloud Components framework, and it includes many improvements such as asynchronous bulk processing (for emails), the ability to fully test the content service within Eloqua, and design-time interaction with the Email and Landing Page editors.
Quickstart
AppCloud Content follow the same general instantiation-execution model as described in the Write Apps for Eloqua's AppCloud™document. The following sections describe AppCloud Content-specific details and provide the endpoints needed to develop an AppCloud Content 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/content/create?instance=123
{}
For an AppCloud Content service, AwesomeApp's response must include height, width, and default editorImageUrl, as well as the recordDefinition parameter.
The height and width parameters define the size of the content instance when rendered, while editorImageUrl specifies the url for an image that Eloqua will display in the editor's design surface. editorImageUrl` is not a templated URL.
{
"recordDefinition" :
{
"ContactID" : "{{Contact.Id}}"
},
"height" : 256,
"width" : 256,
"editorImageUrl" : "https://example.com/image.png"
}
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/contents/instances/123
{
"recordDefinition":
{
"ContactID" : "{{Contact.Id}}",
"EmailAddress" : "{{Contact.Field(C_EmailAddress)}}",
},
"height" : 256,
"width" : 256,
"editorImageUrl" : "https://example.com/image.png"
}
Notification URL Call and Response
Eloqua's call to the Notification URLs transmits the requested fields in the items parameter. You configure the notify request size when you register your app with Eloqua, and Eloqua will send the items in batches until all have been transmitted. If the maximum batch size was 5000, for example, and you had 10,000 items, Eloqua would send the items in two batches. The calls to the Notification URL resemble:
POST https://example.com/awesomeapp/content/notify?instance=123&asset=456
{
"offset" : 0,
"limit" : 1000,
"totalResults" : 2,
"count" : 2,
"hasMore" : false,
"items" :
[
{
"ContactID" : "1",
"EmailAddress" : "fred@example.com"
},
{
"ContactID" : "2",
"EmailAddress" : "john@example.com"
}
]
}
For AppCloud Content services, AwesomeApp's response will depend on whether the content is for an Email or a Landing Page:
- For Landing Pages, the response is a 200 status code with text/html content inline. If the response takes too long, Eloqua uses the default content for that contact.
- For Email, AwesomeApp can respond in one of two ways:
- Inline Response: A 200 status code with text/html content inline, in which case Eloqua uses the same content for each contact (this is the same response type as used for landing pages), or
- Asynchronous Response: A 204 status code, indicating that the call was accepted, but there is no content to return directly. The service should process asynchronously and then call the {callbackUrl} parameter with contact-specific content.
Inline Response
The inline response for landing pages and email is a 200 status code, followed by the text/html content. For example:
200 OK
Content-Type: text/html
{
<div>
<h1>External Content</h1>
<p>This content is used for all recipients for this request.</p>
</div>
}
Asynchronous Response
For the asynchronous response, AwesomeApp responds with a 204 status code, indicating that the response will be asynchronous, followed by one or more imports to Eloqua's Bulk API, where contact-specific content is updated with the ContactId and the instance Id, mapping the contact to the new html content.
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.
- Create the bulk import definition, including a Content parameter whose value is the service instance ID.
POST https://secure.eloqua.com/api/bulk/2.0/contacts/imports ?
{
"name" : "AwesomeApp Content Response Bulk Import",
"updateRule" : "always",
"fields" : {
"EmailAddress" : "{{Contact.Field(C_EmailAddress)}}"
"Content" : "{{ContentInstance(--instanceID--)}}"
},
"identifierFieldName" : "EmailAddress"
}
Eloqua's response will be a 201 Created response that includes a uri parameter, which you can use to identify the import:
201 Created
{
"name" : "AwesomeApp Content Response Bulk Import",
"updateRule" : "always",
"fields" : {
"EmailAddress" : "{{Contact.Field(C_EmailAddress)}}"
"Content" : "{{ContentInstance(--InstanceID--)}}"
},
"identifierFieldName" : "EmailAddress",
"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, using the service's Instance ID as the parameter with the content that Eloqua should use for each contact:
POST https://secure.eloqua.com/api/bulk/2.0/contacts/imports/6/data
[
{
"EmailAddress" : "fred@example.com",
"Content" : "<p>This is the content for Fred</p>"
},
{
"EmailAddress" : "sylvie@example.com"
"Content" : "<p>This is the content for Sylvie</p>"
}
]
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:
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 Content, you can check out the other AppCloud Service configurations at: