TIBCO Scribe® Online Connector For Oracle Eloqua Bulk API

Use the TIBCO Scribe® Online Connector for Oracle Eloqua Bulk API to create contact, account, and custom entities in Oracle Eloqua with TIBCO Scribe® Online, as well as query activity information from Oracle Eloqua.

Possible use cases for the Oracle Eloqua Bulk API Connector include:

• Copy Oracle Eloqua data to a data warehouse for third party reporting and data analytics. Periodically integrate any new or modified records into the data warehouse to keep your reports up to date.
• Initiate marketing activities in Oracle Eloqua, such as a marketing campaign, by synchronizing leads from your CRM system into Oracle Eloqua. New leads created in Oracle Eloqua can trigger a campaign to begin immediately.
• Update existing contact information in Oracle Eloqua by integrating contacts from another system, such as Salesforce.
• Enable company information to be shared with a customer, based on the subscription status of that customer.

Refer to TIBCO Scribe® Online Connectors For Oracle Eloqua for information on when to use the Oracle Eloqua Bulk API Connector and when to use the standard Oracle Eloqua Connector.

Connector Specifications

This Connector primarily supports Oracle Eloqua Bulk API version 2.0.

	Supported
Agent Types
On Premise	X
Cloud	X
Replication Services
Source
Target
Integration Services
Source	X
Target	X
Migration Services
Source	X
Target	X
Maps
Integration	X
Request-Reply	X
Message

Supported Entities

TIBCO Scribe® Online currently supports the following Oracle Eloqua entities. Select a linked entity name for additional information when using that entity in TIBCO Scribe® Online.

Entity	Query	Add	Create	Update	Delete	Upsert
Account	X					X
Contact	X					X
Company Custom Objects	X					X
Contact Custom Objects	X					X
ContactListMember		X
EmailGroup	X
Activities
ActivityBouncebackEmail	X
ActivityEmailClickThrough	X
ActivityEmailOpen	X
ActivityEmailSend	X
ActivityEmailSubscribe	X
ActivityEmailUnsubscribe	X
ActivityFormSubmit	X
ActivityPageView	X
ActivityWebVisit	X

Setup Considerations

The Oracle Eloqua user account must have the following: 

• Valid credentials to an Oracle Eloqua company.
• Read and write access to the supported entities.

Oracle Eloqua user's API settings must include:

• "API User" role
• API should be enabled for the user's Oracle Eloqua instance.
• Appropriate Security Groups. Oracle Eloqua User settings must be configured for Security Groups associated with the data you want to access. If not, you may create records with incorrect permissions settings preventing you from accessing that data later.

  For example, if you use TIBCO Scribe® Online to create a ContactList and your Oracle Eloqua User's settings are not configured for the Advanced Users - Marketing Security Group, TIBCO Scribe® Online cannot retrieve the list nor the Contacts associated with that list.

OAuth Connections

Some connections where authentication tokens must be refreshed periodically, such as OAuth2 or Azure AD authentication flows, do not support simultaneous use of the connection by more than one process. This includes:

• Multiple Scheduled or Data Replication Solutions running at the same time, using the same connection, when using a Cloud Agent or different On-Premise Agents.
• Event Solutions that use an OAuth Connection to write to a target system because this type of Solution processes multiple messages concurrently.

If you are encountering connection errors, the workaround options include:

• Configure a separate connection with unique credentials, such as Client IDs and Users, for each Scheduled or Data Replication Solution.
• Set up Solution schedules that ensure that there are never two Solutions running that use the same OAuth connection. For example, schedule one Solution to run Monday, Wednesday, and Friday. Schedule the second Solution to run Tuesday, Thursday, and Saturday.

Selecting An Agent Type For Oracle Eloqua Bulk API

Refer to TIBCO Scribe® Online Agents for information on available Agent types and how to select the best Agent for your Solution.

Connecting To Oracle Eloqua Bulk API

1. Select More > Connections from the menu.
2. From the Connections page select Add to open the Add a New Connection dialog.
3. Select the Connector from the drop-down list in the Connection Type field, and then enter the following information for this Connection:
   • Name — This can be any meaningful name, up to 25 characters.
   • Alias — An alias for this Connection name. The alias is generated from the Connection name, and can be up to 25 characters. The Connection alias can include letters, numbers, and underscores. Spaces and special characters are not accepted. You can change the alias. For more information, see Connection Alias.
   • A message in the Connection dialog box indicates the OAuth URL has been received and you can begin the Authentication process.
4. Select Authenticate. The Allow Access To Oracle Eloqua screen opens, noting the TIBCO Scribe® Online Connector for the Oracle Eloqua Bulk API is requesting permission to access Oracle Eloqua.
5. If you are not logged into Oracle Eloqua:
   1.  Select Login and enter the following information: 
      • Company — The name of your company as defined in Oracle Eloqua.
      • Username — Your user name for Oracle Eloqua.
      • Password — The password associated with your Oracle Eloqua user name.
   2. Select Sign In. You are prompted to accept the request for access.
6. Select Accept.

   A TIBCO Scribe® Online page with the following message displays:

   

7. Select Close to return to the TIBCO Scribe® Online page.

   Tip: Do not test the Connection until the message at the top of the Connection dialog reads Authentication complete. Note that it may take a few minutes for this message to display.

8. Select Test to ensure that the Agent can connect to your database. Be sure to test the Connection against all Agents that use this Connection. See Testing Connections.
9. Select OK/Save to save the Connection.

Metadata Notes

Text Fields

• Oracle Eloqua text data types are represented as string data types in TIBCO Scribe® Online.
• Oracle Eloqua recognizes text fields of up to 32,000 characters. However, in TIBCO Scribe® Online, text fields in this Connector only appear to be 1000 characters in length.

Numeric Fields

• Oracle Eloqua numeric fields are represented as type Double64.
• Oracle Eloqua number data types are represented as signed integer data types in TIBCO Scribe® Online.
• Due to API limitations, a number longer than 15 digits, including decimal places, is converted to its corresponding scientific notation format and any operation that reads or writes to that field fails.

Picklists

• Use Option Value, not Option Name, when mapping or matching picklist values.
• Option Values are case-sensitive and space-sensitive. Spaces before, after, and within strings must match.
• If you Create or Update with a Null value, a value that is not in the list, or multiple values in a single-select picklist, the result after the Create or Update operation is a No Selection value.
• For multi-select picklists, separate options in the source data with a double colon (::), for example, Value1::Value2::Value3.

Checkbox Fields

• The value from the source must exactly match the Checked Value defined for that Oracle Eloqua checkbox field. Otherwise, a check=yes result does not appear after the Solution runs.

  For example, if a decimal field is defined with a Checked Value of 1.000 and a mapped source field is defined with a value of 1, decimal field, or 1.000, decimal or string field, the result is check=yes. However, if that same decimal field is defined with a Checked Value property of 1, these two mapped source values yield a check=no result.

Filter, Match Criteria, Or Lookup

• The Not Like operator is not supported.

Access Token

• When you establish a Connection with the Oracle Eloqua Bulk API Connector, your system is granted an access token and a refresh token. These tokens allow a Solution to remain actively connected to Oracle Eloqua.

Oracle Eloqua Bulk API Connection As IS/MS Source

• If Preview on a Query operation does not display any data, your data set may be too large. However, the query will be successful when the Map is executed.
• Marketing Activity data is not retained indefinitely. Refer to Oracle Eloqua documentation for data retention policy information.
• When filtering with the CreatedBy or UpdatedBy field, use the actual username, such as Firstname.Lastname, instead of the userid integer value displayed in the query Preview for these fields. Using the userid integer value yields no results.
• This Connector supports exports of up to 250 fields per export call. Requests for a greater number of fields must be handled by multiple export calls.

Oracle Eloqua Bulk API Connection As IS/MS Target

• Upsert
  • Upsert is only supported for the Account, Contact, and Custom Objects entities.
  • Batch Processing must be enabled for the Upsert operation. If disabled, TIBCO Scribe® Online processes the records very slowly and generates errors.
  • The Upsert operation does not have a Match Criteria tab. When linking fields between the source and target for an Upsert operation, TIBCO Scribe® Online provides a MatchFieldName in the list of fields for the target. Link that field to a field in the source that contains unique data, such as company name, email address, or phone number. When the Map is executed, the data in the MatchFieldName determines the result:
    • If the data in the field matches an existing record, the record is updated.
    • If the data in the field does not match any records, a new record is inserted.
  • Typically, you populate the MatchFieldName field with the Upsert operation. If you use Upsert with the Id field mapped instead of MatchFieldName, the results for entities that support Upsert are as follows:
    • Account — If the Id matches, the Account is updated; otherwise a new Account record is created.
    • Contact — If the Id matches, the Contact is updated; otherwise a new Contact record is created.
    • Custom Objects — A new Custom Object record is always created regardless of whether the Id matches or not.
• This Connector supports import definitions that include up to 100 fields. If more than 100 fields are specified, the import definition fails to create.

Notes On Standard Entities

Account

• The Account entity displays as Company in the Oracle Eloqua user interface, but displays as Account in the API and in TIBCO Scribe® Online.

Activity Type Entities

• Query Previews — For all activity-type entities, apply a filter against a specific Contact ID to preview sample data. Unfiltered Query Previews may result in timeouts.
• ActivityBouncebackEmail — Bounceback type information, such as hardBounce or softBounce, is not exposed in the Bulk API.
• ActivityFormSubmit, ActivityWebVisit — There may be a delay of 15 minutes or more between the time this data activity is started in Oracle Eloqua and when the data is received by the Oracle Eloqua Bulk API Connector.
• ActivityWebVisit — Always shows 0 for Website Visits.
• Filter, Match Criteria, Or Lookup
  • Operators IsNull, NotLike, and IsNotNull are not valid.
  • The ActivityType field is not available as a filter.
  • The logical OR operator is not supported.

Contact

• IsSubscribed — This Boolean field appears on the Contact entity, can be set with the Upsert Block, but is not filterable. The global Subscribe/Unsubscribe setting appears on the summary screen and on the Preferences tab in Oracle Eloqua. Values for this field are:
  • 0 or False — Unsubscribed
  • 1 or True — Subscribed

ContactListMember

• This entity is only available on the Add Block.
• ContactId, ContactEmailAddress — If either of these fields contains an invalid value, the Oracle Eloqua Bulk API does not report an error and TIBCO Scribe® Online reports the record as successfully processed, but the record is not added to Oracle Eloqua.
• MatchFieldName — Must specify the literal string for either the ContactId or the ContactEmailAddress field.
• ContactListId — Identifies the list where the ContactListMember is to be added. Some valid list Id values reference system contact lists that are not included in Query results but that can be mapped and updated without errors. Values associated with these system contact lists are:
  • 2 —  My Brochures Subscriptions
  • 3 —  My Brochures UnSubscriptions
  • 4 —  Newsletter Subscriptions
  • 5 —  Newsletter UnSubscriptions
  • 6 —  Events Subscriptions
  • 7 —  Events UnSubscriptions
  • 8 —  Testing Area Subscriptions
  • 9 —  Testing Area UnSubscriptions

EmailGroup

• Filter, Match Criteria, Or Lookup
  • The logical operators AND, and OR are not supported.

Oracle Eloqua Custom Objects

Company Custom Objects

• Company Custom Objects cannot be mapped to Accounts when upserting Custom Object records in Oracle Eloqua using TIBCO Scribe® Online and the Oracle Eloqua Bulk API. You can map the Company Custom Objects to a Company in the Oracle Eloqua user interface. The Account entity displays as Company in the Oracle Eloqua user interface.

Upserting Records

• To upsert Contact Custom Object records from TIBCO Scribe® Online and have the resulting records automatically saved and mapped in the Oracle Eloqua application, map the following field in the target field list in Oracle Eloqua, along with any other field mappings:
  • ContactEmailAddress – The email address of the Contact entity should be mapped to the ContactEmailAddress.
• To show the upserted Contact Custom Object records as unmapped in Oracle Eloqua, undo the above field mapping in TIBCO Scribe® Online.
• When upserting Contact Custom Object records in TIBCO Scribe® Online, TIBCO recommends that you define the following fields in your Oracle Eloqua custom objects and map values for these fields, in addition to the ContactEmailAddress field, in your TIBCO Scribe® Online Map:
  • Display Name — Not mapping a Display Name causes an unknown value to be entered for this field after the TIBCO Scribe® Online Solution executes.
  • Unique Code — Not mapping Unique Code fields causes a system-generated value to be entered for this field after the TIBCO Scribe® Online Solution executes.
  • Email Address
• Mapping only the ContactEmailAddress field upserts unusable Custom Object records after a Solution executes, and the records cannot be edited.

TIBCO Scribe® Online API Considerations

To create Connections with the TIBCO Scribe® Online API, the Oracle Eloqua Bulk API Connector requires the following information:

Connector Name	Oracle Eloqua Bulk API
Connector ID	9A84503B-AF2A-489A-AC0A-778EEEB83FC2

TIBCO Scribe® Online Connection Properties

In addition, this Connector uses the following Connection properties, which are case-sensitive:

Name	Data Type	Required	Secured
Company	String	Yes	No
Username	String	Yes	No
Password	String	Yes	Yes

License Agreement

The TIBCO Scribe® Online End User License Agreement for the Oracle Eloqua Bulk API Connector describes TIBCO and your legal obligations and requirements. TIBCO suggests that you read the End User License Agreement.

More Information

For additional information on this Connector, refer to the Knowledge Base and Discussions in the TIBCO Community.