TIBCO Scribe® Online Connector For Marketo
The TIBCO Scribe® Online Connector for Marketo connections is secured using OAuth 2.0 and supports create, update, delete, query, and upsert operations on Company, Lead, Opportunity, OpportunityRole, SalesPerson, and Custom Objects. The connector also supports queries for Activities, Activity Lists, and Custom Activities. You may also Add and Remove Leads to Lists and configure customized HTTP requests to your Marketo instance.
Refer to TIBCO Scribe® Online Connectors For Marketo for information on when to use the Marketo SOAP Connector and when to use the Marketo Connector.
Connector Specifications
This Connector supports version 1.0 of the REST API.
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 entities and operations for the Marketo Connector. Select a linked entity name for additional information on using that entity with TIBCO Cloud™ Integration - Connect. For a list of additional operations by entity see Special Operations.
Standard Operations
Entity | Query | Create |
Update | Delete | Upsert |
---|---|---|---|---|---|
X |
|
|
|
|
|
X |
|
|
|
|
|
X |
X |
X | X | X | |
X |
X |
X |
X |
X |
|
|
|
|
|
|
|
X |
X |
X |
X |
X |
|
X |
X |
X |
X |
X |
|
X | X | X | X | X | |
Custom Activities |
X |
X |
|
|
|
X |
X |
X |
X |
X |
Special Operations
Entity | Operations |
---|---|
List |
-Add -Remove |
Request |
-Send -Add |
-
There is an Add block that only supports the List entity. That block is used to add leads to Marketo lists.
-
The second Add block is used in conjunction with the Send block to support Hierarchical data allowing you to add multiple nested records in a single parent record. The hierarchy can extend down multiple levels, for example, a record containing a Country or parent, States or children, and Cities within each state or grandchildren.
The connector supports two Add blocks that are used in different circumstances.
Setup Considerations
Marketo Editions
Marketo Spark Edition is not supported.
Marketo User Account
To connect to Marketo via the REST API you must log into Marketo and locate or create the following:
- REST Identity URL, located under Admin > Web Services in the REST API section.
- API Only Role. If you are using Custom Objects, be sure to enable the Read-Write Custom Objects option for this role. See Edit An Existing Role in the Marketo Help for instructions.
- API Only User associated with the API Only Role
- Custom Service
Creating the Custom Service generates the Client ID and Client Secret used in TIBCO Cloud™ Integration - Connect to configure your Marketo Connection. View the details of the Custom Service to locate the Client Id, and Client Secret.
API Usage Limits
Marketo limits the number of API calls in any 24 hour period and any 20 second window for every organization. Refer to the Marketo REST API documentation for exact limits.
To view the number of API calls your organization has used, log into Marketo and navigate to Admin > Web Services. If the API call limit is exceeded, the API returns an error of code 606.
Reducing API Usage
When performing an Update or a Delete operation, use the ID or other unique field as the match criteria. If you do not use unique data to match the record being processed, TIBCO Cloud™ Integration - Connect must query the Marketo API more than once to determine which record to Update or Delete. Multiple queries also reduce performance. Refer to Notes On Standard Entities below for a list of unique fields for each entity.
Batch Processing
Best practice is to enable Batch Processing on operation Blocks when using Marketo as a target. This reduces the number of API calls by grouping records into batches before sending them to the API instead of sending each record individually. When using Marketo with Batch Processing, Marketo allows batches of up to 300 records. If you request processing in batches of 3000, TIBCO Cloud™ Integration - Connect creates 10 batches of 300 records each. Batch Processing also improves performance. See Batch Processing.
Selecting An Agent Type For Marketo
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 Marketo
- Select Connections from the menu.
- From the Connections page select Create
to open the Create a connection dialog.
- 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.
- Marketo Identity URL— The complete URL (REST endpoint) for this account. Locate this URL in Marketo under Admin > Integration > Web Services in the REST API section.
- Client ID — The ID associated with this Marketo Connection. Located on the Marketo Custom Service Details dialog.
- Client Secret — The secret associated with this Marketo Connection. Located on the Marketo Custom Service Details dialog.
- 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.
- 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.
Query
A filter is required on the Filter tab for all queries on all entities. If no filter is included, an error is generated.
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.
DateTime Fields
Marketo DateTime fields do not include milliseconds. If you are using the Process only records created or updated since last run option when querying the Marketo REST API, TIBCO Cloud™ Integration - Connect may end up reprocessing some records on subsequent executions of a flow, because it begins with the DateTime of the most recent record processed.
Boolean Fields
When using Marketo as a source, if a Boolean is requested but is not returned from the Marketo REST API, TIBCO Cloud™ Integration - Connect assumes that the value is false.
When using Marketo as a target, only True and False, or 1 and 0 are accepted. Using Yes or No causes a fatal error in the app execution.
NULL Values
Filtering on fields that contain NULL values is not supported, nor is sending NULL values for certain fields.
When a flow attempts to filter on a field containing a NULL value, record errors, such as the one shown below, are generated.
Error description: Operation failed. Label: Delete Opportunity, Name: OpportunityDelete_2, Message: ErrorCode:, ErrorMessage:The following exception occured in the Marketo REST connector: Marketo Error Code: 1003, Error Message:Value for requried field 'externalcompanyid' not specified At Line 614 Called by GetMultipleLeads. Current Api Control Rate is: MaximumSpeed.
When a flow attempts to Insert or Update a record into Marketo that contains NULL values, if the field does not accept NULL, record errors are generated. For example, when creating an Opportunity in Marketo , if the name field is set to NULL the following error is generated:
Failed to sync opportunity.
To address this issue, build a formula for the name field to determine whether the field is set to NULL and replace it with a blank, because blank is accepted by the REST API .
IFNULLUSE( Opportunity.name, " " )
Field Descriptions
When working with Marketo entities, associated fields do not display a description in the TIBCO Cloud™ Integration - Connect Fields tab in operation Blocks.
Marketo Connector As An App Source
When using the Marketo Connector as a source, you may encounter the following issues:
- Marketo Smart Lists are not supported. However, to use your Marketo data with TIBCO Cloud™ Integration - Connect, you can convert a Smart List to a Static List.
- Smart Lists are supported when using HTTP calls to access Marketo via the API. See the Send Operation section for additional information.
- Parent/child relationships are only supported for Activity and Custom entities.
Net Change
When querying the Marketo API, records are not returned in order by date. If the Net Change option is enabled on the Query block to return only new and updated records, the Marketo Connector must request all records, sort them by date, and then locate only the new and updated records. This process takes place in memory and affects agent memory requirements. If you are using a Connect on-premise agent and the server where that agent is installed does not have enough memory, it may appear that there is a memory leak due to the volume of records being sorted.
Filters, Match Criteria, Or Lookups
- Only the equals (=) operator is supported for all entities.
- The greater than (>) operator is supported only for some fields.
- ANDs are supported only when a combination of Dedupe Fields is required to identify a specific record.
- ORs are supported only for filtering for multiple values in the same field, such as, ID=10 OR ID=11 OR ID=12.
Refer to Notes On Standard Entities for additional filtering information for specific entities.
Relationships
- Hierarchical relationships, such as grandparent, parent, grandchild relationships are not supported. See Hierarchical Data for examples.
- Parent/Child relationships are supported where noted for some entities. Review the TIBCO Scribe® Online Connector For Marketo section for details on specific entities.
Marketo Connector As An App Target
When using the Marketo Connector as a target, you may encounter the following issues:
- When using Marketo with Batch Processing, Marketo allows batches of up to 300 records. If you request processing in batches of 3000, TIBCO Cloud™ Integration - Connect creates 10 batches of 300 records each.
- Searchable fields can be mapped, however, best practice is to also map a unique field. Mapping a unique field, such as the Marketo ID reduces the number of API calls required to locate the specific record that needs to be updated.
Dedupe Fields
Marketo entities can have one or more fields marked as dedupe fields. Dedupe fields are used by Marketo to eliminate duplicate records based on the unique data contained within the field, such as an ID or an email address. Dedupe fields can be used to locate a specific record when using Update, Upsert, or Delete operations. For some entities and operations, dedupe fields or combinations of dedupe fields are required. Refer to the Notes On Standard Entities for additional information on specific entities.
Upsert
The Upsert operation requires the use of dedupe fields to identify and update existing records. If dedupe fields are not used, all records are treated as new records and are created in the target, which could result in duplicates.
Send Operation
-
The Send operation is used to make API calls to the Marketo API. It can be used to support custom calls to the Marketo REST APIs.
-
Send supports the Request entity used to build the HTTP calls to the API.
-
Send works in conjunction with the Add Block to include Headers, Cookies, or Query Parameters.
-
The Send and Add operations support the use of the following variables or tokens to make configuring customized API calls easy and robust:
Name Example Value [endpointUrl] https://060-vve-010.mktorest.com/rest [authToken] 60f4394b-ebd2-4a2f-b613-2a1ac107aaff:ab
[organizationId] 060-VVE-010 - endpointUrl — The Connector derives the value of the [endpointUrl] from the Marketo Organization associated with the Connection configuration. This is the Custom Domain URL for your Marketo organization. Use the [endpointUrl] to construct the Uri for the Send block. Note that the value of the variable includes https://. The value of endpointUrl is https://060-vve-010.mktorest.com/rest.Note: You can provide [endpointUrl] in the Uri field of the Request Entity.
- authToken — The Connector derives the value of the [authToken] variable from the authentication token configured in the Connection. This token is used to perform the POST, GET, and any other HTTPVerb calls using the Request entity. Note: The authToken is supported only for Marketo REST APIs.Note: The [authToken] must be provided in the Request Header for any HTTP request.Note: If the Authorization Token is provided explicitly, instead of using the [authToken] variable, and the token is refreshed, an error similar to the following is generated:
Operation failed. Label: Send Request, Name: RequestSend, Message: Forbidden: Error in calling Operation Send Http call failed with StatusCode 403 - Forbidden. Response Body: Bad_OAuth_Token.
- organizationId — The Connector derives the value of the [organizationId] from the Marketo organization associated with the Connection configuration. This is the Id of your Marketo organization. [organizationId] is used wherever the organizationId is specified as a parameter in the Marketo API documentation.Note: You can provide [organizationId] in the Request.Headers or in the Uri field of Request Entity.
- endpointUrl — The Connector derives the value of the [endpointUrl] from the Marketo Organization associated with the Connection configuration. This is the Custom Domain URL for your Marketo organization. Use the [endpointUrl] to construct the Uri for the Send block. Note that the value of the variable includes https://. The value of endpointUrl is https://060-vve-010.mktorest.com/rest.
- The Send block, the Add block, and the Request entity are based on the functionality in the HTTP Connector. For more details see the HTTP Connector help.
- The CreateDuplicate action is supported via the Marketo API using the Send block and the Request Entity.
Notes On Standard Entities
Activity
Query
- Filters support the greater than (>) operator only for the activityDate field.
- Filtering by ActivityType is required when querying the Activity entity. You can only filter or join on up to ten Activity Types at any given time.
- Only inner joins on the Activity entity are supported. If outer join is selected, a filter is required.
- You can specify up to ten related entities. However, for any Query, all related entities must be an inner join.
- Deleted or Historical records are never returned for the Activity entity.
- The attribute field contains an array of values and can be accessed only by using the Send Operation to send an HTTP Request to the Marketo API.
ActivityTypes
- The list of ActivityTypes varies based on your Marketo configuration. TIBCO Cloud™ Integration - Connect displays any ActivityType available via the Marketo API.
- Reset the metadata for the Marketo Connection to display new ActivityType entities in TIBCO Cloud™ Integration - Connect.
- Filters support the greater than (>) operator only for the activityDate field.
Company
- Company is not supported for CRM-enabled subscriptions. If your Marketo account is a CRM-enabled subscription, the Company entity does not display in TIBCO Cloud™ Integration - Connect.Note: To display the Company entity in TIBCO Cloud™ Integration - Connect, contact your Marketo Account Representative about disabling CRM.
- Upsert Operation — Requires the externalCompanyId dedupe field. See Dedupe Fields.
Lead
- Query — Returns a maximum number of 1000 records unless filtered by one of the following fields:
- ListId
- LeadProgramId
- UpdatedAt
Note: If the maximum is exceeded, the operation fails with the following error:Too many results match the filter.
- Upsert —
- The ExternalIDFieldName target field is a virtual field used to indicate which field should be used as Match Criteria when using Upsert with Lead data. On the Fields tab enter the field name of the field to match in the ExternalIDFieldName target field.
- If you try to UpsertLead data into Marketo where the source contains the MarketoLead ID, the operation fails with the following error:
Error description: Operation failed. Label: Upsert LeadRecord, Name: LeadRecordUpsert, Message: 20103 - Lead not found
Filter, Match Criteria, Or Lookup
- Supports the greater than (>) operator for the updatedAt field.
- Filtering by the listName field is not supported for list names containing special characters. List names containing special characters cannot be found during Query operations.
- Some fields displayed in the Filter, Match Criteria, or Lookup drop-downs cannot be used to filter data. Use the Preview tab to check for errors on filter fields similar to the following:
Marketo Error Code: 1011, Error Message: Lookup field <field name> not supported..."
List
Use the List entity to add and remove Leads from Marketo Lists.
- You cannot query on a List because the List entity is not available from the Query Block.
- LeadKeyValue is the ID of the lead you want to add to or remove from the list. If the Lead ID does not exist, a record error occurs.
- ListKeyValue field must be the name or the ID of the list you want to process. List names containing special characters are not supported because they cannot be found during Add or Remove operations.
- Use the Add Block to add Leads to an existing list.
The Add Block is similar to a Create Block. See Create Block for information about configuring and using Add.
- Use the Remove Block to remove Leads from an existing list.
The Remove Block is similar to a Delete Block. See Delete Block for information about configuring and using Remove.
Note: If you choose only one match criterion when using a Remove List operation, an input error is generated when the flow executes, but there is no information in the message indicating that there are not enough match fields. Make sure that Remove Blocks contain both LeadKeyValue and ListKeyValue as match fields.
Opportunity
- Opportunity is not supported for CRM-enabled subscriptions. If your Marketo account is a CRM-enabled subscription, the Opportunity entity does not display in TIBCO Cloud™ Integration - Connect and the following error is logged in the Verbose logging.
"success":false,"errors":[{"code":"1018","message":"Opportunity API disabled"}]
Note: To display the Opportunity entity in TIBCO Cloud™ Integration - Connect, contact your Marketo Account Representative about disabling CRM. - Filtering by date is not supported for Opportunity. Therefore, you cannot limit records to new and updated records by enabling the Process only records created or updated since last run option when querying the Marketo API.
- Upsert Operation — Requires the externalOpportunityId dedupe field. See Dedupe Fields.
OpportunityRole
- OpportunityRole is not supported for CRM-enabled subscriptions. If your Marketo account is a CRM-enabled subscription, the OpportunityRole entity does not display in TIBCO Cloud™ Integration - Connect and the following error is logged in the Verbose logging.
"success":false,"errors":[{"code":"1018","message":"Opportunity API disabled"}]
Note: To display the OpportunityRole entity in TIBCO Cloud™ Integration - Connect, contact your Marketo Account Representative about disabling CRM. - Filtering by date for OpportunityRole is not supported. Therefore, you cannot limit records to new and updated records by enabling the Process only records created or updated since last run option when querying the Marketo API.
- Upsert Operation — Requires the externalOpportunityId dedupe field. In addition to the externalOpportunityId field, map the leadId and role dedupe fields to eliminate extra API calls. See Dedupe Fields.
SalesPerson
- SalesPerson is not supported for CRM-enabled subscriptions. If your Marketo account is a CRM-enabled subscription, the SalesPerson entity does not display in TIBCO Cloud™ Integration - Connect.Note: To display the SalesPerson entity in TIBCO Cloud™ Integration - Connect, contact your Marketo Account Representative about disabling CRM.
- Upsert Operation — Requires the externalSalesPersonId dedupe field. See Dedupe Fields.
Custom Objects
- When defining Custom Objects and fields in Marketo, make the API names for objects and fields the same as the User Interface display names for objects and fields to prevent confusion when working in TIBCO Cloud™ Integration - Connect. When the TIBCO Cloud™ Integration - Connect Connector displays Marketo Custom Objects and fields, it uses the API names not the display names shown in the Marketo User Interface.
- Filtering by date for Custom Objects is not supported. Therefore, you cannot limit records to new and updated records by enabling the Process only records created or updated since last run option when querying the Marketo API.
- Parent/child relationships are supported for Custom entities.
- Upsert Operation — For Custom Objects created in Marketo, ID and up to three dedupe fields are specified when you create the object. All dedupe fields and link fields, such as LeadId and CompanyId, are required for Upsert. See Dedupe Fields.
TIBCO Cloud™ Integration - Connect API Considerations
To create connections with the TIBCO Cloud™ Integration - Connect API, the Marketo Connector requires the following information:
Connector Name |
Marketo |
Connector ID |
B806E821-BECF-4B43-AC66-1B2E20B9241E |
TIBCO Cloud™ Integration - Connect Connection Properties
In addition, this Connector uses the Connection properties shown in the following table.
Name | Data Type | Required | Secured | Usage |
---|---|---|---|---|
Identityurl |
String |
Yes |
No |
|
client_id |
String |
Yes |
No |
|
client_secret |
String |
Yes |
Yes |
|
License Agreement
The TIBCO End User License Agreement for the Marketo 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.