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 Cloud™ Integration - Connect, 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
Connect on-premise	X
Connect cloud	X
Data Replication Apps
Source
Target
On Schedule Apps
Source	X
Target	X
On Event Apps
Source	X
Target	X
Maps
Integration	X
Request-Reply	X
Message

Supported Entities

TIBCO Cloud™ Integration - Connect currently supports the following Oracle Eloqua entities. Select a linked entity name for additional information when using that entity in TIBCO Cloud™ Integration - Connect.

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 Cloud™ Integration - Connect to create a ContactList and your Oracle Eloqua User's settings are not configured for the Advanced Users - Marketing Security Group, TIBCO Cloud™ Integration - Connect 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 On schedule or Data replication apps running at the same time, using the same connection, when using a Connect cloud agent or different Connect on-premise agents.
• On event apps that use an OAuth Connection to write to a target system, because this type of app processes multiple messages concurrently.

If you are encountering connection errors, workaround options include:

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

Selecting An Agent Type For Oracle Eloqua Bulk API

Refer to TIBCO Cloud™ Integration - Connect Agents for information on available agent types and how to select the best agent for your app.

Connecting To Oracle Eloqua Bulk API

1. Select Connections from the menu.
2. From the Connections page select Create to open the Create a connection dialog.
3. SSelect the Connector from the list to open the Connection dialog, 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 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 Cloud™ Integration - Connect page with the following message displays:

   

7. Select Close to return to the TIBCO Cloud™ Integration - Connect 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 Cloud™ Integration - Connect.
• Oracle Eloqua recognizes text fields of up to 32,000 characters. However, in TIBCO Cloud™ Integration - Connect, 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 Cloud™ Integration - Connect.
• 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 app 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 an app to remain actively connected to Oracle Eloqua.

Oracle Eloqua Bulk API Connection As An App Source

Consider the following when using the Oracle Eloqua Bulk Connector as an app 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 flow 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 An App Target

Consider the following when using the Oracle Eloqua Bulk Connector as an app 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 Cloud™ Integration - Connect 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 Cloud™ Integration - Connect 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 flow 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 Cloud™ Integration - Connect.

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 Cloud™ Integration - Connect 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 Cloud™ Integration - Connect 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 Cloud™ Integration - Connect 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 Cloud™ Integration - Connect.
• When upserting Contact Custom Object records in TIBCO Cloud™ Integration - Connect, a best practice is to 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 Cloud™ Integration - Connectflow:
  • Display Name — Not mapping a Display Name causes an unknown value to be entered for this field after the TIBCO Cloud™ Integration - Connect app executes.
  • Unique Code — Not mapping Unique Code fields causes a system-generated value to be entered for this field after the TIBCO Cloud™ Integration - Connect app executes.
  • Email Address
• Mapping only the ContactEmailAddress field upserts unusable Custom Object records after an app executes, and the records cannot be edited.

TIBCO Cloud™ Integration - Connect API Considerations

To create Connections with the TIBCO Cloud™ Integration - Connect 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 Cloud™ Integration - Connect 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 Cloud™ Integration - Connect 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.