DocumentationExperience PlatformDestinations Guide

(API) Oracle Eloqua connection

Last update: Wed Jul 31 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • User

Oracle Eloqua enables marketers to plan and execute campaigns while delivering a personalized customer experience for their prospects. With integrated lead management and easy campaign creation, it helps marketers engage the right audience at the right time in their buyer’s journey and elegantly scales to reach audiences across channels including email, display search, video, and mobile. Sales teams can close more deals at a faster rate, increasing marketing ROI through real-time insight.

This Adobe Experience Platform destination leverages the Update a contact operation from the Oracle Eloqua REST API, which allows you to update identities within an audience into Oracle Eloqua.

Oracle Eloqua uses Basic Authentication to communicate with the Oracle Eloqua REST API. Instructions to authenticate to your Oracle Eloqua instance are further below, in the Authenticate to destination section.

Use cases use-cases

The marketing department of an online platform wants to broadcast an email based marketing campaign to a curated audience of leads. The platform’s marketing team can update existing lead information through Adobe Experience Platform, build audiences from their own offline data, and send these audiences to Oracle Eloqua, which can then be used to send the marketing campaign email.

Prerequisites prerequisites

Experience Platform prerequisites prerequisites-in-experience-platform

Before activating data to the Oracle Eloqua destination, you must have a schema, a dataset, and segments created in Experience Platform.

Refer to the Experience Platform documentation for Audience Membership Details schema field group if you need guidance on audience statuses.

Oracle Eloqua prerequisites prerequisites-destination

In order to export data from Platform to your Oracle Eloqua account you need to have an Oracle Eloqua account.

Additionally, you need, at a minimum, the “Advanced Users - Marketing permissions” for your Oracle Eloqua instance. Refer to the “Security Groups” section on the Secured user access page for guidance. The access is required by the destination to programmatically determine your base URL when invoking the Oracle Eloqua API.

Gather Oracle Eloqua credentials gather-credentials

Note down the items below before you authenticate to the Oracle Eloqua destination:

Credential
Description
Company Name
The company name associated with your Oracle Eloqua account.
You will later use the Company Name and Oracle Eloqua Username as a concatenated string to be used as the Username when authenticating to the destination.
Username
The username of your Oracle Eloqua account.
Password
The password of your Oracle Eloqua account.
Pod
Oracle Eloqua supports multiple data centers, each with a unique domain name. Oracle Eloqua refers to these as “pods”, there are currently seven in total - p01, p02, p03, p04, p06, p07, and p08. To obtain which POD you are on, login to Oracle Eloqua and note the URL in your browser after you have logged in successfully. For example, if your browser URL is secure.p01.eloqua.com your pod is p01. Refer to the determining your POD page for additional guidance.

Refer to the Signing in to Oracle Eloqua for guidance.

Guardrails guardrails

NOTE
  • Oracle Eloqua custom contact fields are automatically created using the names of the audiences selected during the Select segments step.

  • Oracle Eloqua has a maximum limit of 250 custom contact fields.

  • Before exporting new audiences ensure that the number of Platform audiences and the number of existing audiences within Oracle Eloqua do not exceed this limit.

  • If this limit is exceeded, you will encounter an error in Experience Platform. This is because the Oracle Eloqua API fails to validate the request, and responds with a - 400: There was a validation error - error message describing the issue.

  • If you have reached the limit specified above, you need to remove existing mappings from your destination and delete the corresponding custom contact fields in your Oracle Eloqua account before you can export more segments.

  • Refer to the Oracle Eloqua Creating Contact Fields page for information about additional limits.

Supported identities supported-identities

Oracle Eloqua supports update of identities described in the table below. Learn more about identities.

Target Identity
Description
Mandatory
EloquaId
Unique identifier of the contact.
Yes

Export type and frequency export-type-frequency

Refer to the table below for information about the destination export type and frequency.

Item
Type
Notes
Export type
Profile-based
  • You are exporting all members of a segment, together with the desired schema fields (for example: email address, phone number, last name), according to your field mapping.
  • For each selected audience in Platform, the corresponding Oracle Eloqua segment status gets updated with its audience status from Platform.
Export frequency
Streaming
  • Streaming destinations are “always on” API-based connections. As soon as a profile is updated in Experience Platform based on audience evaluation, the connector sends the update downstream to the destination platform. Read more about streaming destinations.

Connect to the destination connect

IMPORTANT
To connect to the destination, you need the View Destinations and Manage Destinations access control permissions. Read the access control overview or contact your product administrator to obtain the required permissions.

To connect to this destination, follow the steps described in the destination configuration tutorial. In the configure destination workflow, fill in the fields listed in the two sections below.

Within Destinations > Catalog search for (API) Oracle Eloqua. Alternatively you can locate it under the Email Marketing category.

Authenticate to destination authenticate

Fill in the required fields below. Refer to the Gather Oracle Eloqua credentials section for any guidance.

  • Password: The password of your Oracle Eloqua account.
  • Username: A concatenated string composed of your Oracle Eloqua Company Name and the Oracle Eloqua Username.
    The concatenated value takes the form of {COMPANY_NAME}\{USERNAME}.
    Note, do not use any braces or spaces and preserve the \.
    For example if your Oracle Eloqua Company Name is MyCompany and Oracle Eloqua Username is Username, the concatenated value you will use in the Username field is MyCompany\Username.

To authenticate to the destination, select Connect to destination.
Platform UI screenshot showing how to authenticate.

If the details provided are valid, the UI displays a Connected status with a green check mark. You can then proceed to the next step.

Fill in destination details destination-details

To configure details for the destination, fill in the required and optional fields below. An asterisk next to a field in the UI indicates that the field is required.
Platform UI screenshot showing the destination details.

  • Name: A name by which you will recognize this destination in the future.
  • Description: A description that will help you identify this destination in the future.
  • Pod: To obtain which pod you are on, login to Oracle Eloqua and note the URL in your browser after you have logged in successfully. For example, if your browser URL is secure.p01.eloqua.com the pod value you need to select is p01. Refer to the Gather Oracle Eloqua credentials section for additional guidance.

Enable alerts enable-alerts

You can enable alerts to receive notifications on the status of the dataflow to your destination. Select an alert from the list to subscribe to receive notifications on the status of your dataflow. For more information on alerts, see the guide on subscribing to destinations alerts using the UI.

When you are finished providing details for your destination connection, select Next.

Activate audiences to this destination activate

IMPORTANT

Read Activate profiles and audiences to streaming audience export destinations for instructions on activating audiences to this destination.

Mapping considerations and example mapping-considerations-example

To correctly send your audience data from Adobe Experience Platform to the Oracle Eloqua destination, you need to go through the field mapping step. Mapping consists of creating a link between your Experience Data Model (XDM) schema fields in your Platform account and their corresponding equivalents from the target destination.

To map your XDM fields to the Oracle Eloqua destination fields, follow these steps:

  1. In the Mapping step, select Add new mapping. You will see a new mapping row on the screen.

  2. In the Select source field window, choose the Select attributes category and select the XDM attribute or choose the Select identity namespace and select an identity.

  3. In the Select target field window, choose Select identity namespace and select an identity, or choose Select custom attributes and type in the desired attribute name in the Attribute name field. The attribute name that you provide should match an existing contact attribute in Oracle Eloqua. See create a contact for the exact attribute names that you can use in Oracle Eloqua.

    • Repeat these steps to add both the required and any desired attribute mappings between your XDM profile schema and Oracle Eloqua:

      table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 9-row-3 10-row-3
      Source Field Target Field Mandatory
      IdentityMap: Eid Identity: EloquaId Yes
      xdm: personalEmail.address Attribute: emailAddress Yes
      xdm: personName.firstName Attribute: firstName
      xdm: personName.lastName Attribute: lastName
      xdm: workAddress.street1 Attribute: address1
      xdm: workAddress.street2 Attribute: address2
      xdm: workAddress.street3 Attribute: address3
      xdm: workAddress.postalCode Attribute: postalCode
      xdm: workAddress.country Attribute: country
      xdm: workAddress.city Attribute: city

    • An example with the above mappings is shown below:
      Platform UI screenshot example with attribute mappings.

IMPORTANT
  • Attributes specified in the Target field should be named exactly as specified in the Create a contact as these attributes will form request body.
  • Attributes specified in the Source field do not follow any such restriction. You can map it based on your need, however if the data format is not correct when pushed to Oracle Eloqua it will result in an error. For example, you can map the Source field identity namespace contact key, ABC ID etc. to Target field : EloquaId after ensuring that the ID values match the format that is accepted by Oracle Eloqua.
  • The EloquaID mapping is mandatory to update attributes corresponding to the identity.
  • The emailAddress mapping is required. Without it, the API throws an error as shown below:
code language-json 
{
   "type":"ObjectValidationError",
   "container":{
      "type":"ObjectKey",
      "objectType":"Contact"
   },
   "property":"emailAddress",
   "requirement":{
      "type":"EmailAddressRequirement"
   },
   "value":"<null>"
}

When you are finished providing the mappings for your destination connection, select Next.

NOTE
The destination automatically suffixes a unique identifier to the selected audience names on each execution when sending the contact field information to Oracle Eloqua. This ensures the contact field names corresponding to your audience names do not overlap. Refer to the Validate data export section screenshot example of an Oracle Eloqua Contact Details page with custom contact field created using the audience names.

Validate data export exported-data

To validate that you have correctly set up the destination, follow the steps below:

  1. Select Destinations > Browse and navigate to the list of destinations.

  2. Next, select the destination and switch to the Activation data tab, then select an audience name.
    Platform UI screenshot example showing Destinations Activation Data.

  3. Monitor the audience summary and ensure that the count of profiles corresponds to the count within the segment.
    Platform UI screenshot example showing Segment.

  4. Log in to the Oracle Eloqua website, then navigate to the Contacts Overview page to check if the profiles from the audience have been added. To see the audience status, drill down into a Contact Detail page and check if the contact field with the selected audience name as its prefix has been created.

Oracle Eloqua UI screenshot showing the Contact Details page with custom contact field created with the audience name.

Data usage and governance data-usage-governance

All Adobe Experience Platform destinations are compliant with data usage policies when handling your data. For detailed information on how Adobe Experience Platform enforces data governance, see the Data Governance overview.

Errors and troubleshooting errors-and-troubleshooting

When creating the destination, you might receive one of the following error messages: 400: There was a validation error or 400 BAD_REQUEST. This happens when you exceed the 250 custom contact fields limit, as described in the guardrails section. To fix this error, make sure you are not exceeding the custom contact field limit in Oracle Eloqua.
Platform UI screenshot showing error.

Refer to the Oracle Eloqua HTTP status codes and Oracle Eloqua Validation errors pages for a comprehensive list of status and error codes with explanations.

Additional resources additional-resources

For additional details, see the Oracle Eloqua documentation:

Changelog

This section captures the functionality and significant documentation updates made to this destination connector.

View changelog
table 0-row-3 1-row-3 2-row-3 layout-auto
Release month Update type Description
April 2023 Documentation update
  • We updated the use-cases section with a clearer example of when customers would benefit from using this destination.
  • We updated the mapping section with clear examples of both mandatory and optional mappings.
  • We updated the Connect to the destination section with an example on how to construct the concatenated value for the Username field using the Oracle Eloqua Company Name and the Oracle Eloqua Username. (PLATIR-28343)
  • We updated the Gather Oracle Eloqua credentials and the Fill in destination details sections with guidance on Oracle Eloqua Pod selection. The “Pod” value is used by the destination to construct the base URL for the API calls. The Oracle Eloqua prerequisites section was also updated with guidance on assigning “Advanced Users - Marketing permissions” as a required “Security Groups” for your Oracle Eloqua instance.
March 2023 Initial release Initial destination release and documentation publish.
recommendation-more-help
7f4d1967-bf93-4dba-9789-bb6b505339d6