Oracle Marketing Cloud (Eloqua) Integration

Last modified on 2022/10/27 17:51
Contents

SM_IntegrationIntroduction_OnlyEN

You can integrate third-party systems with Service Manager in many ways. The method you select will depend on business requirements, architectural and security constraints as well as the characteristics specific to each third-party application or service.

This document describes an integration process that has already been implemented in a customer context. 

To find out more about this integration (e.g. scripts to be used), please do not hesitate to contact your EasyVista contact, or your service provider and integrator.

Integration Summary

This integration is used to retrieve all available information from your Eloqua instance using the Eloqua REST API Bulk 2.0 or the REST API 2.0 (GET method).

example    Retrieve and display a list of campaigns or contacts in an Service Apps app

Integration Data Feed (direction) Authentication Type Integration Connector Options

Favicon EasyVista - 32.png Service Apps

Up arrow.png

Logo - Oracle Eloqua.png

Check icon.png   Basic Authentication

REST data source   Apps - Datasource - JSON Online icon.png

SaaS Version of Third-Party Product

On-premise Version of Third-Party Product

Check icon.png

Not check icon.png

API detailed description

Item Comments
About the software and company

Logo - Oracle Eloqua.png

Oracle Marketing Cloud (Eloqua) enables drive lead generation and customer retention through data management, change management and marketing transformation.
Information about the REST API

Date on which the information was retrieved from the software company's website: May 2016

Last known REST API name/version/date: Bulk 2.0 (REST API) & REST API 2.0

  • The Bulk API is a RESTful API designed to support high volume data transfers. It can be used for CRM and data warehousing integrations and extending Eloqua's functionality.
  • The REST API is used primarily for Eloqua asset management. Assets are the building blocks of Eloqua marketing campaigns.

Eloqua's REST API is synchronous and so is not recommended for use with high volumes of data. For that we recommend using Eloqua's Bulk API.
Main useful links to software company information about REST

Getting started with Oracle Eloqua APIs

Determining base URLs

For Bulk 2.0 API:

Bulk 2.0 API (REST API) Overview

Bulk 2.0 API About determining endpoint URLs

Bulk 2.0 API Limits

Bulk 2.0 Developer Guide (pdf)

For REST API 2.0:

Oracle Eloqua REST API Overview

Eloqua Rest API 2.0 References

Oracle Eloqua REST API Developer Guide (pdf)
Format and sample of API resources/endpoints For Bulk 2.0 API:

https://{subdomain}.eloqua.com/api/bulk/2.0/assets/campaigns

For REST API 2.0:

https://{subdomain}.eloqua.com/api/rest/2.0/assets/campaigns

Notes:
  • When documenting a resource, Oracle uses curly brackets { } for identifiers.
  • Replace {subdomain} in the URI with your subdomain name provided by Oracle.
API assets

N/A

API recommendations

(limitations, advice, tips)

 For Bulk 2.0 API:
  • API calls: This API is "rate limited". Only a certain number of syncs are allowed: 2,000 syncs every 24 hours. Additionnal limits:
    • Import Limits:
      • Maximum of 100 fields
      • Hard limit of 32 MB per request
      • Staging limit: It is recommended to sync an import whenever approximately 250 MB of data has been posted to its staging area
    • Export Limits:
      • Maximum of 250 fields
      • There is a limit of 50,000 records per request
      • When exporting activities there is a limit of 5 million records per sync
  • Pagination: By default, endpoints return a maximum of 1000 records per page. You can change the number of records on a per-request basis by passing a limit parameter in the request URL parameters.
    example    limit=500  

    However, you cannot exceed 1000 records per page. You can specify an offset that allows you to retrieve the next batch of records. For example, if your limit is 1000, specifying an offset of 1000 will return records 1000 through 2000.

    example    offset=1000  
For REST API 2.0:
  • API calls: No data avaiblable
  • Pagination: By default, for most of endpoints (type: Get Lists) return a maximum of 1000 records (called also entities) per page. You can change the number of records on a per-request basis by passing a count parameter in the request URL parameters.
    example    count=500  

    You can specify which page of entities to return using the page parameter. By default, value is 1.

    example    page=3&count=50  
Comments For Bulk 2.0 API: According to Oracle:
  • "The Bulk API is a RESTful API designed to support high volume data transfers. It can be used for CRM and data warehousing integrations and extending Eloqua's functionality."
  • "Some Eloqua instances enable contact-level security, which restricts access to data based on different user roles...Because these permissions affect what data the user can access, it is important that the Eloqua user accessing the API has the appropriate permissions."
  • For Sortering/Ordering: orderBy specifies the name of the property to order the results by. The format is < term > ASC | DESC.
    example    orderBy=name ASC  
  • For Filtering/Searching: The Bulk API 2.0 supports complex filters that filter based on multiple criteria using the AND, OR, and NOT operators. q: Specifies query criteria used to filter results. The format is < term >< operator >< value >.
    example    name='Email*'  
For REST API 2.0: According to Oracle:
  • "Eloqua's REST API is synchronous and so is not recommended for use with high volumes of data. For that we recommend using Eloqua's Bulk API."
  • "The REST API is used primarily for Eloqua asset management. Assets are the building blocks of Eloqua marketing campaigns ..."
  • "Some Eloqua instances enable contact-level security, which restricts access to data based on different user roles...Because these permissions affect what data the user can access, it is important that the Eloqua user accessing the API has the appropriate permissions."
  • For Depth parameter: Eloqua APIs can retrieve entities at three different levels of depth: minimal, partial and complete. In general, requests at minimal depth will perform best, as they scan the least amount of data. The descriptions below should help you choose the right level of depth for your request.

    Open url.png see Request depth documentation

  • For Sortering/Ordering:
    • Sort: Specifies the name of the property used to sort the returned entities. The value depends on the type of entity being sorted, with each entity having its own list of sortable properties.
      example    GET .../data/contacts?sort=firstName  
    • Dir: Specifies the direction in which to sort the returned entities. asc for ascending or desc for descending.
      example    GET .../data/contacts?sort=firstName&dir=asc  
    • OrderBy: Specified the field by which list results are ordered. Any valid asset parameter field.
      example    ?orderBy=createdAt  
  • For Filtering/Searching:
    • Search: Specifies the search criteria used to retrieve entities. [{term} {operator}] {value} where:
      • {term} is the name of a field to filter on
      • {operator} is the comparison operator
      • {value} is the value to compare the field with
    • If {term} and {operator} are not supplied, the name field is compared to the value using the equality operator. Searches for exact full matches, and a * symbol can be used as a wildcard for partial matches.

Step-by-step integration process

Oracle Eloqua can be integrated with Service Apps in 4 easy steps:


Step 1: Check the list of prerequisites

  • This documentation assumes that you already have an Eloqua instance and an account on that instance.
  • The Bulk API is designed to let developers start developing with minimal setup or configuration effort. Nethertheless, in order to be able to interact with your Eloqua data, your account needs adequate permissions to access contact fields, secondary assets, and so on.
  • Make sure that the user account you will use belongs to the Security Group API Users.
             Prerequisites.png

Note: Some Eloqua instances enable contact-level security, which restricts access to data based on different user roles. Users might only have access to contacts located in their geographical region, for instance. Because these permissions affect what data the user can access, it is important that the Eloqua user accessing the API has the appropriate permissions.


Step 2: Start the process for creating the REST data source

   Open url.png  For details about the creation, see the wiki page REST data source

  • Click Apps - Add datasource icon.png in the Objects pane. 
  • Open the Online category and select the REST data source Apps - Datasource - JSON Online icon.png.
  • Name the data source.

    example    Eloqua_List of Contacts Lists


Step 3: Authenticate to Oracle Marketing Cloud/Eloqua

 Authenticate to Oracle Marketing Cloud/Eloqua with Basic Access Authentication

  • Select the type of authentication: Authentication Type = Basic.
  • Click Apps - Edit icon.png next to the Basic Authentication Parameters field. 
  • Enter the User Name using the following format: CompanyName\EloquaUserName. Enter the Password.
             Basic Access Authentication.png
    • The user name is composed of your Oracle Cloud Marketing/Eloqua CompanyName and account/login you want to use for this data source (separated with a \).
    • The password is the password set for this account.
    • Once you validate, the *** symbols will appear in the field.


Step 4: Create a query string using Oracle Marketing Cloud/Eloqua documentation

         Open url.png  See the Oracle Marketing Cloud/Eloqua API documentation for details
        Open url.png  See Examples of use cases

  • Create a query string as a data source, i.e. a resource to access, in the URL field.

example   You want to create a data source that will retrieve a list of all campaign assets ordered by ascending order and ordered by creation date with a minimum of information (parameter depth=minimal), with the REST API 2.0  ==>  Enter the following text in the URL field. Note: Replace {subdomain} with the name of your Oracle Marketing Cloud/Eloqua instance.

https://{subdomain}.eloqua.com/API/REST/2.0/assets/campaigns?depth=minimal&dir=asc&orderBy=createdAt

Best Practice

        Open url.png See Best Practice for the REST data source

  • By default, Eloqua list endpoints return a maximum of 1000 records per page. To keep the number of records as low as possible, we recommend that you define as many parameters as possible.
  • For the REST API 2.0 you can also use the parameter depth with the value minimal to reduce the number of information returned and the size of Json flows.

Samples of most relevant use cases and resources

 Notes: 

  • Replace {subdomain} in the URI with your subdomain name provided by Oracle.

Method: GET

Use Case Sample Endpoint
Retrieve a list of contact segments

==> with Bulk API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label: Retrieve a list of contact segments
URI: https://{subdomain}.eloqua.com/api/bulk/2.0/contacts/segments
Description: Retrieve a list of contact segments for our Instance
Selector: .items
Retrieve a list of account list definitions

==> with Bulk API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label: Retrieve a list of account list definitions
URI: https://{subdomain}.eloqua.com/api/bulk/2.0/accounts/lists
Description: Retrieve a list of account list definitions for our Instance
Selector: N/A
Retrieve a list of activity import definitions

==> with Bulk API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label:

Retrieve a list of activity import definitions for our Instance

Activities are entities which track certain defined online behavior for individual contacts.

Activity elements behave differently from other Eloqua elements: each activity type has its own set of associated fields
URI: https://{subdomain}.eloqua.com/api/bulk/2.0/activities/imports
Description: Retrieve a list of contact segments for our Instance
Selector: N/A
Retrieve a list of contact lists

==> with Bulk API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label: Retrieve a list of contact lists
URI: https://{subdomain}.eloqua.com/api/bulk/2.0/contacts/lists
Description: Retrieve a list of contact lists for our Instance
Selector: .items
Retrieve a list of contact export definitions

==> with Bulk API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label: Retrieve all campaign assets
URI: https://{subdomain}.eloqua.com/api/bulk/2.0/contacts/exports
Description: Retrieve a list of contact export definitions for our Instance
Selector: N/A
Retrieve all campaign assets

==> with REST API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label: Retrieve a list of contact export definitions
URI: https://{subdomain}.eloqua.com/api/rest/2.0/assets/campaigns
Description: Retrieve all campaign assets for our Instance
Selector: .name
Retrieve all visitor data

==> with REST API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label: Retrieve all visitor data
URI: https://{subdomain}.eloqua.com/api/rest/2.0/data/visitors
Description: Retrieve all visitor data for our Instance
Selector: N/A
Retrieve a list of all the external assets

==> with REST API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label: Retrieve a list of all the external assets
URI: https://{subdomain}.eloqua.com/api/rest/2.0/assets/externals
Description: Retrieve a list of all the external assets associated for our Instance
Selector: N/A
Retrieve all external assets type

==> with REST API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label: Retrieve all external assets type
URI: https://{subdomain}.eloqua.com/api/rest/2.0/assets/external/types
Description: Retrieve all external assets type for our Instance
Selector: .name
Retrieve a list of email groups

==> with REST API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label: Retrieve a list of email groups
URI: https://{subdomain}.eloqua.com/api/rest/2.0/emailGroups
Description: Retrieve a list of email groups for our Instance
Selector: N/A
Retrieve a list of all campaign assets:
  • ordered by ascending order
  • and ordered by creation date with a minimum of information (parameter depth=minimal)

    ==> with REST API 2.0

Authentication Type: Basic Access Authentication
Basic Authentication Parameters: User Name: {CompanyName}\{EloquaUserName}

Password: {Password}
Label: Retrieve a list of all campaign assets ordered by ascending order and ordered by creation date with a minimum of information
URI: https://{subdomain}.eloqua.com/api/rest/2.0/assets/campaigns?depth=minimal&dir=asc&orderBy=createdAt
Description: Retrieve a list of all campaign assets ordered by ascending order and ordered by creation date with a minimum of information (parameter depth=minimal) for our Instance
Selector: .name
SAS_IntegrationRESTAboutTheUse_OnlyEN

About the use of the software companies API REST

   Caution : The possible cost of the use of the third-parties API REST via Service Apps is not taken care by EasyVista.

  • Numerous software companies limit the access to the API REST of their software, generally by basing itself on a number of calls by hour/day/month.
  • Only specific editions of their software can be eligible in the use of the API REST (with or without additional cost).
  • Some software companies set up plans, e.g., Classic, Professional, Enterprise, for which the number of possible calls to the REST API or even to specific resources (i.e. endpoints) can be more or less numerous.
Tags:
Powered by XWiki © EasyVista 2022