TIBCO Scribe® Online Connector For Oracle Eloqua

The TIBCO Scribe® Online Connector for Oracle Eloqua enables you to create contact information in Oracle Eloqua with TIBCO Cloud™ Integration - Connect, as well as query campaign and activity information from Oracle Eloqua. Use the Oracle Eloqua Connector to: 

• Integrate Oracle Eloqua information with other business systems, including contact data cards.
• Maintain Oracle Eloqua lists from outside applications.
• Provide your sales team with better information about prospects with your email campaigns.
• Get better sales cycle analytics from initial contact to opportunity and add-on sales, when you integrate Oracle Eloqua with customer data from your CRM, ERP or other data sources.

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 supports Oracle Eloqua API version 1.0 (REST).

	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
Flows
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. For a list of additional operations by entity see Special Operations.

Entity	Query	Create	Update	Delete	Upsert
Activity	X
ActivityBouncebackEmail	X
ActivityEmailClickThrough	X
ActivityEmailOpen	X
ActivityEmailSend	X
ActivityEmailSubscribe	X
ActivityEmailUnsubscribe	X
ActivityFormSubmit	X
ActivityWebVisit	X
Campaign	X
Contact	X	X	X	X
ContactList	X	X	X	X
ContactListMember	X
Custom Objects	X	X	X	X	X
Email	X
Form	X
LandingPage	X

Special Operations

Entity	Operations
ContactListMember	Add Remove

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.

Selecting An Agent Type For Oracle Eloqua

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

1. Select Connections from the menu.
2. From the Connections page select Create to open the Create a connection dialog.
3. Select 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.
   • 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.
4. 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.
5. Select OK/Save to save the Connection.

Metadata Notes

Naming

Connection metadata must have unique entity, relationship, and field names. If your Connection metadata has duplicate names, review the source system to determine if the duplicates can be renamed.

Text Fields

• Oracle Eloqua text data types are represented as string data types in TIBCO Cloud™ Integration - Connect.
• The maximum sizes for text fields are:
  • Small Text Fields — 100 characters
  • Multiselect List Fields — 1,000 characters
  • Custom Object Text Fields — 250 characters
  • Large Text Fields — 32,000 characters

Numeric Fields

• Oracle Eloqua numeric data types are represented as decimal data types in TIBCO Cloud™ Integration - Connect and can have at most 19 digits before and 4 digits after the decimal point.
• 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.

DateTime Fields

• Oracle Eloqua reads mapped source field values as local time, but displays values as UTC time after the operation runs.
• The Oracle Eloqua API stores datetime fields using Unix dates in seconds. The oldest datetime value supported is 12/13/1901 3:45:52 PM or -2147483648 seconds, which is the lower bound of an Int32 field. Dates older than 12/13/1901 3:45:52 PM are not supported and are converted to 12/13/1901 3:45:52 PM.

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 insert 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.

Relationships

Hierarchical relationships, such as grandparent, parent, grandchild relationships are not supported. See Hierarchical Data for examples.

Oracle Eloqua Connection As An App Source

Marketing Activity data is not retained indefinitely. Refer to Oracle Eloqua documentation for data retention policy information.

Filtering

When a datetime is configured on the Query block on the Block Properties Net Change Tab to query for new and updated records, that configuration is treated as an additional filter. The Net Change datetime filter is applied as an AND after any other filters specified on the Block Properties Filter Tab. TIBCO Cloud™ Integration - Connect builds a query combining both the Net Change filter and the filters on the Filter tab. See Net Change And Filters for an example.

Some Connectors for TIBCO Cloud™ Integration - Connect only support one filter. For those Connectors you can use either Net Change or one filter on the Filter tab, not both.

• Only the logical AND operator is supported. The logical OR operator is not supported. If the OR operator is used, TIBCO Cloud™ Integration - Connect generates a Fatal Error and does not process any data.
• Two or more filters using the same field are not supported.

  For example, the following is not supported: Field1 > 100 AND Field1 < 1000

• The LIKE operator supports wild cards. Use the * (asterisk) wild card to match any value.
• 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.
• When filtering with DateTime fields, the filter value is always read as UTC time format. The Oracle Eloqua database stores datetime fields in UTC format, while the Oracle Eloqua interface and TIBCO Cloud™ Integration - Connect Query Preview display these dates in local time.
• The equals operator only returns results if the date contains the value of 000 for milliseconds.

Oracle Eloqua Connection As An App Target

Add And Remove Target Operations

• Add and Remove target operation Blocks are available in flows for the ContactListMember entity.
• Batch processing is supported only for Add or Remove ContactListMember. You must explicitly configure the Add or Remove operation Blocks to use batch processing. See Batch Processing.
• If batch processing fails for any reason, the Add or Remove operation restarts on a record-by-record basis for that batch.

Insert And Update Operations

• Required Value Fields — TIBCO Cloud™ Integration - Connect returns record errors for fields with required values only to the extent that Oracle Eloqua validates those fields.
• Default values
  • If a field with a default value is unmapped on a Create Block, the default value is inserted if the operation is successful.
  • If a Null value from the source is inserted or updated into a mapped field with a default value defined, the default value is inserted/updated in the field if the operation is successful.

Update And Delete Operations

• Matching Criteria
  • Only the logical AND operator is supported. The logical OR operator is not supported.
  • The LIKE operator supports wild cards. Use the * (asterisk) wild card to match any value.
  • In complex matching criteria, two or more filters using the same field are not supported.

    For example, the following is not supported: Field1 > 100 AND Field1 < 1000

Notes On Standard Entities

Activity And Activity Type

• Query Preview — For the Activity entity and all activity-type entities, apply a filter against a specific Contact ID to preview sample data. Unfiltered Query Previews result in timeouts.
• Activity — The Activity entity does not include entries for email bounceback activities. Use the ActivityBouncebackEmail entity to query all pertinent data for this activity type.
• ActivityBouncebackEmail — Use data from a combination of the following fields to get bounceback type information, such as, hardBounce or softBounce:
  • Category
  • SMTPErrorCode
  • SMTPMessage
• 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 Connector.
• ActivityWebVisit — Always shows “0” for Website Visits.
• EmailCampaignID — Always returns NULL in Activity and all activity type entities.

Campaign And Campaign Asset

• Campaign — Due to Oracle Eloqua limitations, a Query Preview in TIBCO Cloud™ Integration - Connect displays Null values in the following fields, even if those fields contain values in Oracle Eloqua:
  • CampaignType
  • Product
  • Region
• Campaign, Email, Form, and LandingPage
  • Filter fields have been limited for these entities to only those for which the Oracle Eloqua API yields reliable results.
  • Permissions field always returns fullControl value, even if user rights are different in Oracle Eloqua.

Contact

• EmailAddress — This is the only field that the Contact entity validates, even if other fields are defined as required.
• Only the DateTime value is converted. No values are cast.
• DateCreated, DateModified — DateTime values for these fields are displayed on the Query Preview tab in Coordinated Universal Time (UTC), but are interpreted by the Oracle Eloqua API as Eastern Standard Time (EST). When using the Contact entity as a source, if one of these fields is used as a filter, match criteria, lookup, or to locate new and updated records, the resulting set of records is incomplete due to the time difference between UTC and EST.

  For example, assume you are querying the Contact entity, with the Process only records created or updated option enabled. You are using the DateModified field to compare against the Most Recent Record Processed date to determine which records to include in the query results. If the value of the DateModified field for a given record is 8:00 AM (UTC), the Oracle Eloqua API interprets this as 8:00 AM (EST), or 13:00 (UTC). Records with a DateModified field between the 8:00 (UTC) and 13:00 (UTC) are not included in the results.

  TIBCO Cloud™ Integration - Connect provides two virtual fields for the Contact entity, DateCreatedUTC and DateModifiedUTC, that can be used instead to filter Contact data. These fields are controlled by TIBCO Cloud™ Integration - Connect. The values contained in these fields are adjusted by the Connector to always be interpreted as UTC datetime data.

ContactList

• Due to API limitations, when an app runs, the following operations fail without returning a record error:
  • Adding a duplicate member
  • Deleting a non-existent member
• The scope of this entity includes both local and global.

ContactListMember

• Adding Contact List Members requires the ContactListID value and either the ContactID or the EmailAddress value. If both ContactID and EmailAddress values are provided, the ContactID value supersedes the EmailAddress value.
• You must explicitly configure batch processing for Add or Remove operations.

Oracle Eloqua Custom Objects

MappedEntityID and MappedEntityType Fields — Used in Oracle Eloqua to link a Custom Object to a Contact record. MappedEntityID is the ID of the Contact record. The MappedEntityType field must be 1. No other types are supported.

For existing flows that create or update a Custom Object record, note the following information for the MappedEntityType field:

• Create —
  • Using any value other than 1, NULL, or not mapped in the MappedEntityType field creates a Custom Object record without a link to the Contact record.
  • Using a valid Contact ID in the MappedEntityID field and 1, NULL, or not mapped in the MappedEntityType field links the Custom Object record to the Contact record.
• Update —
  • Using any value other than 1, NULL, or not mapped in the MappedEntityType field generates a record error
  • Using a valid Contact ID in the MappedEntityID field and 1 or not mapped in the MappedEntityType field links the Custom Object record to the Contact record.
• Create or Update -
  • Using an invalid Contact ID in the MappedEntityID field generates a record error.
  • MappedEntityType value is ignored if MappedEntityID is not mapped.

For new flows that create or update a Custom Object record, only the MappedEntityID field containing a Contact ID is required to link a Custom Object record to a Contact record.

Query — Fields that are not populated in Oracle Eloqua are returned as NULL.

DateTime Fields —

• Datetime fields visible in the Oracle Eloqua User Interface display in Eastern time, are stored by Oracle Eloqua in UTC, but are interpreted by TIBCO Cloud™ Integration - Connect as Eastern time for backwards compatibility with flows built against the Oracle Eloqua SOAP API. In a future release, TIBCO Cloud™ Integration - Connect will read these datetimes as UTC time.
• For each Oracle Eloqua datetime field, TIBCO Cloud™ Integration - Connect has a corresponding virtual datetime field that stores and interprets time in UTC. The naming convention for these virtual fields is <OriginalFieldName>_UTC.

Filter, Lookup, and Match Criteria —

• If an ID field is included in a filter configured with multiple fields, only the ID field is used.
• Only the equals (=) operator is supported.
• If you use both an original Oracle Eloqua datetime field and a virtual datetime field ending _UTC in a filter, the _UTC datetime field takes priority.

TIBCO Cloud™ Integration - Connect API Considerations

To create Connections with the TIBCO Cloud™ Integration - Connect API, the Oracle Eloqua Connector requires the following information:

Connector Name	Oracle Eloqua
Connector ID	D734F245-7506-415F-84E0-C2A069292543

TIBCO Cloud™ Integration - Connect Connection Properties

In addition, this Connector uses the Connection properties shown in the following table.

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

More Information

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