Oracle AppCloud Developer Framework Developer Guide

and

Learn more by watching the video

1.4.2 Oracle Eloqua AppCloud Decisions

Decisions allow a marketer to delegate a decision-making step in a campaign to an external system without having to bring the system's data into Eloqua. Decision services evaluate contacts using externally-held data, and determine whether the contacts meet the criteria. The service responds with

'yes' or 'no' to determine which path the contact should take through the campaign or program workflow. For example, a decision service could check if a contact exists in a CRM system, and sort the contacts accordingly. With AppCloud Decisions, the data used in the decision never needs to be brought into Eloqua. Read more about Decisions in the

and

Learn more by watching the video

1.4.3 Oracle Eloqua AppCloud Feeders

With Feeders, developers can build apps that use data in third-party services to drive campaign and program membership. Feeders allow marketers to populate a campaign or program with contacts/custom objects from an external system, automatically importing the contacts or custom objects into Eloqua and adding them to a campaign or program. Read more about Feeders in the

and

Note: For marketers using Eloqua's campaign canvas, feeder services are referred to as

AppCloud Audiences.

Learn more by watching the video

1.4.4 Oracle Eloqua AppCloud Content

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. Read more about Content in the

and

1.4.5 Oracle Eloqua AppCloud Menus

The AppCloud Menus service is all about

context

. AppCloud Menus enable a marketer to launch an externally-hosted application from within Eloqua via a menu dock. This menu dock floats on the right side of the screen in the Campaign Canvas or asset editor screens. Read more about Menus in the

and

1.4.6 Oracle Eloqua AppCloud Firehose

The Firehose service, acts as a web hook, and notifies an external system when a marketer performs an action in Eloqua. For example, when a marketer creates a campaign or edits an email, Eloqua can call out to the third-party with the update. Read more about the Firehose service in the

service registration instructions

and

1.5 Introduction to URL Templating

The Oracle Eloqua AppCloud Developer Framework supports

URL Templating

to enable you to configure the service URIs that Eloqua calls out to. Any acceptable template parameter is substituted with the appropriate value before the call is made.

Common URL parameters include

{ UserId

} , the unique identifier for the user whose actions triggered the call,

instantiation-execution model , which Actions, Decisions, Feeders, and Content follow. Then, you can

} , the GUID-based ID that identifies an instance of a service, and

{ EventType }

, which provides campaign status information (Created, Activated, Draft, and so on). These URL parameters enable you to configure the service URLs that Eloqua calls out to, specifying the information that you need for your application.

1.5.1 Example

Consider this templated URL:

https://awesomeapp.example.com/create/instance=

{InstanceId}&asset={AssetId}&site={SiteName}

When Eloqua calls the URL, the templated parameters are replaced with the appropriate values: https://awesomeapp.example.com/create/instance=b5fc25ce-9709-

42c4-a57d-caa00e23f658&asset=45&site=DocsExampleSite

1.5.2 Recommendations

Choose the URL parameters to include in your templated URLs based on your use case. These parameters provide contextual information: your application design will determine which parameters you need. The full list of parameters is available. The

url parameters reference

provides a description for each parameter. You should familiarize yourself with the supported URL parameters when designing your templated URLs.

The service registration guides also include suggestions for parameters to include for specific URLs.

These recommendations are the minimum you will likely need. Include additional parameters if you require them.

1.6 AppCloud Frequently Asked Questions

1.6.1 General

Why should I develop apps for the Oracle Eloqua AppCloud?

The AppCloud Developer Framework is a complete development platform where you can easily build, register, and deploy apps for Eloqua. With new and improved service types which take advantage of

Eloqua's Bulk API , support for OAuth, and the ability to test your applications with Eloqua prior to launch, the AppCloud Developer Framework provides the environment needed to put apps first.

What permissions do I need to start developing apps for the Oracle Eloqua

AppCloud?

At the minimum, you need access to an Eloqua instance. If you are not currently an Eloqua user, you can sign up as a technology partner to obtain a development instance. As a user, you will also need the

Advanced Users - Marketing permissions.

When and how does my app get listed on the Oracle Eloqua AppCloud site?

See the Building Apps for the Oracle Marketing AppCloud page on Topliners for detailed instructions.

How do marketers find my app to start using it?

Registered apps are listed on the Oracle Cloud Marketplace . Users are linked to this page through the

"Get more Apps" link in Eloqua's AppCloud Catalog section.

Is there an Oracle Eloqua AppCloud certification program?

Yes there is! Check out the Oracle Marketing AppCloud Certification Program on Topliners.

1.6.2 Oracle Eloqua AppCloud Services and Operations

Which service should I develop?

It depends on what you're trying to achieve! See the

Service Descriptions

for an overview of each service and the use cases it supports.

What's the difference between Oracle Eloqua AppCloud services and

Cloud Connectors or Components?

Eloqua Oracle Eloqua AppCloud services greatly extend the functionality provided by

Cloud Connectors and Cloud Components. Cloud Content replaces Cloud Components, allowing you to process emails in bulk and test the service within Eloqua. Unlike Cloud Connectors and

Components, the Oracle Eloqua AppCloud services use Eloqua's Bulk API for processing, greatly improving performance and throughput.

Can I include Campaign, Email, Landing Page, Form (etc) fields in my record definition?

No. The Oracle Eloqua AppCloud exclusively supports Contact, Account, Activity and Custom Object fields in its record definition fields. You must use the correct Eloqua Markup Language statement to reference each field.

Can I include static values in my record definition?

No. You can only specify the Eloqua Markup Language for Eloqua fields.

1.6.3 Managing Your Apps

What happens if contacts encounter an error in an Action or Decision step? What happens if the service is unavailable when contacts flow into a step on the canvas?

The contacts remain in the step until the marketer manually pushes them into the next step on the canvas.

Does Eloqua notify me when someone uninstalls or deletes my app from their

Eloqua instance?

If you set an

Uninstall URL

it will be called when a user uninstalls the app.

Why has my app been shut down?

If in the last five minutes, there were more than 100 calls, and 25% of them failed, the app will be shut down. All the pending and future requests will be marked as failed. See the

App Shutdown

for more information.

Will Eloqua retry my contacts if my app doesn't respond?

If Eloqua calls out to your app and receives five consecutive failures, the contacts in a step will be marked as "Errored". If the marketer has configured a default path for the contacts to flow through, then the contacts will flow into the next step.

Why does my app prompt the error "502 Error: App Provider not Available"?

This error message will appear if a URL has been configured with a non-standard port. Eloqua only supports the standard ports 80 and 443. If a URL is not configured with port 80 or port 443, requests to this URL will fail.

1.6.4 Limits

Are there limits that I should be aware of?

The AppCloud Developer Framework relies on the Bulk API. The Bulk API has limits on the size of the staging area for imports and exports, on the amount of data you can import at one time, and on the

number of fields you can include in a record definition. There is also a daily limit on the number of syncs you can perform.

What happens if I reach the daily sync limits?

The daily sync limit is not currently enforced, but syncs are logged and monitored.

2 Develop an App

The Oracle Eloqua AppCloud Developer Framework provides 6 service types that you can develop to extend Eloqua's functionality. Some services create steps that a marketer can add to the campaign canvas, or to an email or landing page, another service type enables marketers to launch third-party applications directly from within Eloqua's UI, while another yet creates a web hook that calls out to a third-party service when a marketer performs an action within Eloqua.

These services make it easy for developers to extend Eloqua's capabilities, providing new opportunities for marketers to harness both Eloqua data and external services to better serve their goals.

Before you start developing Oracle Eloqua AppCloud services, familiarize yourself with the

read the development guides:

Develop an Action Service

Develop a Decision Service

Develop a Feeder Service

Develop a Content Service

Develop a Firehose Service

Develop a Menu Service

2.1 Instantiation-Execution Model

With the exception of Menus and the Firehose, Oracle Eloqua AppCloud Services follow an instantiation-execution model. When you add an Decision or Action step to a campaign in the

Campaign Canvas, a new instance of that Decision or Action service is created. When that campaign or program reaches the Decision or Action stage, the service is executed. Similarly, when Content is added to an email or landing page, a new instance of that Content service is created.

2.1.1 Service Instantiation

1. A Marketer drags the service onto a campaign or program canvas or onto an email or landing page asset. This triggers a call from the Eloqua UI to an internal Eloqua API that will interact with your servers.

2. 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 a Decision service, the response might resemble:

{

"EmailAddress" : "{{Contact.Field(C_

EmailAddress)}}"

}

"recordDefinition":

{

"ContactID" : "{{Contact.Id}}",

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

3. 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.

4. 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

/fddc932a-f27d-40c3-a126-82299b9512c5

{

"recordDefinition":

{

"ContactID" : "{{Contact.Id}}",

"EmailAddress" : "{{Contact.Field(C_

EmailAddress)}}",

"field1" : "{{Contact.Field(C_field1)}}",

"field2" : "{{Contact.Field(C_field2)}}",

"field3" : "{{Contact.Field(C_field3)}}"

}

2.1.2 Execution

1. When the 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.

2. 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=fddc

932a-f27d-40c3-a126-82299b9512c5&asset=456

{

"offset" : 0,

"limit" : 1000,

"totalResults" : 2,

"count" : 2,

"hasMore" : false,

"items" :

[

{

"ContactID" : "1",

"EmailAddress" : "[email protected]",

"field1" : "stuff",

"field2" : "things",

"field3" : "et cetera"

}

]

{

"ContactID" : "2",

"EmailAddress" : "[email protected]",

"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.

3. 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.

4. 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 for more information

5. Eloqua receives the import. For service instances associated with a campaign, those contacts flow through to the next stage.

2.2 Notification URL Setup

Many AppCloud Services require that you configure a Notification URL when registering the service.

The Notification URL is essentially a webhook: it is the URL that Eloqua should call out to when something happens.

For example, when an Eloqua contact visits a landing page containing an AppCloud Content service instance, Eloqua calls out to the service provider's Notification URL to request the HTML content needed to populate the landing page. Similarly, when contacts flow into an AppCloud Decision or

AppCloud Action step during a campaign, Eloqua calls out to the Notification URL to notify the App that contacts have reached that step.

The Notification URL is a

templated URL

which supports the common parameters, including

{InstanceId} , {InstallId} , {AssetId} , {AssetName} , {UserName} , {UserId} , {EventType} , and

{UserCulture} . The AppCloud Content Service Notification URL also supports {VisitorId} , which maps to the ID of a visitor when called from a landing page, to enable delivery of visitor-specific content.

When the Notification URL is called for AppCloud Actions, Decisions, Feeders, or Content, Eloqua also sends, as parameters, the fields specified by your app during the Instantiation Phase. For example, AwesomeApp has an AppCloud Decision service. Its notification URL is: https://example.com/awesomeapp/decide/notify?instance={InstanceId}&asset={AssetId}

During Instantiation, ExampleApp specified that it requires the Contact Id, email address, field1, field2, and field3 in the

recordDefinition

field of the service instance data transfer object. The

recordDefinition

field was:

"recordDefinition": {

"contactID": "{{Contact.Id}}",

"email": "{{Contact.Field(C_EmailAddress)}}",

"field1": "{{Contact.Field(C_Field1)}}",

"field2": "{{Contact.Field(C_Field2)}}",

"field3": "{{Contact.Field(C_Field3)}}"

}

Suppose that two contacts, [email protected] and [email protected], flowed into an AppCloud

Decision step. Eloqua's 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",

"email" : "[email protected]",

"field1" : "stuff",

"field2" : "things",

"field3" : "et cetera"

]

}

{

"contactID" : "2",

"email" : "[email protected]",

"field1" : "more stuff",

"field2" : "other things",

"field3" : "and so on"

}

The appropriate response to the Notification URL call varies slightly depending on which service you're developing. You can see the appropriate responses for each service type in the following documents:

Develop an AppCloud action service

Develop an AppCloud decision service

Develop an AppCloud content service

Develop an AppCloud feeder service

Develop an AppCloud firehose service

2.3 Develop an Oracle Eloqua AppCloud Action Service

Actions are steps on a campaign or program canvas that are delegated to an external system. This allows you to perform actions that you cannot do with Eloqua. Actions are analogous to the existing

Cloud Connectors.

Actions follow

the instantiation-execution model . The following sections describe Action-specific

details and provide the endpoints needed to develop an Action 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.

2.3.1 Create URL

Eloqua’s call to the CreateURL:

POST https://example.com/awesomeapp/act/create?instance=f82d50cd-

86a9-4fca-b37e-4ec9a98b0339

{}

AwesomeApp’s response is a DTO describing the fields Eloqua should transmit when the service in executed. You can include a maximum of 249 fields in your record definition.

Example response for contacts:

{

}

"recordDefinition": {

"ContactID": "{{Contact.Id}}",

"EmailAddress": "{{Contact.Field(C_EmailAddress)}}"

"requiresConfiguration": true

Example response for custom objects:

{

}

"recordDefinition": {

"Email": "{{CustomObject[1].Field[4]}}"

"requiresConfiguration": true requiresConfiguration is an optional Boolean parameter which tells Eloqua whether user configuration is required before the app can be used. If set to true , users will be unable to activate a campaign or program containing the unconfigured app service instance. Eloqua will display an error message.

Warning: All field names and values in Eloqua data transfer objects are case sensitive. Be sure to reproduce them exactly. For example: {{Contact.id}} would fail if the correct form is

{{Contact.Id}} .

2.3.2 Configure URL

When a user clicks the edit button on the service instance and makes changes through the Configure

URL that require an updated recordDefinition data transfer object (DTO), AwesomeApp must call out to Eloqua’s Cloud API

PUT /actions/instances/{id}

endpoint with that updated DTO:

Example request for contacts:

PUT https://secure.p03.eloqua.com/api/cloud/1.0/actions/instances/ f82d50cd-86a9-4fca-b37e-4ec9a98b0339

{

"recordDefinition":

{

"ContactID" : "{{Contact.Id}}",

"EmailAddress" : "{{Contact.Field(C_

EmailAddress)}}",

"field1" : "{{Contact.Field(C_field1)}}",

"field2" : "{{Contact.Field(C_field2)}}",

"field3" : "{{Contact.Field(C_field3)}}"

"requiresConfiguration": false

}

Example request for custom objects:

PUT https://secure.p03.eloqua.com/api/cloud/1.0/actions/instances/ f82d50cd-86a9-4fca-b37e-4ec9a98b0339

{

"recordDefinition": {

}

"Email": "{{CustomObject[1].Field[4]}}"

"requiresConfiguration": false requiresConfiguration is an optional Boolean parameter which tells Eloqua whether user configuration is required before the app can be used. If set to true , users will be unable to activate a campaign or program containing the unconfigured app service instance. Eloqua will display an error message.

Use the Configure URL response to set requiresConfiguration to false when your app's configuration acceptance criteria have been met.

Warning: If the campaign or program is not in draft mode, attempting to set requiresConfiguration to true will result in an error.

2.3.3 Notification URL

Eloqua calls the Notification URL when contacts or custom objects arrive in the Action step. This call transmits the requested fields in the items parameter:

POST https://example.com/awesomeapp/act/notify?instance=f82d50cd-

86a9-4fca-b37e-4ec9a98b0339&asset=456

{

"offset" : 0,

"limit" : 1000,

"totalResults" : 2,

"count" : 2,

"hasMore" : false,

"items" :

[

{

"ContactID" : "1",

"EmailAddress" : "[email protected]",

"field1" : "stuff",

]

"field2" : "things",

"field3" : "et cetera"

{

"ContactID" : "2",

"EmailAddress" : "[email protected]",

"field1" : "more stuff",

"field2" : "other things",

"field3" : "and so on"

}

Your app must respond to this call, otherwise Eloqua will think the call has timed out.

Important: If AwesomeApp's Action service is configured to automatically set a contact or custom object record's status to "complete", contacts and custom object records will always move to the next step in the canvas. Eloqua will ignore the details of the response to the notification URL call, even if it is a 400- or 500-level error.

Each batch, delivered through a call to the Notification URL, of Contacts or Custom

Object Records in a step will only remain in the workflow for a maximum of 90 days.

Attempts to operate on them (i.e. set the status to "complete" or "errored”) after 90 days will fail, resulting in the records being stuck in the step, and requiring manual intervention to move them along in the flow. Each batch of records sent through a call to the

Notification URL has an ExecutionId, available as a

template parameter

, that identifies a unique batch.

If the Action service is not configured to automatically set the status to "complete", AwesomeApp should return a 204 response. This indicates that the response will be asynchronous. AwesomeApp should then create an import to Eloqua using the Bulk API where AwesomeApp specifies a sync action: either “complete” or “errored”.

Bulk API Contact Import

1. Create the bulk import definition, setting the status to "complete" to import data.

If there is no data to import, and you only need to update a record's status, you can update a record's status without performing an import by creating a contact sync action definition .

When importing, the "destination" field refers to the Action service's instance - in this example, the instance GUID is f82d50cd-86a9-4fca-b37e-4ec9a98b0339 :

Warning: When referencing service instances, you must transmit the GUID without dashes. The Bulk API will error if you transmit the GUID with the dashes.

POST https://secure.p03.eloqua.com/api/bulk/2.0/contacts/import s

{

"name" : "AwesomeApp Action Response Bulk Import",

"updateRule" : "always",

"fields" : {

"emailAddress" : "{{Contact.Field(C_EmailAddress)}}"

"syncActions" : [

{

"destination" : "{{ActionInstance

(f82d50cd86a94fcab37e4ec9a98b0339).Execution[12345]}}",

"action" : "setStatus",

"status" : " complete"

}

"identifierFieldName" : "emailAddress"

Eloqua’s response will be a 201 Created response that includes a uri parameter, which you can use to identify the import:

{

"name" : "AwesomeApp Action Response Bulk Import",

"updateRule" : "always",

"fields" : {

"emailAddress" : "{{Contact.Field(C_

EmailAddress)}}"

"identifierFieldName" : "emailAddress",

"syncActions" : [

{

"destination" : "{{ActionInstance

(f82d50cd86a94fcab37e4ec9a98b0339).Execution[12345]}}",

"action" : "setStatus",

"status" : "complete"

}

"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.p03.eloqua.com/api/bulk/2.0/contacts/i mports/6/data

[

{

"emailAddress" : "[email protected]"

}

]

3. Synchronize the data for import:

AwesomeApp’s request:

POST https://secure.p03.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"

}

4. You can then use the sync’s uri ( /syncs/6 ) to check the status of the sync:

GET https://secure.p03.eloqua.com/api/bulk/2.0/sync/6

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"

}

Learn more about Bulk API Imports .

Bulk API Custom Object Import

1. Create the bulk import definition, setting the status to "complete" to import data.

If there is no data to import, and you only need to update a record's status, you can update a record's status without performing an import by creating a custom object sync action definition .

When importing, the "destination" field refers to the Action service's instance - in this example, the instance GUID is f82d50cd-86a9-4fca-b37e-4ec9a98b0339 :

Warning: When referencing service instances, you must transmit the GUID without dashes. The Bulk API will error if you transmit the GUID with the dashes.

POST https://secure.p03.eloqua.com/api/bulk/2.0/customObjects/9

/imports

{

"name" : "AwesomeApp Action Response Bulk Import",

"updateRule" : "always",

"fields" : {

"email" : "{{CustomObject[9].Field[58]}}"

"syncActions" : [

{

"destination" : "{{ActionInstance

(f82d50cd86a94fcab37e4ec9a98b0339).Execution[12345]}}",

"action" : "setStatus",

"status" : " complete"

}

"identifierFieldName" : "email"

}

Eloqua’s response will be a 201 Created response that includes a uri parameter, which you can use to identify the import:

HTTP/1.1 201 Created

{

"name" : "AwesomeApp Action Response Bulk Import",

"updateRule" : "always",

"fields" : {

"email" : "{{CustomObject[9].Field[58]}}"

"identifierFieldName" : "email",

"syncActions" : [

{

"destination" : "{{ActionInstance

(f82d50cd86a94fcab37e4ec9a98b0339).Execution[12345]}}",

"action" : "setStatus",

"status" : "complete"

}

"isSyncTriggeredOnImport" : false,

"isUpdatingMultipleMatchedRecords" : false,

"uri" : " /customObjects/imports/9",

"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.p03.eloqua.com/api/bulk/2.0/customObje cts/imports/9/data

[

{

"email" : "[email protected]"

}

]

3. Synchronize the data for import:

AwesomeApp’s request:

POST https://secure.p03.eloqua.com/api/bulk/2.0/syncs

{

"syncedInstanceURI":"/customObjects/imports/9"

}

Eloqua’s Response:

201 Created

{

"syncedInstanceURI" : "/customObjects/imports/9",

"status" : "pending",

"createdAt" : "2014-01-01T13:59:07.1375620Z",

"createdBy" : "DocsExample",

"uri" : "/syncs/9"

}

4. You can then use the sync’s uri ( /syncs/9 ) to check the status of the sync:

GET https://secure.p03.eloqua.com/api/bulk/2.0/sync/9

When the sync is complete, Eloqua’s response will resemble:

200 OK

{

"syncedInstanceURI" : "/customObjects/imports/9",

"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/9"

}

Learn more about Bulk API Imports .

2.3.4 Delete URL

The delete URL is a templated URL pointing to an endpoint for deleting an instance of your service.

The delete URL uses an HTTP DELETE request and there is no content sent in the request body. All common URL template parameters are available (the same as with a create URL). On success, this endpoint should return a 200-level response.

An example delete URL would look something like: https://www.someurl.com/delete/{appId}/{installId}/

{instanceId}/{userName}/{siteName}/{siteId}

Note: Delete calls are not sent in real time, but are done in a batch once daily.

Learn more about Bulk API Imports .

2.4 Develop an Oracle Eloqua AppCloud Decision Service

Decisions are steps on a campaign or program canvas that directly control the path a contact or custom object takes as they flow through a canvas. Decision steps delegate the decision making to an external system, which responds with a "yes" or "no" for each object flowing through the canvas, determining which path the contact or custom object should take.

Decisions follow the

instantiation-execution model

. The following sections describe Decision-specific details and provide the endpoints needed to develop a 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.

2.4.1 Create URL

Eloqua’s call to the CreateURL:

POST https://example.com/awesomeapp/decide/create?instance=9347bfe

1-9c72-409c-a5cd-402ff74f0caa

{}

AwesomeApp’s response is a DTO describing the fields Eloqua should transmit when the service in executed. You can include a maximum of 249 fields in your record definition.

Example response for contacts:

{

}

"recordDefinition": {

"ContactID": "{{Contact.Id}}",

"EmailAddress": "{{Contact.Field(C_EmailAddress)}}"

"requiresConfiguration": true

Example response for custom objects:

{

}

"recordDefinition": {

"Email": "{{CustomObject[1].Field[4]}}"

Warning: All field names and values in Eloqua data transfer objects are case sensitive. Be sure to reproduce them exactly. For example: {{Contact.id}} would fail if the correct form is

{{Contact.Id}} .

2.4.2 Configure URL

When a user clicks the edit button on the service instance and makes changes through the Configure

URL that require an updated recordDefinition DTO, AwesomeApp must call out to Eloqua’s Cloud API

PUT /decisions/instances/{id}

endpoint with that updated DTO:

Example request for contacts:

PUT https://secure.p03.eloqua.com/api/cloud/1.0/decisions/instance s/9347bfe1-9c72-409c-a5cd-402ff74f0caa

{

"recordDefinition":

{

"ContactID" : "{{Contact.Id}}",

"EmailAddress" : "{{Contact.Field(C_

EmailAddress)}}",

"field1" : "{{Contact.Field(C_field1)}}",

"field2" : "{{Contact.Field(C_field2)}}",

"field3" : "{{Contact.Field(C_field3)}}"

"requiresConfiguration": false

}

Example request for custom objects:

PUT https://secure.p03.eloqua.com/api/cloud/1.0/decisions/instance s/9347bfe1-9c72-409c-a5cd-402ff74f0caa

{

"recordDefinition": {

}

"Email": "{{CustomObject[1].Field[4]}}"

Use the Configure URL response to set requiresConfiguration to false when your app's configuration acceptance criteria have been met.

Warning: If the campaign or program is not in draft mode, attempting to set requiresConfiguration to true will result in an error.

2.4.3 Notification URL

Eloqua’s call to the Notification URL transmits the requested fields in the items parameter:

POST https://example.com/awesomeapp/decide/notify?instance=9347bfe

1-9c72-409c-a5cd-402ff74f0caa&asset=456

{

"offset" : 0,

"limit" : 1000,

"totalResults" : 2,

"count" : 2,

"hasMore" : false,

"items" :

[

{

"ContactID" : "1",

"EmailAddress" : "[email protected]",

"field1" : "stuff",

"field2" : "things",

"field3" : "et cetera"

}

]

{

"ContactID" : "2",

"EmailAddress" : "[email protected]",

"field1" : "more stuff",

"field2" : "other things",

"field3" : "and so on"

}

Important: Each batch, delivered through a call to the Notification URL, of Contacts or Custom

Object Records in a step will only remain in the workflow for a maximum of 90 days. Attempts to operate on them (i.e. set the status to "complete" or "errored”) after 90 days will fail, resulting in the records being stuck in the step, and requiring manual intervention to move them along in the flow. Each batch of records sent through a call to the Notification URL has an ExecutionId, available as a

template parameter

, that identifies a unique batch.

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

Decisions, the sync action is either "yes", "no", or "errored". AwesomeApp will need to create multiple imports for the different statuses, with contacts or custom objects that should follow the "no" path in one import and then contacts and custom objects that should follow the "yes" path in another.

Note that the maximum import size per batch is 5,000: if you have more than 5,000 contacts or custom objects, break your data up into multiple imports.

Bulk API Contact Import

1. Create the bulk import definition, setting the status to "yes" to import data.

If there is no data to import, and you only need to update a record's status, you can update a record's status without performing an import by creating a contact sync action definition .

When importing, the "destination" field refers to the AppCloud Decision service's instance - in this example, the instance ID is 9347bfe1-9c72-409c-a5cd-402ff74f0caa :

Warning: When referencing service instances, you must transmit the GUID without dashes. The Bulk API will error if you transmit the GUID with the dashes.

POST https://secure.p03.eloqua.com/api/bulk/2.0/contacts/import s

{

"destination" : "{{DecisionInstance

(9347bfe19c72409ca5cd402ff74f0caa).Execution[12345]}}",

"action" : "setStatus",

"status" : " yes"

}

"identifierFieldName" : "emailAddress"

}

"name" : "AwesomeApp Decision Response Bulk Import",

"updateRule" : "always",

"fields" : {

"emailAddress" : "{{Contact.Field(C_EmailAddress)}}"

}

"syncActions" : [

{

Eloqua’s response will be a 201 Created response that includes a uri parameter, which you can use to identify the import:

{

"name": "AwesomeApp Decision Response Bulk Import",

"updateRule": "always",

"fields": {

"emailAddress": "{{Contact.Field(C_EmailAddress)}}"

"identifierFieldName": "emailAddress",

"syncActions": [

{

"destination": "{{DecisionInstance

(9347bfe19c72409ca5cd402ff74f0caa).Execution[12345]}}",

"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.p03.eloqua.com/api/bulk/2.0/contacts/i mports/6/data

[

{

"emailAddress" : "[email protected]"

{

"emailAddress" : "[email protected]"

}

]

3. Synchronize the data for import:

AwesomeApp’s request:

POST https://secure.p03.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"

}

4. You can then use the sync’s uri ( /syncs/6 ) to check the status of the sync:

GET https://secure.p03.eloqua.com/api/bulk/2.0/sync/6

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"

}

Bulk API Custom Object Import

1. Create the bulk import definition, setting the status to "yes" to import data.

If there is no data to import, and you only need to update a record's status, you can update a record's status without performing an import by creating a custom object sync action definition .

When importing, the "destination" field refers to the Decision service's instance - in this example, the instance GUID is f82d50cd-86a9-4fca-b37e-4ec9a98b0339 :

Warning: When referencing service instances, you must transmit the GUID without dashes. The Bulk API will error if you transmit the GUID with the dashes.

POST https://secure.p03.eloqua.com/api/bulk/2.0/customObjects/9

/imports

{

"name" : "AwesomeApp Decision Response Bulk Import",

"updateRule" : "always",

"fields" : {

"email" : "{{CustomObject[9].Field[58]}}"

"syncActions" : [

{

"destination" : "{{DecisionInstance

(f82d50cd86a94fcab37e4ec9a98b0339).Execution[12345]}}",

"action" : "setStatus",

"status" : " yes"

}

"identifierFieldName" : "email"

Eloqua’s response will be a 201 Created response that includes a uri parameter, which you can use to identify the import:

HTTP/1.1 201 Created

{

"name" : "AwesomeApp Decision Response Bulk

Import",

"updateRule" : "always",

"fields" : {

"email" : "{{CustomObject[9].Field[58]}}"

"identifierFieldName" : "email",

"syncActions" : [

{

"destination" : "{{DecisionInstance

(f82d50cd86a94fcab37e4ec9a98b0339).Execution[12345]}}",

"action" : "setStatus",

"status" : "yes"

}

"isSyncTriggeredOnImport" : false,

"isUpdatingMultipleMatchedRecords" : false,

"uri" : "

/customObjects/imports/9",

"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.p03.eloqua.com/api/bulk/2.0/customObje cts/imports/9/data

[

{

"email" : "[email protected]"

{

"email" : "[email protected]"

}

]

3. Synchronize the data for import:

AwesomeApp’s request:

POST https://secure.p03.eloqua.com/api/bulk/2.0/syncs

{

"syncedInstanceURI":"/customObjects/imports/9"

}

Eloqua’s Response:

201 Created

{

"syncedInstanceURI" : "/customObjects/imports/9",

"status" : "pending",

"createdAt" : "2014-01-01T13:59:07.1375620Z",

"createdBy" : "DocsExample",

"uri" : "/syncs/9"

}

4. You can then use the sync’s uri ( /syncs/9 ) to check the status of the sync:

GET https://secure.p03.eloqua/api/bulk/2.0/sync/9

When the sync is complete, Eloqua’s response will resemble:

200 OK

{

"syncedInstanceURI" : "/customObjects/imports/9",

"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/9"

}

Learn more about Bulk API Imports .

2.4.4 Delete URL

The delete URL is a templated URL pointing to an endpoint for deleting an instance of your service.

An example delete URL would look something like: https://www.someurl.com/delete/{appId}/{installId}/

{instanceId}/{userName}/{siteName}/{siteId}

Note: Delete calls are not sent in real time, but are done in a batch once daily.

2.5 Develop an Oracle Eloqua AppCloud Content Service

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.

Content follows the

instantiation-execution model .The following sections describe Content-specific

details and provide the endpoints needed to develop a 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.

2.5.1 Content Service Flow Diagrams

For Emails

For Landing Pages

2.5.2 Create URL

Eloqua’s call to the CreateURL:

POST https://example.com/awesomeapp/content/create?instance=f82d50c d-86a9-4fca-b37e-4ec9a98b0339

{}

For a Content service, AwesomeApp's response must include height , width , and default editorImageUrl , as well as the recordDefinition parameter. You can include a maximum of 250 fields in your record definition.

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",

"requiresConfiguration": true requiresConfiguration is an optional Boolean parameter which tells Eloqua whether user configuration is required before the app can be used. If set to true

, users will be unable to save an email or landing page asset containing the unconfigured app service instance. Eloqua will display an error message.

Warning: All field names and values in Eloqua data transfer objects are case sensitive. Be sure to reproduce them exactly. For example:

{{Contact.id}} would fail if the correct form is

{{Contact.Id}} .

2.5.3 Configure URL

When a user clicks the edit button on the service instance and makes changes through the Configure

URL that require an updated recordDefinition DTO, AwesomeApp must call out to Eloqua’s Cloud API

PUT /contents/instances/{id}

endpoint with that updated DTO:

PUT

https://secure.eloqua.com/api/cloud/1.0/contents/instances/f82 d50cd-86a9-4fca-b37e-4ec9a98b0339

{

"recordDefinition": {

"ContactID": "{{Contact.Id}}",

"EmailAddress": "{{Contact.Field(C_EmailAddress)}}",

"height": 256,

"width": 256,

"editorImageUrl": "https://example.com/image.png",

"requiresConfiguration": false

} requiresConfiguration is an optional Boolean parameter which tells Eloqua whether user configuration is required before the app can be used. If set to true

, users will be unable to save an email or landing page asset containing the unconfigured app service instance. Eloqua will display an error message.

Use the Configure URL response to set requiresConfiguration to false when your app's configuration acceptance criteria have been met.

Warning: If the email or landing page asset is not in draft mode, attempting to set requiresConfiguration to true will result in an error.

2.5.4 Notification URL

Eloqua’s call to the Notification URL transmits the requested fields in the items parameter:

POST https://example.com/awesomeapp/content/notify?instance=f82d50c d-86a9-4fca-b37e-4ec9a98b0339&asset=456

{

"offset": 0,

"limit": 1000,

"totalResults": 2,

"count": 2,

"hasMore": false,

"items":

[

]

{

"ContactID": "1",

"EmailAddress": "[email protected]"

"ContactID": "2",

"EmailAddress": "[email protected]"

}

For 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 Bulk

API.

Important: Emails deployments will fail if emails contain empty text or empty html content.

Inline Response

The inline response for landing pages and email is a 200 status code, followed by the text/html content.

For example:

{

<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 contactspecific content is updated with the ContactId and the instance Id, mapping the contact to the new html content.

Note: The maximum import size per batch is 5,000. If you have more than 5,000 contacts, break your data up into multiple imports.

1. Create the bulk import definition, including a Content parameter whose value is the service instance ID and execution ID. Including the execution ID enables you to differentiate between different uses of the asset, for example, when multiple campaigns use the same email template that contains the service instance:

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

(f82d50cd86a94fcab37e4ec9a98b0339).Execution[21]}}"

"identifierFieldName": "EmailAddress"

}

Eloqua’s response will be a 201 Created response that includes a uri parameter, which you can use to identify the import:

HTTP/1.1 201 Created

{

"name" : "AwesomeApp Content Response Bulk Import",

"updateRule" : "always",

"fields" : {

"EmailAddress" : "{{Contact.Field(C_

EmailAddress)}}",

"Content" : "{{ContentInstance

(f82d50cd86a94fcab37e4ec9a98b0339).Execution[21]}}"

"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"

}

2. Send Eloqua the data for import, using the Content parameter with the content the Eloqua should use for each contact:

POST https://secure.eloqua.com/api/bulk/2.0/contacts/imports/6/ data

[

]

{

"EmailAddress" : "[email protected]",

"Content" : "<p>This is the content for Sylvie</p>"

}

"EmailAddress" : "[email protected]",

"Content" : "<p>This is the content for Fred</p>"

3. Synchronize the data for import:

AwesomeApp’s request:

POST https://secure.p03.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"

}

4. You can then use the sync’s uri ( /syncs/6 ) to check the status of the sync:

GET https://secure.p03.eloqua.com/api/bulk/2.0/sync/6

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"

}

Note: If you want your content service hyperlinks to take advantage of Eloqua's dynamic link tracking features, it will not do so automatically. To enable Eloqua tracking for a link within your content service:

If the destination page has an Eloqua tracking script installed you should append s=<span class=eloquaemail>siteid</span>&elq=<span class=eloquaemail>recipientid</span> to the URL.

If the destination page does not have an Eloqua tracking script installed you should append elqtrack=true to the URL.

2.5.5 Delete URL

The delete URL is a templated URL pointing to an endpoint for deleting an instance of your service.

An example delete URL would look something like: https://www.someurl.com/delete/{appId}/{installId}/

{instanceId}/{userName}/{siteName}/{siteId}

Note: Delete calls are not sent in real time, but are done in a batch once daily.

2.6 Develop an Oracle Eloqua AppCloud Feeder Service

Feeders allow external systems to determine and control which contacts or custom objects enter into a campaign or program canvas, and when. Developers can now build apps that utilize data in thirdparty systems to drive campaign or program membership.

Feeders follows the

instantiation-execution model . The following sections describe Feeder-specific

details and provide the endpoints needed to develop a Feeder 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.

2.6.1 Create URL

Eloqua’s call to the CreateURL:

POST https://example.com/awesomeapp/feeders/create?siteid=123instan ce=9347bfe1-9c72-409c-a5cd-402ff74f0caa

{}

AwesomeApp’s response is a 200-level HTTP response:

HTTP/1.1 200 Ok

{

"requiresConfiguration": true

} requiresConfiguration is an optional Boolean parameter which tells Eloqua whether user configuration is required before the app can be used. If set to true , users will be unable to activate a campaign or program containing the unconfigured app service instance. Eloqua will display an error message.

2.6.2 Configure URL

When a user clicks the edit button on the service instance and makes changes through the Configure

URL, AwesomeApp must call out to Eloqua’s Cloud API

PUT /feeders/instances/{id}

endpoint:

PUT https://secure.eloqua.com/api/cloud/1.0/feeders/instances/93

47bfe1-9c72-409c-a5cd-402ff74f0caa

{

}

"requiresConfiguration": false

requiresConfiguration is an optional Boolean parameter which tells Eloqua whether user configuration is required before the app can be used. If set to true , users will be unable to activate a campaign or program containing the unconfigured app service instance. Eloqua will display an error message.

Use the Configure URL response to set requiresConfiguration to false when your app's configuration acceptance criteria have been met.

Warning: If the campaign or program is not in draft mode, attempting to set requiresConfiguration to true will result in an error.

2.6.3 Notification URL

Eloqua's call to the Campaign Status Notification URL tells AwesomeApp that the campaign or program is active and ready to receive contacts or custom object records. These calls are made using

templated URLs

to differentiate the call out. For example, the notification call for activating a campaign would resemble:

POST https://example.com/awesomeapp/feeders/notify?instance=9347bfe

1-9c72-409c-a5cd-402ff74f0caa&asset=456&status=Activated

When the campaign or program is deactivated, Eloqua's call to the Campaign Status Notification

URL tells AwesomeApp to stop sending contacts or custom object records. The deactivate notification would resemble:

POST https://example.com/awesomeapp/feeders/notify?instance=9347bfe

1-9c72-409c-a5cd-402ff74f0caa&asset=456&status=Draft

After the campaign or program is activated, 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 Feeders, the sync action sets the AppCloud

Feeder instance's status to complete. Note that the maximum import size per batch is 5,000: if you have more than 5,000 records, break your data up into multiple batches.

Bulk API Contact Import

1. Create the bulk import definition, setting the status of the AppCloud Feeder instance to complete. The "destination" field refers to the AppCloud Feeders service's instance - in this example, the instance ID is 9347bfe1-9c72-409c-a5cd-402ff74f0caa :

Warning: When referencing service instances, you must transmit the GUID without dashes. The Bulk API will error if you transmit the GUID with the dashes.

POST https://secure.p03.eloqua.com/api/bulk/2.0/contacts/imp orts

{

"name" : "AwesomeApp Feeder Bulk Import",

"updateRule" : "always",

"fields" : {

"emailAddress" : "{{Contact.Field(C_

EmailAddress)}}"

}

"syncActions" : [

{

"destination" : "{{FeederInstance

(9347bfe19c72409ca5cd402ff74f0caa)}}",

"action" : "setStatus",

"status" : "

complete"

}

"identifierFieldName" : "emailAddress"

Warning: All field names and values in Eloqua data transfer objects are case sensitive.

Be sure to reproduce them exactly. For example:

{{Contact.id}} would fail if the correct form is {{Contact.Id}} .

Eloqua’s response will be a 201 Created response that includes a uri parameter, which you can use to identify the import:

{

"name": "AwesomeApp Feeder Bulk Import",

"updateRule": "always",

"fields": {

"emailAddress": "{{Contact.Field(C_EmailAddress)}}"

"identifierFieldName": "emailAddress",

"syncActions": [

{

"destination": "{{FeederInstance

(9347bfe19c72409ca5cd402ff74f0caa)}}",

"action": "setStatus",

"status": "complete"

}

"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.p03.eloqua.com/api/bulk/2.0/contacts/i mports/6/data

[

{

"emailAddress" : "[email protected]"

}

]

3. Synchronize the data for import:

AwesomeApp’s request:

POST https://secure.p03.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"

}

4. You can then use the sync’s uri ( /syncs/6 ) to check the status of the sync:

GET https://secure.p03.eloqua.com/api/bulk/2.0/sync/6

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"

}

Bulk API Custom Object Import

1. Create the bulk import definition, setting the status to yes. The "destination" field refers to the

Feeder service's instance - in this example, the instance GUID is f82d50cd-86a9-4fca-b37e-

4ec9a98b0339 :

Warning: When referencing service instances, you must transmit the GUID without dashes. The Bulk API will error if you transmit the GUID with the dashes.

POST https://secure.p03.eloqua.com/api/bulk/2.0/customObjects/9

/imports

{

"name" : "AwesomeApp Feeder Response Bulk Import",

"updateRule" : "always",

"fields" : {

"email" : "{{CustomObject[9].Field[58]}}"

"syncActions" : [

{

"destination" : "{{FeederInstance

(f82d50cd86a94fcab37e4ec9a98b0339)}}",

"action" : "setStatus",

"status" : " complete"

}

"identifierFieldName" : "email"

}

Eloqua’s response will be a 201 Created response that includes a uri parameter, which you can use to identify the import:

HTTP/1.1 201 Created

{

"name" : "AwesomeApp Feeder Response Bulk Import",

"updateRule" : "always",

"fields" : {

"email" : "{{CustomObject[9].Field[58]}}"

"identifierFieldName" : "email",

"syncActions" : [

{

"destination" : "{{FeederInstance

(f82d50cd86a94fcab37e4ec9a98b0339)}}",

"action" : "setStatus",

"status" : "complete"

}

"isSyncTriggeredOnImport" : false,

"isUpdatingMultipleMatchedRecords" : false,

"uri" : " /customObjects/imports/9",

"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.p03.eloqua.com/api/bulk/2.0/customObje cts/imports/9/data

[

{

"email" : "[email protected]"

}

]

3. Synchronize the data for import:

AwesomeApp’s request:

POST https://secure.p03.eloqua.com/api/bulk/2.0/syncs

{

"syncedInstanceURI":"/customObjects/imports/9"

}

Eloqua’s Response:

201 Created

{

"syncedInstanceURI" : "/customObjects/imports/9",

"status" : "pending",

"createdAt" : "2014-01-01T13:59:07.1375620Z",

"createdBy" : "DocsExample",

"uri" : "/syncs/9"

}

4. You can then use the sync’s uri ( /syncs/9 ) to check the status of the sync:

GET https://secure.p03.eloqua.com/api/bulk/2.0/sync/9

When the sync is complete, Eloqua’s response will resemble:

200 OK

{

"syncedInstanceURI" : "/customObjects/imports/9",

"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/9"

}

Learn more about Bulk API Imports .

2.6.4 Delete URL

The delete URL is a templated URL pointing to an endpoint for deleting an instance of your service.

An example delete URL would look something like: https://www.someurl.com/delete/{appId}/{installId}/

{instanceId}/{userName}/{siteName}/{siteId}

Note: Delete calls are not sent in real time, but are done in a batch once daily.

2.7 Develop an Oracle Eloqua AppCloud Menu Service

The Menus service is all about Context. With Menus, you can build an App that enables a marketer to launch an externally-hosted application from within Eloqua via a menu dock. This menu dock floats on the right side of the screen in the Eloqua's Campaign Canvas or the asset editor screens. When a marketer clicks on your Menu App, Eloqua calls out to your service via the action URL, passing along context-specific data to your App.

Suppose AwesomeApp has a Menu service. When a marketing user clicks on AwesomeApp, they’re directed to the callout URL: https://example.com/awesome/callout

. The call can include contextual information for your app to use. Available attributes include: siteId and siteName : these describe the Eloqua "site", generally the company or organization of the user userId and userName

: the Eloqua username and id for the user who selected the Menu service userCulture : the linguistic profile of the user. Eloqua uses Microsoft’s CultureInfo class to define culture. For example, for English (United States), the code is en-US ; for French

(Canada), fr-CA assetId and assetName : the ID and name of the asset that the user was viewing when they opened the Menu assetType : the type of asset, that the user was viewing when they opened the Menu. Assets include “Account”, “Campaign”, “Contact”, “Landing Page”, “Template”, and so on.

The actual call to AwesomeApp would then resemble:

GET https://example.com/awesome/callout?siteId=123&siteName=Eloqua

&userId=1234&userName=Docs.Example&userCulture=en-

US&assetId=4&assetName=Docs%20Example%20Campaign&assetType=Cam paign

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.

2.8 Develop an Oracle Eloqua AppCloud Firehose Service

Eloqua’s Firehose service type enables third-parties to build a service that receives a notification when a marketer performs an action in Eloqua. When a marketer creates a campaign or edits an email, for example, Eloqua can call out to the third-party with the update.

Firehose supports subscriptions to a wide variety of events for the different asset types:

Email: Created, Updated, Deleted

LandingPage: Created, Updated, Deleted

ContactSegment: Created, Updated, Deleted

Form: Created, Updated, Deleted

Campaign: Created, Updated, Deleted, Draft, DraftApproved, DraftWaitingApproval,

ActivatedBySchedule, CampaignLandingPageAdded, CampaignEmailAdded,

CampaignFormAdded, CampaignLandingPageRemoved, CampaignEmailRemoved

Program: Created, Updated, Deleted, Draft, Activated, Paused

When you configure your App, you specify which events to subscribe to in the pattern. Then, when a marketer triggers one of those events, Eloqua calls out to the configured notification URL with the data specified in the Firehose pattern.

For example, AwesomeApp has a Firehose service and is configured to request all campaign-related events. The call to its notification URL would then resemble:

POST https://example.com/firehose

{

"siteId": "123",

"assetId": "9999",

"assetType": "Campaign",

"eventDate": "12/12/2014 12:00:01 AM",

"eventType": "Updated",

"userId": "1234",

"userName": "Docs.Example",

"msgAttributes": {

"name": "name_of_updated_asset",

"statuschangedby": "1234",

"statuschangedat": "12/12/2014 12:00:00 AM"

"oath_consumerkey": "stuff"

}

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.

Note: If a Firehose service is configured to receive form-related or segment-related events, App providers should expect to see two events whenever a form or segment is created or saved.

When a form is created, Eloqua sends a POST request (for the creation) and a PATCH request (for the update). App providers should expect to see two events in these scenarios.

3 Register Your App

When you have developed an app and are ready to start testing it, you need to register it with Eloqua.

By now, you will have already

registered as an App Provider

in your Eloqua development instance.

Now, you need to register your app and services.

Once registered, you can test your Apps within your instance to make sure they work as expected, and release the apps selectively or to the general public.

3.1 Step 1: Register the App

To register your app, select Settings > AppCloud Developer.

If you have not yet registered any Apps, you will see a “You currently have no apps” message, and the

Create App button.

If you have already registered an App, it will be listed alongside the Create App button. To register your App, click Create App.

3.1.1 App information

The

Create App

screen prompts you to fill in a number of fields that describe your App. Complete these fields with the relevant information. Current fields include Name, Description, and Icon.

Warning: the Name field is limited to 100 characters and the Description field is limited to

4000 characters.

3.1.2 Lifecycle fields

Enable URL:The URL called when the App is first installed or when it is reconfigured. This is a templated URL which should include, at a minimum, the {

InstallId

} ,

{ AppId

} , and

{ CallbackUrl

} parameters. WIthout the callback URL you will not be able to complete the installation flow if your app requires configuring (for example, to use OAuth).

Configure URL: The URL called when the app is configured.

Status URL:The URL called when a user checks the App’s connection.

Learn how to respond when Eloqua calls the Status URL

Uninstall URL: The URL called when a user uninstalls the app. This allows Eloqua to notify the app provider when someone uninstalls their app from the appcloud catalog. This URL supports templated parameters such as

{ InstallId

} ,

{ AppId

} , etc.

3.1.3 Authentication to Eloqua

Apps for the AppCloud use OAuth for authentication.

OAuth Callback URL: the URL that the users should be redirected to after installing the app and authenticating with Eloqua.

To use OAuth, you'll need the following information which is displayed after you click Save:

Client ID (App id): Eloqua creates and assigns the App ID when you save your App.

Client Secret: Eloqua generates the secret access token when you save your App. Click Show to view it.

When you’ve filled in all fields, click Save to finish configuring the app, or click Add Services to start registering services.

3.2 Step 2: Register Services

Finally, you should register any service your app uses. The AppCloud Developer Platform currently supports 6 services: Menus, Firehose, Content, Actions, Decisions, and Feeders.

Apps can include zero services, as in the case of a portal app or if the integration not directly tied to one of the service types, or if it's tied to many services.

To define your app's services within Eloqua, navigate to Settings > AppCloud Developer then click on your app (see step 1 above for setup instructions) and select Add Services.

A modal opens listing the available service types. Select the service type you wish to register.

Then, fill out the service’s details: you will have different information you need to supply depending on the service you are implementing. For example, for a Menu, you need to provide the Action URL, specify the areas it supports and how Eloqua should present it, and provide the service’s icon URL, name, and description; for Content, you will need to fill out instance configuration details, as well as configure content and notification settings, as well as the general service details. The following documents describe the service configuration page for each service type:

When you are done configuring your service, click Save. A green alert message will appear at the top of the page indicating the Service has been successfully saved.

3.3 Step 3: View the App

You can view the App information by clicking its name in the list. Here is an example of the App Details page for

Docs Example App

The App page shows all of the App information, including

Services

. When you register an App, it immediately becomes available in your instance of Eloqua so you can test it before releasing it to any other prospective users. When you’re ready to release your App, or just to share it with a select few, check out the

App publishing tutorial

3.4 Register an Action Service

With Actions, developers can build apps that control an external action that occurs when contacts enter a step on the campaign canvas. Examples of this could include sending contacts SMS messages, a direct mail piece, or registering them for webinars. When contacts enter an action step,

Eloqua will call out to the app, and the app can respond by performing an action in an external system, then informing Eloqua that the process is complete. The contact will then move on in the workflow.

Actions are the next generation of Eloqua’s popular Cloud Connectors framework.

When you set up an Action service, you will need to provide the usual Oracle Eloqua AppCloud

Developer framework service details, as well as the Instance Configuration and Action Settings.

3.4.1 Service Details

These fields are present for all services:

Name: the name of the service. Max length: 100 characters.

Description: describes what the service does. Max length: 4000 characters.

16x16px Icon: the URL of the icon Eloqua displays when your service is displayed on a canvas. The icon will be 16px by 16px when displayed. It must be a secure URL. See

App Icon

Design Guidelines

for more information on designing app icons.

32x32px Icon: the URL of the icon that Eloqua should display for your service. The icon will be

32px by 32px when displayed. It must be a secure URL. See

App Icon Design Guidelines

for more information on designing app icons.

3.4.2 Instance Configuration

This section defines the URLs for creating, configuring, copying, and deleting an instance of your service. The installation tutorial details the instance creation flow when a marketer drags an Action step onto the canvas, and selects your app.

Each URL is a

templated URL

that uses common URL template parameters and some Eloqua Markup

Language parameters. Eloqua replaces these paramters with their appropriate values when it makes a call. For more about URL templating, see our

Create URL: A templated URL pointing to a web portal for creating an instance of this service as an HTTP POST request. All common URL template parameters are available.

You should be sure to include, at a minimum, the

} parameter so that you will be able to identify the service in the future. On success, this endpoint should return a 200-level response with the created instance.

Configure URL: A templated URL pointing to an endpoint for configuring an instance of this service as an HTTP GET request. All common URL template parameters are available.

You should be sure to include, at a minimum, the

} parameter so that you will be able to identify the service in the future.

Modal size configuration window: Select a modal size for your configuration window. The configuration page displays when marketers configure your service.

Large: 950px x 550px

Small: 650px x 550px

Delete URL: A templated URL pointing to an endpoint for deleting an instance of this service using an HTTP DELETE request. All common URL template parameters are available. On success, this endpoint should return a 200-level response.

Copy URL: A templated URL pointing to an endpoint for creating an instance of this service as an HTTP POST request. All common URL template parameters are available in addition to

} ,

} , and

} .

You should be sure to include, at a minimum, the

} and

parameters so that you can identify the original and newly created instances. On success, this endpoint should return a 200-level response with the created instance. Learn how to

complete so they will flow into the next step. See: Develop an Action Service

3.4.3 Service Settings

User Access: Specify if your service supports campaign contacts, program contacts, and/or program custom objects.

Step Response: Specify whether Eloqua should call out to your service when a member arrives in an Action Step, or whether you will poll for members periodically.

Notification URL: This url will be called (HTTP POST) when actions are taken on an instance of this service. This endpoint should return a 2xx level response with an empty body on success. If this property is not specified, the system will fall back to a polling style approach without notification. Note that this url can be used along with the recordDefinition property of the instance to send data.

Records per Notification: Max number of records to push per HTTP request (between 0 and

5,000)

Status on Notification: Specifies what the member’s status should be set to when a notification is set. This is only valid if Max Records per Notification is greater than 0. If you set the Status on Notification to Complete, Eloqua will call out to the notification URL when contacts flow into the action step, and will then push the contacts directly into the next step. If you set it to Active, you will need to call back into Eloqua to set each contact's status to

for more information.

When you’re done configuring your service, click Save. A green alert message will appear at the top of the page indicating the service has been successfully saved.

3.5 Register a Decision Service

With Decisions, developers can build apps that directly control the path a contact takes as they flow through a campaign. For instance, you could build an App that Eloqua calls out to when contacts reach a Decision step. This App might interact with an external system, and evaluate rules against that set of external data. The App then responds, telling Eloqua whether the contacts should flow through the step’s “yes” or “no” path. With Decisions, the data used in the decision never needs to be brought into

Eloqua.

When you set up a Decision service, you will need to provide the usual AppCloud Developer framework service details, as well as the Instance Configuration, Content-Type of the notification

POST call and Decision Settings.

3.5.1 Service Details

These fields are present for all services:

Name: the name of the service. Max length: 100 characters.

Description: describes what the service does. Max length: 4000 characters.

16x16px Icon: the URL of the icon Eloqua displays when your service is displayed on a canvas. The icon will be 16px by 16px when displayed. It must be a secure URL. See

App Icon

Design Guidelines

for more information on designing app icons.

32x32px Icon: the URL of the icon that Eloqua should display for your service. The icon will be

32px by 32px when displayed. It must be a secure URL. See

App Icon Design Guidelines

for more information on designing app icons.

3.5.2 Instance Configuration

Each URL is a

templated URL

that uses common URL template parameters and some Eloqua Markup

Language parameters. Eloqua replaces these paramters with their appropriate values when it makes a call. For more about URL templating, see our

Create URL: A templated URL pointing to a web portal for creating an instance of this service as an HTTP POST request. All common URL template parameters are available.

You should be sure to include, at a minimum, the

} parameter so that you will be able to identify the service in the future. On success, this endpoint should return a 200-level response with the created instance.

Configure URL: A templated URL pointing to an endpoint for configuring an instance of this service as an HTTP GET request. All common URL template parameters are available.

You should be sure to include, at a minimum, the

} parameter so that you will be able to identify the service in the future.

Modal size configuration window: Select a modal size for your configuration window. The configuration page displays when marketers configure your service.

Large: 950px x 550px

Small: 650px x 550px

Copy URL: A templated URL pointing to an endpoint for creating an instance of this service as an HTTP POST request. All common URL template parameters are available in addition to

} ,

} , and

} .

You should be sure to include, at a minimum, the

} and

parameters so that you can identify the original and newly created instances. On success, this endpoint should return a 200-level response with the created instance. Learn how to

3.5.3 Service Settings

User Access: Select the Eloqua services for which your app should be available.

Step Response: Specify whether Eloqua should call out to your service when a member arrives in the decision step, or whether your application will poll for members periodically.

Notification URL: A templated URL to an endpoint for notifying the external service, during execution, to get the decision result of the configured instance. If this property is not specified,

the system will fall back to a polling style approach without any notification.

Records per Notification: max number of records to push per HTTP request (between 0 and

5,000).

When you’re done configuring your service, click Save. A green alert message will appear at the top of the page indicating the service has been successfully saved.

3.6 Register a Content Service

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. For instance, you can now re-size content in real time!

When you set up a Content service, you will need to provide the usual AppCloud Developer framework service details, as well as the Instance Configuration and Content Settings.

3.6.1 Service Details

These fields are present for all services:

Name: the name of the service

Description: describes what the service does

32x32px Icon: the URL of the icon that Eloqua should display for your service. The URL must be https://

3.6.2 Instance Configuration

This section defines the URLs for creating, configuring, copying and deleting an instance of your service. The installation tutorial details the instance creation flow when a creates a Landing Page or

Email populated with Content.

Each URL is a

templated URL

that uses common URL template parameters and some Eloqua Markup

Language parameters. Eloqua replaces these paramters with their appropriate values when it makes a call. For more about URL templating, see our

Create URL: A templated URL pointing to a web portal for creating an instance of this service as an HTTP POST request. All common URL template parameters are available.

You should be sure to include, at a minimum, the

} parameter so that you will be able to identify the service in the future. On success, this endpoint should return a 200-level response with the created instance.

Configure URL: A templated URL pointing to an endpoint for configuring an instance of this service as an HTTP GET request. All common URL template parameters are available.

You should be sure to include, at a minimum, the

} parameter so that you will be able to identify the service in the future.

Modal size configuration window: Select a modal size for your configuration window. The configuration page displays when marketers configure your service.

Large: 950px x 550px

Small: 650px x 550px

Delete URL: A templated URL pointing to an endpoint for deleting an instance of this service using an HTTP DELETE request. All common URL template parameters are available. On

success, this endpoint should return a 200-level response.

Copy URL: A templated URL pointing to an endpoint for creating an instance of this service as an HTTP POST request. All common URL template parameters are available in addition to

} ,

} , and

} .

You should be sure to include, at a minimum, the

} and

parameters so that you can identify the original and newly created instances. On success, this endpoint should return a 200-level response with the created instance. Learn how to

3.6.3 Service Settings

User Access: Select the Eloqua asset types for which your app should be available.

Landing Page Notification (HTML) URL: templated URL that Landing Page engines should call out to during render to retrieve the HTML content for the configured instance.

In addition to the common HTML template parameters, the Notification (HTML) URL supports the

{

VisitorId }

{Fragment}

{Host}

{Query} and

{Url} parameters. Be sure to include, at a minimum, the the

App Icon Design Guidelines

} and

{ ExecutionId }

parameters so that you will be able to call back in to Eloqua.

Email Notification (HTML) URL: templated URL that the Email engine should call out to during render to retrieve the HTML content for the configured instance. Be sure to include, at a minimum, the the

{ InstanceId }

and

{ ExecutionId }

parameters so that you will be able to call back in to Eloqua.

Max Records per Notification: max number of records to push per HTTP request (between 0 and 5,000)

3.6.4 Content Settings

Default Content: the HTML content the system should use if the external service is not accessible. This is a required field and cannot be empty.

Content Layout: choose from flow or fixed. If you choose flow, the external content is input into your landing page or email with no constraints (except width). If you choose fixed, the external content will be constrained in height and width, as specified by the content instance, and will not be configurable from within Eloqua.

If the landing page or email notification URL is not specified and a Landing Page or Email rendering is required, the default content is used instead.

When you’re done configuring your service, click Save. A green alert message will appear at the top of the page indicating the service has been successfully saved.

3.7 Register a Feeder Service

With Feeders, developers can build apps that use data in third-party services to drive campaign membership. When you set up a Feeder service, you will need to provide the usual AppCloud

Developer framework service details, as well as the Instance Configuration and Feeder Settings.

3.7.1 Service Details

These fields are present for all services:

Name: the name of the service. Max length: 100 characters.

Description: describes what the service does. Max length: 4000 characters.

16x16px Icon: the URL of the icon Eloqua displays when your service is displayed on a canvas. The icon will be 16px by 16px when displayed. It must be a secure URL. See

App Icon

Design Guidelines

for more information on designing app icons.

32x32px Icon: the URL of the icon that Eloqua should display for your service. The icon will be

32px by 32px when displayed. It must be a secure URL. See

for more information on designing app icons.

3.7.2 Instance Configuration

Each URL is a

templated URL

that uses common URL template parameters and some Eloqua Markup

Language parameters. Eloqua replaces these paramters with their appropriate values when it makes a call. For more about URL templating, see our

Create URL: A templated URL pointing to a web portal for creating an instance of this service as an HTTP POST request. All common URL template parameters are available.

You should be sure to include, at a minimum, the

} parameter so that you will be able to identify the service in the future. On success, this endpoint should return a 200-level response with the created instance.

Configure URL: A templated URL pointing to an endpoint for configuring an instance of this service as an HTTP GET request. All common URL template parameters are available.

You should be sure to include, at a minimum, the

} parameter so that you will be able to identify the service in the future.

Modal size configuration window: Select a modal size for your configuration window. The configuration page displays when marketers configure your service.

Large: 950px x 550px

Small: 650px x 550px

Delete URL: A templated URL pointing to an endpoint for deleting an instance of this service using an HTTP

DELETE request. All common URL template parameters are available. On success, this endpoint should return a 200-level response.

Copy URL: A templated URL pointing to an endpoint for creating an instance of this service as an HTTP POST request. All common URL template parameters are available in addition to

} ,

} , and

} .

You should be sure to include, at a minimum, the

} and

parameters so that you can identify the original and newly created instances. On success, this endpoint should return a 200-level response with the created instance. Learn how to

3.7.3 Feeder Settings

User Access: Select the Eloqua services for which your app will be available.

Notification URL: This URL is called (HTTP POST ) when a campaign containing an instance of the service’s status changes, such as when it is activated.

Be sure to include the

AppCloud Installation Flow

} and

{ EventType

} parameters in the templated URL.

AssetId describes the campaign whose status has changed, and EventType defines the status. When a campaign is activated, for example EventType will be “Active”. Otherwise, you will not be able to identify what the incoming call references.

When you’re done configuring your service, click Save. A green alert message will appear at the top of the page indicating the service has been successfully saved.

3.8 Register a Menu Service

Eloqua’s Menus service is all about

context

. With Menus, you can build an App that enables a marketer to launch an externally-hosted application from within Eloqua via a menu dock. This menu dock floats on the right side of the screen in the Eloqua’s Campaign Canvas or the asset editor screens. When a marketer clicks on your Menu App, Eloqua calls out to your service on the specified endpoint URL, passing along information about the asset or area from which your App was launched.

When setting up a Menu service, you will need to provide basic service details, as well as the Menu

Extension Service Details.

3.8.1 Service Details

These fields are present for all services:

Name: the name of the service

Description: describes what the service does

32x32px Icon: the URL of the icon that Eloqua should display for your service. The URL must be https://

3.8.2 Service Settings

Action URL: A templated URL that defines where users are redirected to when they select the menu item. For example, a new tab with an external page showing information on a Campaign.

User Access: Select the assets/areas within Eloqua that your app will appear to the Marketer.

Default View: Specify how your service will appear.

Always visible: Display the menu service in two areas: within the selected area of the interface and within the editor for the asset.

Example: If this option is selected along with

Campaign

access, a user will see the menu service when they navigate to Orchestration > Campaigns, and when they open a campaign.

Only visible for a selected asset: Display the menu service only for the selected assets under User Access.

Example: If this option is selected along with

Campaign

access, a user will only see the menu service when they open a campaign.

Content Display Layout: Select a layout option for your content display.

Drawer: Content will open within the AppCloud Menu dock.

Window: Content will open in a new window or tab.

When you’re done configuring your service, click Save. A green alert message will appear at the top of the page indicating the service has been successfully saved.

3.9 Register a Firehose Service

Firehose enables third-parties to build a service that receives a notification when a marketer performs an action in Eloqua. This is essentially a web-hook that will be triggered when a marketer does things like creating or editing a campaign, or creating or updating an email etc.

3.9.1 Service Details

These fields are present for all services:

Name: the name of the service

Description: describes what the service does

32x32px Icon: the URL of the icon that Eloqua should display for your service. The URL must be https://

3.9.2 Firehose Settings

Notification URL: the URL that Eloqua will call out to with the notification. This is a templated

URL.

Subscribed Events: defines which events trigger a call out to the external application. The service configuration page includes a list of valid asset types and the event types supported for each asset, as well as examples of valid patterns.

When you’re done configuring your service, click Save. A green alert message will appear at the top of the page indicating the service has been successfully saved.

4 Publish Your App

The final step in the App configuration lifecycle is publishing your App. The publishing flow has two components: whitelisting users so that they are permitted to install the App, and retrieving the link that those users need in order to add the App to their catalog.

4.1 Grant Access

By default, when you register an App with Eloqua, only your instance of Eloqua has access to it. This makes it easy for you to test your App to ensure it is behaving as expected.

To allow other people access to the App, you have to grant access from the App Configuration page, by clicking Edit Availability in the Availability section.

You can choose between granting access to all Eloqua instances, or select Eloqua instances.

4.1.1 Publish to All Sites

If your app is available to all Eloqua instances, all sites are immediately whitelisted. At present, this cannot be undone. Nevertheless, a Customer Admin will need the install URL before they can actually install the App.

4.1.2 Publish To A Specific Site

To make your app available to specific Eloqua instances, enter the name of the site you want to add and click Add Client. All Eloqua Instances with that site name will now be able to install the App.

Note: You cannot remove a Site from your app's whitelist if that Site has your app installed. To remove a Site from your app's whitelist, you must first contact the appropriate client and have them uninstall your app. This a security measure in place to prevent broken assets and campaigns.

4.2 Share the URL

Having published your App, giving sites the ability to install it, you now need to share the URL so that users can add the App to their Eloqua instance’s App Catalog, giving marketers the ability to use it.

Eloqua automatically creates the installation URL when you register your App.

Many developers send the link by email to the Sites they have authorized. When an authorized user clicks the link, the App is added to their catalog. The link will not work for users who are not authorized, so you don’t need to worry about people passing around the installation link to sites you did not whitelist.

The number of sites which have installed your app is listed in the App details page.

Click Logs to see catalog install details.

4.3 Next Steps

When a customer admin installs an app on a new site, Eloqua calls out to the App's install URL. Refer to the

tutorial for more information.

4.4 AppCloud Installation Flow

When a Customer Admin installs an app, Eloqua calls out to the configured enable URL with a POST request. The call will resemble the following: https://example.com/awesomeapp/api/enable?enableurl&oauth_ consumerkey=XXX-XXX-XXX-XXX-XXX

&oauth_nonce=nonce&oauth_signature_method=SIG-METH&oauth_ timestamp=111111111

&oauth_version=1.0&oauth_ signature=signature&callback=https%3A%2F%2Fsecure.eloqua.com%2

FApps%2FCloud%2FAdmin%2FInstall%2FCallback%2Fa1b2c3d4%3Fguid%3

Dz9y8x7w6

The app must respond in one of two ways: if the app does not require configuring by the user, it can return an HTTP 200 OK response. Otherwise, it should respond with an HTTP 302 redirect to another page. The following sections detail each option.

4.4.1 No Additional Information Needed

In this scenario, there is no need to obtain OAuth authorization for the installing user's instance, nor any other configuration information. The appropriate response is then:

HTTP/1.1 200 OK

The app install status will be set to the "Ready" and marketers will be able to use it.

4.4.2 Additional Information Needed

If you need to have the user configure the application or provide OAuth authorization for their instance, you should respond with an HTTP 302 redirect to another page. When the app is configured, you need to call back in to the callback URL.

1. Respond with a redirect:

HTTP/1.1 302 Redirect

If your app needed to go through the OAuth flow, the redirect might point to login.eloqua.com/auth/oauth2/authorize , Eloqua’s OAuth endpoint. If you needed users to configure options in the app when they install it, the redirect might point to a configure page within your app.

2. Call in to the callback URL when the user has finished configuring the application. Using the above example, the call would look like: https://secure.eloqua.com/Apps/Cloud/Admin/Install/Callbac k/a1b2c3d4?guid=z9y8x7w6

Eloqua provides the callback URL when you request it as a template in your templated enable URL. Calling the callback URL tells Eloqua that the install status should be set to

"Ready" so that marketers can start using the application.

3. When the app provider calls back in to complete the installation, it can optionally append a

redirect URL: https://secure.eloqua.com/Apps/Cloud/Admin/Install/Callbac k/{installId}?guid={guid}&redirect={redirectUrl}

Replace parameters in {} with desired values, and the redirect URL must be in HTTP or HTTPS.

The redirect URL supports

templated URL parameters

. You must URL encode the redirect URL to ensure that template parameters are returned back to you. If no redirect URL is given, or if the redirect URL given is not acceptable, then the user is redirected to Eloqua’s catalog.

4.5 Respond When Eloqua Calls the Status URL

When you register an App in Eloqua, you are able to specify a Status URL. This URL is an endpoint which Eloqua can call to verify that your app is up and running.

Eloqua calls the Status URL when a user clicks the Check Connection button for that App from the

AppCloud Catalog.

Important: Applications have an “application status” associated with them. This status is either

“up”, “down”, or “maintenance”. Calls to the Status URL do not update the application status: they merely display the application’s response to the user who clicked the “Status” button.

4.5.1 Example

Suppose the user clicked the Check Connection button for AwesomeApp. The call resembles:

GET https://example.com/awesomeapp/status

If AwesomeApp is operating normally, the appropriate response is an 200-level response:

HTTP/1.1 200 OK

Eloqua then displays the Status to the user in a modal window.

Otherwise, if AwesomeApp is down and responds with a 400 or 500-level message, Eloqua indicates that it was unable to connect to the application. Or that the application is in

maintenance mode

4.6 Respond When a Marketer Copies a Service Instance

Marketers often create new campaigns, landing pages, and emails from existing resources. When a marketer creates a campaign, landing page, or email using the Save As option in the Campaign

Canvas and Landing Page or Email editors all of the objects in that resource are duplicated. For most items on a canvas, this is straightforward. For services that follow the

instantiation-execution model

, however, each instance has its own unique identifier. Thus, when an Action, Decision, Feeder, or

Content service instance is copied, a new GUID needs to be assigned to the copy. The Oracle Eloqua

AppCloud Developer Framework uses the Copy URL to communicate with the service’s provider to configure and update the new service instance when a service is copied.

4.6.1 Sample Copy URL Call and Response

Eloqua’s call to the Copy URL is similar to the call to the CreateURL when a service is first created.

The following section provides step-by-step instructions for properly handling calls to the Copy URL.

This example uses a Decision service, but the process is the same for Actions, Content, and Feeders.

1. A marketing user copies a campaign that includes an AwesomeApp Decision Service whose templated Copy URL is: example.com/awesomeapp/decide/copy?instanceId=

{InstanceId}&originalId={OriginalInstanceId}

2. Eloqua calls out to the Copy URL, replacing the templated parameters with the original service’s GUID, and the new GUID of the copy. AwesomeApp can use the original service’s

GUID to determine the appropriate configuration options for the copy:

POST example.com/awesomeapp/decide/copy?instanceId=bcbdff6a-

74dd-41c9-b716-825e4049b776

&originalId=d155213e-cd30-422b-984c-acb33093cb5b

3. AwesomeApp responds in one of two ways: either it replies with an HTTP 200 Ok response, and no content, in which case Eloqua will use the original service’s configuration for the new service, or, AwesomeApp replies with a 200-level HTTP response along with a DTO specifying how the new service should be configured, as in the following:

HTTP/1.1 200 OK

{

"recordDefinition":

{

"ContactId": "{{Contact.Id}}",

"EmailAddress": "{{Contact.Field(C_

EmailAddress)}}"

}

Internally, Eloqua then updates the references in the campaign to the new service instance

GUID, and the new campaign is created.

4.6.2 Persistent Settings and Data

As an App provider, you have control over what data and settings are persisted when a service is copied: if you wish to retain the configuration of the original service, simply return a blank DTO when

Eloqua calls out to the Copy URL. Conversely, if you wish to update the configuration of the new service, you can do so by replying with a new DTO.

Once a service has been copied, and the new service has been configured, there is

no link

between the original and new services: changing the configuration in one does not affect the other.

4.7 Scheduled Maintenance

If you need to perform maintenance on your app, and wish to put it into maintenance mode, you can do so directly from the app's App Details page from within your Eloqua instance by clicking the Stop App button.

When an app is in maintenance mode,

Eloqua will not send any calls to the app

Marketers should not be able to add the app's services to a campaign, email, or landing page

When a user

checks the app's status , Eloqua will inidcate the app is undergoing maintenance

App Shutdown is not equivalent to deactivating or deleting an app. It is, however, ideal if you wish to suspend the app while performing an upgrade.

4.8 App Shutdown

If your app is not operating properly, Oracle Eloqua can shut down your app. This prevents marketers from creating new campaigns that use your app's services. Marketers can also configure a default path for contacts to follow in the event that a service is unavailable while a campaign is in progress.

See: Configuring Cloud Action and Decision Elements in the Eloqua product documentation for more information. When an app is shutdown, any contacts in the app's service's steps will flow down the default path, if it is configured.

4.8.1 Shutdown

Eloqua will shut down your app if there were more than 100 calls in the last five minutes, and 25% of them failed. Eloqua will automatically send an email message to the

email address associated with your provider , with a link you can use to reactivate your app. When the app is shut down, all pending

and future requests are marked as "failed".

4.8.2 Reactivate Your App

To reactivate your app, simply click on the link in the notification email that Eloqua has sent.

Alternately, you can log into your development instance, and click the Start App button on the App

Details page in the AppCloud Developer Framework area of Eloqua.

You can also programatically start or stop your app using the

GET /apps/{appid}/configurations

and

PUT /apps/{appid}/configurations

endpoints. See:

Programmatically Update your App's

Status

for more information.

4.9 App Icon Design Guidelines

When designing your app's icon, it's important to follow the recommended design guidelines to ensure your app icon displays correctly for your users. Each app requires:

AppCloud Catalog icon

App specific icon (the size requirement depends on where the App appears in the Eloqua interface)

Content

Firehose

Canvas

Each app has different size guidelines and will appear in different areas of the Eloqua interface:

AppCloud Catalog icons

Size requirement:

96x96px

An icon to represent your App will be displayed in the AppCloud Catalog and on the App Details page.

4.9.1 Menu apps

Size requirement:

96x96px

Menu apps are accessed from the Cloud menu tab, located at the top right of the screen. These apps should be context specific.

The Menu app icon appears within the Cloud menu tab and in AppCloud catalog.

4.9.2 Content apps

Size requirement:

96x96px

Content apps are accessible from the Cloud Content popup in the Email and Landing Page editors. The content apps icon appears on this popup and in the AppCloud catalog.

4.9.3 Firehose apps

Size requirement:

96x96px

Firehose apps only require an icon in the AppCloud catalog.

4.9.4 Canvas apps (Action, Decision, and Feeder services)

Size requirement:

32x32px

16x16px

Canvas apps are accessible from the Campaign Canvas and the Program Canvas left Canvas Palette.

Two icons are needed for Canvas apps:

The 32x32px icon appears in the left campaign/program step on the canvas

The 16x16px icon appears in the left canvas palette

Recommendation:

White icon with transparent background

Important: Because color is used to differentiate between Audience (green), Decision (red) and

Action (purple) steps and unpopulated state steps (grey), it is strongly recommended that App

Providers use white icons with transparent backgrounds for Canvas Apps.

Migrating existing apps to the new interface

In the new interface, your existing apps will be modified accordingly:

Menu apps: Unchanged, but scale in size.

Content apps: Unchanged, but scale in size.

Firehose apps: Unchanged, but scale in size.

Canvas apps: The dotted line shows placement of the icon within the step:

Left palette:

4.10 Viewing an App's Outbound Logs

The logs page records all the outbound requests made from Eloqua to your app's

lifecycle URLs

(the

URLs an app calls when the app is configured, uninstalled, and so on). The records in the outbound log are useful for determining if Eloqua is calling your app's lifecycle URLs successfully.

Example: You can review the logs to determine if Eloqua is successfully calling the

Enable

URL

by searching the logs page for the URL and viewing the response body to ensure a 200

level response code is returned.

If Eloqua fails to call a URL, a 400 level response code is returned.

The logs page only displays outbound requests for your instance and other clients on your pod, to pull logs from another pod, use the

app logs endpoint .

To view an app's outbound logs:

1. Navigate to Settings > AppCloud Developer.

2. Select your app and click Logs.

Expand the chevron to see the request and response body for the requests made to the lifecycle URLs.

Click Log Details to view details about the request.

The Log Details display how long the request took to execute, as well as the full request and response body.

4.11 Update or Check your App's Status Using the Cloud API

From time to time, you may wish to update your App's status. While it is possible to start or stop your app from the App Details page in the AppCloud Developer Framework area of your Eloqua development instance, you can also do so programmatically using a Cloud API endpoint. The endpoint also enables you to check the status of your App. You will need to know your App's ID in order to call out to the Cloud API endpoints. The App ID is listed on the App Details page in your Eloqua development instance, and is a GUID.

The Cloud API URL is https://<eloqua base url>.com/api/cloud/1.0/<endpoint> . All calls to the API must be authenticated using OAuth. Learn more about configuring and authenticating with

OAuth .

4.11.1 To Check the App's Status

Retrieve your app's status using the

GET /apps/{id}/configurations

endpoint:

GET /apps/a0f6779e-8263-4bfb-a292-9714cd10d1e7/configurations

The response should resemble:

HTTP/1.1 200 OK

{

"uri": "/apps/a0f6779e-8263-4bfb-a292-

9714cd10d1e7/configurations",

"clientSecret":

"a1ba63f9aae1cc84d91544f15b0af27ab6ced4e42c6145b9cc0425742ec f2a0da1ba63f9aae1cc84d91544f15b0af27ab6ce",

"name": "Call Example",

"description": "This is a test",

"shortDescription": "This is a test",

"iconUrl": "https://www.example.com/logo.png",

"enableUrl": "http://example.com/enable/{appId}/

{installId}/{userName}/{siteName}/{siteId}",

"statusUrl": "http://example.com/status/{installId}",

"callbackUrl": "http://example.com/callback/

{installId}",

"makeAvailableUrl": "https://example.com",

"publishedSites": [

"AwesomeCompany"

"status": "Up"

}

The status field indicates the app's current status, either "Up", "Down", or "Maintenance".

4.11.2 To Update the App's Status

Update the status by sending a request to the

PUT /apps/{id}/configurations

endpoint.

Important: You must include all of the fields in the configuration document in the PUT request.

You cannot merely specify a value for the status field.

The status can be "Up", "Down", or "Maintenance":

PUT /apps/a0f6779e-8263-4bfb-a292-

9714cd10d1e7/configurations

{

"uri": "/apps/a0f6779e-8263-4bfb-a292-

9714cd10d1e7/configurations",

"clientSecret":

"a1ba63f9aae1cc84d91544f15b0af27ab6ced4e42c6145b9cc0425742ec f2a0da1ba63f9aae1cc84d91544f15b0af27ab6ce",

"name": "Call Example",

"description": "This is a test",

"shortDescription": "This is a test",

"iconUrl": "https://www.example.com/logo.png",

"enableUrl": "http://example.com/enable/{appId}/

{installId}/{userName}/{siteName}/{siteId}",

"statusUrl": "http://example.com/status/{installId}",

"callbackUrl": "http://example.com/callback/

{installId}",

"makeAvailableUrl": "https://example.com",

"publishedSites": [

"AwesomeCompany"

"status": "Maintenance"

}

If successful, Eloqua will respond with an HTTP/1.1 204 No Content .

If you GET the /apps/{id}/configurations endpoint again, the response should reflect the updated status.

5 Reference

The following pages provide detailed reference for the parameters and endpoints used in the

Oracle Eloqua AppCloud Developer Framework.

URL Parameters

Cloud API endpoints

PUT /api/cloud/1.0/actions/instances/{id}

PUT /api/cloud/1.0/contents/instances/{id}

PUT /api/cloud/1.0/decisions/instances/{id}

PUT /api/cloud/1.0/feeders/instances/{id}

POST /api/cloud/1.0/actions/instances

POST /api/cloud/1.0/decisions/instances

GET /api/cloud/1.0/apps/{id}/configurations

PUT /api/cloud/1.0/apps/{id}/configurations

GET /api/cloud/1.0/apps/{id}/logs

Bulk API v2.0 documentation

Warning: For PUT or POST requests, you must specify application/json in the Content-

Type header. If the Content-Type header is not included, data persisted in Eloqua will be corrupted, resulting in your App not functioning correctly.

The Content-Type header is not required for GET or DELETE requests, since these do not accept data inputs.

5.1 Service level URL template parameters

The Oracle Eloqua AppCloud Developer Framework supports

URL Templating

, enabling the configuration of service URIs Eloqua calls out to. Any acceptable

template parameter

is substituted with the appropriate value before the call is made. See the

Action Service Parameters

for more information.

There are different

template parameters

available for different calls in different AppCloud service types:

Decision Service Parameters

Feeder Service Parameters

Content Service Parameters

Menu Service Parameters

Firehose Service Parameters

To look up individual parameters, please see the below

parameter descriptions

5.1.1 Service parameters

Action Services

URL

Available parameters

} ,

}

}

{

}

} ,

} ,

}

}

{

}

Conditional

Parameters

} and

{

} are available only if the campaign has been

URL

Available parameters

}

}

}

, {

} ,

} ,

} ,

} ,

, {

} ,

} ,

}

}

}

}

}

}

}

{

Conditional

Parameters saved with the referencing asset.

Decision Services

URL

Available parameters

} ,

}

}

{

}

}

}

}

{

} ,

} ,

} ,

} ,

, {

} ,

} ,

} ,

} ,

, {

} ,

} ,

} ,

} ,

} ,

Conditional

Parameters

} and

{

} are available only if the campaign has been saved with the referencing asset.

URL

Available parameters

}

} ,

} ,

} ,

, {

Conditional

Parameters

Feeder Services

URL

Available parameters

} ,

} ,

} ,

, {

}

} ,

} ,

}

}

, {

} ,

} ,

} ,

} ,

, {

} ,

} ,

} ,

} ,

, {

}

}

} ,

} ,

} ,

} ,

} ,

} ,

}

}

} ,

} ,

, {

Conditional

Parameters

} and

{

} are available only if the campaign has been saved with the referencing asset.

Content Services

URL

Available parameters

} ,

}

}

{

} ,

Conditional

Parameters

} ,

URL Available parameters

} ,

} ,

, {

} ,

} ,

} ,

, {

} ,

} ,

} ,

} ,

, {

}

}

}

}

} ,

} ,

}

} ,

} ,

} ,

} ,

} ,

}

} ,

} ,

} ,

, {

Conditional

Parameters

{

AssetType

} and

{