Develop an Oracle Eloqua app feeder service

Create URL

Eloqua's call to the CreateURL:

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

{}

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

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

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

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/9347bfe1-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.

Note: X-Frame-Options must not be set to DENY for any configure page.

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

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=9347bfe1-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=9347bfe1-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.

   Create a contact import definition where the sync action sets the record's status, where the instance ID is 9347bfe1-9c72-409c-a5cd-402ff74f0caa :

   POST https://secure.p03.eloqua.com/api/bulk/2.0/contacts/imports
   {
      "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"
   }
   

2. Send Eloqua the import data using the uri:

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

   [
        {
           "emailAddress" : "fred@example.com"
        },
        {
           "emailAddress" : "sylvie@example.com"
        }
   ]
   

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
   

   For a full description of the sync status codes, see: bulk API sync status codes

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

   200 OK
   
   {
         "syncedInstanceURI" : "/contacts/imports/6",
         "syncStartedAt" : "2014-01-01T13:59:07.1375620Z",
         "syncEndedAt" : "2014-01-01T13:59:14.1375620Z",
         "status" : "success",
         "createdAt" : "2014-01-01T13:59:07.1375620Z",
         "createdBy" : "DocsExample",
         "uri" : "/syncs/6"
   }