TIBCO Scribe® Online Connector For Salesforce Marketing Cloud

Use the TIBCO Scribe® Online Connector for Salesforce Marketing Cloud to create Salesforce Marketing Cloud^® source or target Connections for Integration and Migration Solutions. You can use this Connector to integrate Salesforce Marketing Cloud data, such as subscribers, lists, sends, and send metrics into Dynamics CRM or reporting systems.

Connector Specifications

	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 entities and operations for the Salesforce Marketing Cloud connector. Select a linked entity name for additional information on using that entity with TIBCO Scribe® Online.

Entity	Query	Create	Update	Delete	Upsert
Subscriber (with attributes)	X		X	X	X
List					X
ListSubscriber	X		X		X
Data Extensions (with primary key)	X		X		X
Data Extensions (without primary key)	X	X
ScribeTemplate_ Data Extension (with primary key)	X		X		X
ScribeTemplate_ Data Extension (without primary key)	X	X
Send	X
SentEvent	X
ClickEvent	X
BounceEvent	X
OpenEvent	X
UnsubEvent	X
SurveyEvent	X
SMSMTEvent	X
SMSMOEvent	X

Setup Considerations

Salesforce Marketing Cloud Versions

Salesforce Marketing Cloud can be configured in a number of different ways. TIBCO has tested the Salesforce Marketing Cloud Connector with the following Salesforce Marketing Cloud Editions:

• Advanced
• Enterprise 2.0

While TIBCO believes that the Salesforce Marketing Cloud Connector is compatible with the following Salesforce Marketing Cloud Editions, TIBCO has not tested the Connector against these Editions, nor do we officially support the use of the Connector with Salesforce Marketing Cloud products other than Enterprise 2.0 and Advanced Editions:

• Core
• Enterprise 1.0

Selecting An Agent Type For Salesforce Marketing Cloud

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

Connecting To Salesforce Marketing Cloud

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.
   • URL — The Endpoint Link for your Salesforce Marketing Cloud Connection. If your site has an Enterprise account, the URL is not required. TIBCO Scribe® Online defaults to the S1 Instance, but does not display it. If your Salesforce Marketing Cloud account is on a different Instance, then supply an appropriate Endpoint URL. For information, see Getting Started: Developers and the Marketing Cloud API in the Salesforce Marketing Cloud Technical Library or your Salesforce Marketing Cloud Administrator.
   • Username — The name of the user who has rights to access the Salesforce Marketing Cloud API.
     • For Advanced accounts, the API user and Administrative user are different.
     • For Enterprise 2.0 accounts, this may be the same user as the Administrative user.
   • Password — The password for this Username.
   • Subscriber Primary Key — The type of Subscriber Primary key for your Business Unit. The Subscriber Primary Key is determined when the Salesforce Marketing Cloud account is created. Select either Subscriber Key or Email Address. If you do not know which Subscriber Primary Key your account uses, see your Salesforce Marketing Cloud Administrator.
   • Client ID — The ID of the business unit to which you want to connect.

     Note: For Enterprise 2.0 accounts only, the parent business unit Client ID is different from the Client IDs for each specific business unit. For information about the correct Client ID to specify, see your Salesforce Marketing Cloud Administrator.

4. Select Test to ensure that the Agent can connect to Salesforce Marketing Cloud. 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.

Salesforce Marketing Cloud Connector As IS/MS Source

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 Scribe® Online 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 Scribe® Online only support one filter. For those Connectors you can use either Net Change or one filter on the Filter tab, not both.

Timestamps in Salesforce Marketing Cloud are stored in Central Standard Time. In TIBCO Scribe® Online, timestamps in source filters, in the Net Change Most Recent Record Processed option, and on the Query Preview tab are in UTC time.

Salesforce Marketing Cloud Connector As IS/MS Target

Consider the following when using the Salesforce Marketing Cloud Connector as an IS or MS target.

Batch Processing

Using Batch Processing improves performance, because multiple records are cached, and then stored in the target in one API call. When using Salesforce Marketing Cloud with Batch Processing, set batches to 300 records for the best performance. See Batch Processing.

Data Extensions

Accessing Data Extensions

If you have a Business Unit that contains a large set of Data Extensions, some Data Extensions may not be included when the Connector loads metadata. If the missing Data Extensions are referenced in a Map, errors related to those Data Extensions are generated when your Maps run. Reset metadata for the Connection and run the Map again. Note that you may have to reset metadata more than once.

Mapping Data Extensions

When mapping fields to Salesforce Marketing Cloud Data Extensions, if the target field is a type other than string, the source field must contain data. If a source field is empty or null, errors are generated, when TIBCO Scribe® Online attempts to write the record to Salesforce Marketing Cloud. See the excerpt below from Execution History Details.

Operation failed. Label: Upsert Guests, Name: GuestsUpsert, Message: ErrorCode: 2
Status Message: Errors Occurred
Resolution: Resolution: Log error information and contact Support

To address this issue, build a formula for the field to evaluate each record and determine whether that field is null or empty. If the source field on a record is null or empty, the formula passes a default value to the target field. For example, if you are mapping a date field, such as BirthDate, you could use the formula shown below to pass the default date of 1/1/1900 when BirthDate is empty or null.

IF(ISNULLOREMPTY(Contact.Birthdate), "1/1/1900" , Contact.Birthdate)

Notes On Standard Entities

ListSubscriber

• Use the Update operation to unsubscribe list members.

Notes On Custom Entities

ScribeTemplate_name

ScribeTemplate_name is used to define Dynamic Data Extensions. It defines the naming convention for custom entities also known as Data Extensions.

When retrieving data from a ScribeTemplate data extension, you must filter by the name of the data extension or an error is generated.

Dynamically Creating Salesforce Marketing Cloud Data Extensions

Salesforce Marketing Cloud data extensions allow you to specify your own entities. From TIBCO Scribe® Online, you can dynamically create entities or data extensions for your Salesforce Marketing Cloud data.

1. On the Subscribers tab in Salesforce Marketing Cloud, click Create from the Data Extensions node to create a data extension called ScribeTemplate_name , where name is any name that you choose. This data extension is the template for dynamically creating entities in TIBCO Scribe® Online.
   • You can either create a new data extension or copy an existing data extension.

     Note: The data extension name must begin with ScribeTemplate_ for TIBCO Scribe® Online to recognize it as a template. For example, ScribeTemplate_MyCustomData.

   • Add any fields that you want to include in the new dynamically generated entities. Note that:
     • If you include a primary key for a field within the ScribeTemplate_name data extension, the generated entities support Update, Upsert, and Query operations.
     • Without a primary key, the generated entities support Create and Query operations.
   • Any field not marked as Nullable is a required field when the generated entity is used as a target in TIBCO Scribe® Online.

     Note: See Supported Entities for information about supported operations with Salesforce Marketing Cloud entities.

     For example:

     

2. After you create the data extension template, save it. In TIBCO Scribe® Online, reset the metadata for your Salesforce Marketing Cloud Connection.
3. TIBCO Scribe® Online creates an entity called ScribeTemplate_name that contains all of the fields you defined along with a required field called ScribeDataExtensionName.
4. You can now use the TIBCO Scribe® Online ScribeTemplate_name entity to generate new entities or data extensions with the same schema, except they do not include the ScribeDataExtensionName field. If the entity already exists, TIBCO Scribe® Online updates records for that entity.

   Note: Since the generated entity does not contain the ScribeDataExtensionName field, you cannot use it as a template.

Generating New Salesforce Marketing Cloud Entities

1. Create a Map using the ScribeTemplate_name entity as the target:
   • If the ScribeTemplate_name entity contains a field with a primary key, Upsert and Query operations are supported.
   • If there is no primary key, Create and Query operations are supported.
2. Map the source field that contains the name you want for the new entities to the ScribeDataExtensionName field.

   Note: You can also map a formula to the ScribeDataExtensionName field.
   

3. Map any other fields you want to include in your new entities.

TIBCO Scribe® Online Entity Generation Process

After you map the ScribeTemplate_name entity, new entities are created when you run the Solution. As noted above, the operations available depend on whether the entity contains a field with a primary key.

Primary Key Field

• You do not need to define matching criteria for the Upsert operation; it implicitly matches on the primary key field.
• When TIBCO Scribe® Online processes a source record with a unique name in the field mapped to ScribeDataExtensionName, a new entity is created with that field name value, along with values for the primary key field and other mapped fields.
• When TIBCO Scribe® Online processes another record with the same name mapped to ScribeDataExtensionName, the entity is updated as follows:
  • If a record already exists with the same primary key field value, that record is updated.
  • Otherwise, a new record is added to the entity with the new primary key field value.

No Primary Key Field

• When TIBCO Scribe® Online processes a source record with a unique name in the field mapped to ScribeDataExtensionName, a new entity is created with that field name value, along with values from the other mapped fields.
• When TIBCO Scribe® Online processes another record with the same name mapped to ScribeDataExtensionName, a new record is added to the existing entity.

Generated Entities

Use a dynamically generated entity as you would any other source or target Salesforce Marketing Cloud entity.

• If the entity was created from the ScribeTemplate_name entity with a primary key, it supports Query, Update, and Upsert operations.
• If it was created without primary key, it supports Query and Create operations.
• When using the ScribeTemplate_name entity as a source entity or in lookup operations, specify a filter using the ScribeDataExtensionName field as part of the filter criteria. TIBCO Scribe® Online can then process records from the entity using the name that corresponds to the filtered ScribeDataExtensionName value.

Update Generated Entities

To make changes to the ScribeTemplate_name data extension, update it in Salesforce Marketing Cloud and then reset the metadata in TIBCO Scribe® Online for the Salesforce Marketing Cloud Connection.

New entities created from the ScribeTemplate_name data extension are based on the updated template. However, existing entities are not updated. To update existing entities created using the original template, drop the old entities and recreate them, using Create or Upsert, to incorporate any changes.

TIBCO recommends that you back up the original data for the entities before dropping them.

TIBCO Scribe® Online API Considerations

To create connections with the TIBCO Scribe® Online API, the Salesforce Marketing Cloud Connector requires the following information:

Connector Name	Salesforce Marketing Cloud
Connector ID	6F4141DE-F31C-41E1-9427-6D5F143E4178

TIBCO Scribe® Online Connection Properties

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

Name	Data Type	Required	Secured	Usage
Url	string	No	No
username	string	Yes	No
password	string	Yes	Yes
primarykey	string	Yes	No	Email Address, Subscriber Key
clientid	string	Yes	No

License Agreement

The TIBCO Scribe® Online End User License Agreement for the Salesforce Marketing Cloud 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.