Instantiation-execution model

With the exception of menus and the firehose, Oracle Eloqua app 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.

Service instantiation

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.
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:
Note: The "Content-Type" header must be set to "application/json" for the response to the Create URL call.
```
HTTP/1.1 200 application/json; charset=utf-8

{
  "recordDefinition": {
    "ContactID": "{{Contact.Id}}",
    "EmailAddress": "{{Contact.Field(C_EmailAddress)}}"
  }
}
```
This tells Eloqua to send the contacts’ Contact ID and email address when the service is executed. For detailed instructions, see the documentation specific to each service type.
The marketer can then configure the instance using your service's UI by clicking Edit on the service instance. Eloqua opens a browser window to the configure URL for the service. This call to the configure URL comes directly from the marketing user's browser rather than from the Eloqua API. If you need to restrict access, you can do so here by requiring the user be on a specific VPN, for example.

If the Marketer has made changes, your API should call back to Eloqua using a PUT request with an updated DTO specifying the new record definition. For example, if the Marketer created an AppCloud Decision step that required field1, field2, and field3, the PUT request would resemble:

PUT https://secure.eloqua.com/api/cloud/1.0/decisions/instance/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)}}"
   }
}

Execution

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.

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=fddc932a-f27d-40c3-a126-82299b9512c5&asset=456

{
  "offset" : 0,
  "limit" : 1000,
  "totalResults" : 2,
  "count" : 2,
  "hasMore" : false,
  "items" :
  [
     {
        "ContactID" : "1",
        "EmailAddress" : "fred@example.com",
        "field1" : "stuff",
        "field2" : "things",
        "field3" : "et cetera"
     },
     {
        "ContactID" : "2",
        "EmailAddress" : "sylvie@example.com",
        "field1" : "more stuff",
        "field2" : "other things",
        "field3" : "and so on"
     }
  ]
}

This follows the format defined during the create URL and configure URL calls during the instantiation phase.

If Eloqua calls out to your app and doesn't receive a response within 100 seconds, the contacts in a step will be marked as "Errored". If Eloqua receives a response status code that is between 300 and 599, Eloqua will retry the notify call over approximately an eight-hour period of time with a backoff strategy of the time between calls doubling after each call. After this eight-hour period, 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.
If you specified maximum record size of 0 when you configured your app, or the record definition sent during the instantiation phase contains no fields, the DTO contains an empty JSON object. Otherwise, the call sends a DTO containing contact data, with a maximum limit to the number of records as specified in the service configuration. If there are more records than the maximum limit, Eloqua will keep sending requests until all the data is transmitted.
You can then choose to return the same response for all the contacts in the batch, or tailor your responses to each contact.
To individualize your responses for each contact, the desired HTTP response status code is a 204, followed up with an import call using the 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
Eloqua receives the import. For service instances associated with a campaign, those contacts flow through to the next stage.

Learn more

App Developer Framework