Oracle Marketing Cloud (Eloqua) Integration


About this integration
SAS_IntegrationRESTIntroduction_OnlyEN

You can integrate third-party systems with Product name - ev sas.png 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. You can use the REST, CSV, Online CSV data sources as well as the HTML Script widget.

This document describes a standard integration process with the REST data source that has already been implemented in a customer context. It provides only a few examples of HTTP queries for manipulating resources (i.e. endpoints) using the REST API in the third-party application. You can discover more about the possibilities of this API and consult the relevant documentation on the website of the third-party software company.

To find out more about this integration, please contact the Logo - EasyVista.png Consulting & Professional Services team, the Logo - EasyVista.png Support team, 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 documentation icon EN.png  Retrieve and display a list of campaigns or contacts in an Product name - ev sas.png app

Integration Data Feed (direction) Authentication Type Integration Connector Options

Product name - ev sas - big.png

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

SAS_ConventionAPIRequests_OnlyEN

Convention for the API requests

Curly brackets { } indicate values you have to supply. 

In most of the cases, we draw your attention with:

  • in green and bold, the important and mandatory values to be replaced;
  • in green, certain important and/or optional values (often choice of parameters).

Example documentation icon EN.png  https://{subdomain}.eloqua.com  ==> replace {subdomain} with the name of your Marketing Cloud/Eloqua domain (i.e. < Host >)

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 documentation icon EN.png    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 documentation icon EN.png    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 documentation icon EN.png    count=500

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

    Example documentation icon EN.png    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 documentation icon EN.png    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 documentation icon EN.png    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 documentation icon EN.png    GET .../data/contacts?sort=firstName

    • Dir: Specifies the direction in which to sort the returned entities. asc for ascending or desc for descending.

      Example documentation icon EN.png    GET .../data/contacts?sort=firstName&dir=asc

    • OrderBy: Specified the field by which list results are ordered. Any valid asset parameter field.

      Example documentation icon EN.png    ?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 Product name - ev sas.png 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 documentation icon EN.png  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 documentation icon EN.png  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 big icon.pngBest 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 third-parties REST API

Please note that numerous software companies limit the access to the REST API of their software, generally by basing itself on a number of calls by hour/day/month.
Moreover, only specific editions of their software can be eligible in the use of the API REST (with or without additional cost).
Finally, some software companies set up plans (for example Classic, Professional, Enterprise, etc.) 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.

The possible cost of the use of the third-parties API by means of Product name - ev sas.png is not taken care by Logo - EasyVista.png.

Tags:
Last modified by Unknown User on 2017/04/24 15:23
Created by Administrator XWiki on 2016/07/11 15:04

Shortcuts

Recent Updates

Haven't been here in a while? Here's what changed recently:

-   Product name - ev itsm.png
-   Product name - ev sas.png

Interesting Content

How to Automate Integration
Add a Shortcut to an App
History
Quick Dashboard
Full text search - Stop Words

Powered by XWiki ©, EasyVista 2018