TIBCO Scribe® Online Connector For Salesforce

Use the TIBCO Scribe® Online Connector for Salesforce to replicate or integrate Salesforce Contact, Account, and Order data into other database or reporting systems.

Possible use cases for the Connector for Salesforce include:

• Integrate leads and contacts in Salesforce into your marketing software and execute email campaigns.
• Integrate webinar attendee data into your Salesforce database.

Connector Specifications

This Connector supports Salesforce API Versions 37 through 51.

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

Setup Considerations

Salesforce Organization

To have the Expense, ExpenseReport, ExpenseReportEntry entities enabled, Field Service Lightning functionality must be activated in the Salesforce organization.

Salesforce User Account

Use an existing Salesforce account or request a trial account from www.salesforce.com. For information about configuration, see your Salesforce administrator.

Configure the account to use either:

• A trusted IP address
• A security token

Configure API settings:

• Developer Salesforce accounts have Bulk API enabled by default.
• Trial Salesforce accounts have Bulk API disabled by default.

Make sure that Bulk API is set correctly for your needs. See Bulk API vs Web Services API.

API Usage Limits

Salesforce limits the number of API calls in any 24-hour period for every Salesforce organization.

If you are an administrative user, you can view the number of API requests your organization has used in the last 24 hours, as follows:

1. From the Salesforce User menu, select Setup. The Setup menu displays on the left side of the page.
2. Select Administer > Company Profile > Company Information.
3. The API Requests, Last 24 Hours field displays the current number of API requests along with the maximum available to your organization.

Bulk API vs Web Services API

There are two methods for integrating data into or replicating data from Salesforce: Bulk API and Web Services API. While the Bulk API is slower, this method does use fewer API calls than the Web Services API.

• Salesforce Bulk API is optimized to load large amounts of data with a minimal number of API calls. The Bulk API can process up to 10,000 records in a batch and up to 2000 batches per 24-hour period.

  Verify bulk API is also enabled in Salesforce.

• The Web Services API processes sets of 200 records at a time.

For example, if you select the default batch size of 2000 records, for each batch:

• The Bulk API uses at least three API calls, one to start, one to run, and one to end the batch. For this example, the Bulk API would use only three API calls.
• The Web Services API creates 10 sets of 200 records each, which uses at least 12 API calls. One call to start, one for each 200 record set, and one to end the process.

  Note: If you constantly integrate or replicate large amounts of data, you may want to test both methods to determine which one works best for your site.

  Due to unpredictable Salesforce limits, you may receive errors from Salesforce when you try to use either the Bulk API or Batch Processing. In these cases, you must use the non-batch method to integrate your data.

Selecting An Agent Type For Salesforce

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

Authentication

This connector supports the following authentication methods:

• User Credentials.
• OAuth - Supports Single Sign-on and Multi-factor authentication.

OAuth Authentication

To use OAuth Authentication, a Connected App in Salesforce is required. You can use the TIBCO OAuth App or you can create a new Connected OAuth App in Salesforce. To create a new Connected OAuth App, be sure to enable the following:

• Enable the OAuth Settings checkbox
• Callback URL — For the TIBCO Scribe® Online production environments, use https://online.scribesoft.com/OAuthAuthorizationResponse.aspx and for the Sandbox environment, use https://sandbox.scribesoft.com/OAuthAuthorizationResponse.aspx
• Enable the Require Secret for Web Server Flow checkbox
• Enable the Require Secret for Refresh Token Flow checkbox
• Set Refresh Token Policy as Refresh Token is valid until revoked

Once the app is created, you can find Client Id and Client Secret under the API>Enable OAuth Settings section.

 

Connecting To Salesforce

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.
4. Select and configure an Authentication Type for this Connection.

   Note: If you are connecting to a Salesforce sandbox, replace login.salesforce.com with your sandbox URL in the Salesforce URL field. Be sure to use the appropriate User name for the sandbox. For more information, see your Salesforce administrator.

   • For User Credentials —
     • SalesforceURL — The web address that your site uses to reach the Salesforce web services API.
     • User/Password — The Salesforce user and password. The user name must be in the form of an email address.
     • Security Token — If your site has configured Salesforce to use a Security Token, enter it here. See your Salesforce administrator for more information.
   • For OAuth —
     • SalesforceURL — The web address that your site uses to reach the Salesforce web services API.
   • For Connected OAuth App —
     • SalesforceURL — The web address that your site uses to reach the Salesforce web services API.
     • Client Id/Client Secret — The Salesforce Consumer Key and Consumer Secret.

       Note: Use the TIBCO connect app or create a new app to connect to Salesforce. Client Id and Client Secret are required only when using your own Salesforce Connect App. See the OAuth Authentication section for information on where to find Client Id and Client Secret.

5. Authenticate — Applies to OAuth and Connected OAuth authentication. When the Connection configuration is complete, use the Authenticate button to authenticate with Salesforce. If you are not logged into Salesforce, you are asked to log in. A Salesforce authentication dialog displays. To continue the authentication process enter login credentials, which allows TIBCO Cloud ™ Integration - Connect to access your Salesforce data. Select Close on the confirmation dialog.

   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.

6.  Query Page Size — Specifies the number of query results to return per page. Enter a value between 200 and 2000. The default value is 2000.

   Note: You may want to lower this value if you are querying large records or if you are getting timeout errors.

7. Select one or more options for Solutions using this Connection:
   • Integration or Migration Solutions:
     • IS/MS - Include Deleted Items In Query Results
       • Includes records from the query that are currently in the Salesforce Recycle Bin.
       • Salesforce sets the IsDeleted field to True (1) to indicate deleted records.
       • If a record is deleted in Salesforce, it cannot be updated.

         Note: Records in the Salesforce Recycle Bin are retained for a period dictated by Salesforce and this period may change in time. For more information on this retention period, see TIBCO's Salesforce Recycle Bin And Scribe Solutions KB article.

         TIBCO recommends running your Salesforce Solutions more frequently than this retention period.

     • IS/MS - Use Salesforce Bulk API For Batch Operations
       • Uses the Bulk API for Salesforce target operations.

         Note: You can choose whether to use Batch Processing for each Block in a Map, but to make the Bulk API available, you must enable Bulk API in Salesforce and select IS/MS - Use Salesforce Bulk API For Batch Operations.

       • For more information about integration options for Salesforce Connections, see Salesforce Connector As IS/MS Source.
   • Replication Solutions:
     • RS - Use Salesforce Bulk API For Initial Replication
       • Requires fewer Salesforce API calls.
       • Bulk API must also be enabled in Salesforce.
       • The replication is likely to be slower than if performed using the Salesforce Web Services API.
     • RS - Automatically Refresh Metadata On Every Run
       • Requires more Salesforce API calls, because the metadata must be retrieved from Salesforce.
       • The replication is slower because TIBCO Scribe® Online is waiting for the metadata. Best practice is to leave this option disabled unless you frequently modify your schema in Salesforce, such as, by adding custom fields. Enable it temporarily whenever you edit your Salesforce schema.

         Note: You must manually refresh metadata to see the updated metadata reflected in the TIBCO Scribe® Online user interface.

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.

   Important: When using OAuth Authentication, testing the connection immediately saves the values on the Connection dialog. Selecting Cancel does not restore the prior configuration values.

9. Select OK/Save to save the Connection.

Retry Logic

When a timeout occurs, the Salesforce Connector retries three times. Each time a retry fails, the time between retries is increased by 1 second.

Metadata Notes

Ignored Entities

The following entities are not available through the Salesforce Connector because they must be requested using a specific ID number and cannot be queried using any other method.

Ignored Salesforce Entities
IdeaComment
CollaborationGroupRecord
Vote

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.

Relationships

• Hierarchical relationships, such as grandparent, parent, grandchild relationships are not supported. See Hierarchical Data for examples.
• Target operations support some Parent/Child relationships through the use of virtual fields. See Insert, Update, And Upsert With Relationships.
• Parent/Child relationships are supported for some entities. Review the Notes On Standard Entities section for details on specific entities.

Salesforce Connector As RS Source

Salesforce can be used as a data source for Replication Solutions. The Salesforce Bulk API and the Web Services API are the available methods for replicating data from Salesforce. See Managing TIBCO Scribe® Online RS Solutions.

Recommended Salesforce Entities

When you select the Recommended entities option in a Replication Solution, TIBCO Scribe® Online replicates all entities for which you have the appropriate permissions, including custom entities, that meet the following criteria:

• Support retrieving deleted records, which allows TIBCO Scribe® Online to mark them as deleted in the target datastore.
• Have a SystemModstamp field that can be used to retrieve only new and updated records.

Enabling Salesforce Bulk API

When you select the RS - Use Salesforce Bulk API For Initial Replication check box on the Salesforce Connection dialog, the Salesforce Connection uses the Salesforce Bulk API, rather than the Salesforce Web Services API. The Bulk API can be especially useful for initial replication. It may be slower than the Web Services API, but the Bulk API requires far fewer Salesforce API calls.

Replicating Data Within Salesforce API Usage Limits

Depending on your edition of Salesforce, your Replication Solution may exceed the Salesforce API call usage limit for your Salesforce account.

Managing the Salesforce API call usage limit:

• If your replication reaches the API call limit threshold, it will most likely be during your initial replication run. After the initial replication, your Solution only updates records that have changed, which requires fewer API calls.
• If your replication is stopped by the API call limit, after Salesforce resets your API usage meter, your replication restarts from where it was stopped. Typically, the usage meter is reset every 24 hours. No data is lost if the replication stops and restarts.

Preventing your site from reaching the API call limit:

• Consider using the Salesforce Bulk API feature by selecting the Use Bulk API For Initial Replication option from the TIBCO Scribe® Online Salesforce Connection dialog. This feature optimizes Salesforce for loading large sets of data by allowing TIBCO Scribe® Online to insert a large number of records asynchronously. Using the Bulk API feature is generally slower, but uses fewer API calls. Using the Web Services API is faster, but uses more API calls. See Bulk API vs Web Services API.
• Break your initial replication up into smaller chunks of data. This may be especially helpful for the initial replication. Use the Entities feature of the Replication Solution page. Each day, replicate a limited number of entities, for example, 10 entities on day 1, 10 more entities on day 2, and so on. See Selecting Source Entities For Replication Solutions.
• Balance the frequency of your replications with your available number of API calls. Each time a Solution runs, it generates a certain number of API calls. For example, if a replication generates a minimum of 100 API calls each time it runs, running the replication once an hour in any 24-hour period generates 2400 API calls (24 x 100). Running the same replication every 15 minutes generates 9600 API calls (24 x 4 x 100).
• Only enable the RS - Automatically Refresh Metadata On Every Run option on the TIBCO Scribe® Online Salesforce Connection dialog when you have modified the schema, for example, by adding custom fields. Disable it after the replication is complete to prevent it from refreshing the metadata the next time the replication runs.

For more information, see API usage metering under Implementation Considerations in the Salesforce.com Web Services Development Guide.

Net Change

After the initial replication that creates the tables and adds all the records for the selected or recommended entities in the target datastore, subsequent replications attempt to process only new and updated records. TIBCO Scribe® Online checks the SystemModStamp date field in the target datastore and locates the newest date for each replicated table. That date is then used as filter when querying Salesforce to select only those records that have a date higher than the date in the target datastore. In cases where there are entities that do not have a SystemModStamp date field, all records for those entities are processed each time a Replication Solution is executed.

To ensure that all records are replicated, the Connector subtracts one second from the most recent SystemModStamp date field, which could cause a small number of records to be reprocessed.

For example, if the last record written had a Last Modified Date of 09/04/2018 10:10:20, the next Replication starts with data that has a Last Modified Date of 09/04/2018 10:10:19. Any records that were already processed between 09/04/2018 10:10:19 and 09/04/2018 10:10:20 are processed again.

Deleted Records In Salesforce RS Solutions

• Records deleted in Salesforce are not deleted in the corresponding table in the target replication database. Instead, each record has an associated value in the Scribe_DeletedOn field for the replicated table. The Scribe_DeletedOn field contains a datetime stamp that corresponds to the date and time the record was deleted from Salesforce.

  Salesforce moves deleted records to the Salesforce Recycle Bin, where they are retained for a period of time before being permanently deleted. After records are permanently deleted from the Recycle Bin, they are no longer available to be processed by Replication Solutions. The retention period for records in the Recycle Bin is dictated by Salesforce and may change in time. Best practice is to run your Salesforce Solutions more frequently than this retention period. For more information on this retention period, see TIBCO's Salesforce Recycle Bin And Scribe Solutions KB article.

  For example, if the Salesforce Recycle Bin retention period is 15 days and the time between your Replication Solution runs is greater than 15 days, any records deleted in Salesforce since your last Replication Solution run and more than 15 days ago will not update the SCRIBE_DELETEDON field in your target Replication database tables. For this example, Best practice is to run your Salesforce Replication Solutions at least once every 15 days.

  Note: Replication Solutions can retrieve a maximum of the past 30 days of records from the Salesforce Recycle Bin.

• The process for deleting records in Salesforce is asynchronous. Therefore, the next execution of your TIBCO Scribe® Online Replication Solution may not show a record as deleted, especially if the Replication Solution execution occurs close to the actual time the deletion in Salesforce happened. A later execution of the Replication Solution picks up the deletions after the asynchronous Salesforce job has run.

Custom Entities

During replication, TIBCO Scribe® Online automatically creates any corresponding tables for custom entities in the target datastore. Depending on your subscription, you can select the entities you want to replicate from the Entities area of the Replication Solution page. See Selecting Source Entities For Replication Solutions.

If your Salesforce data contains custom entities:

• If your custom entities exist when the Solution first runs, those entities are replicated and no additional action is required on your part.
• If you add custom entities later, you need to do one of the following: 
  • Select your Salesforce Connection from the Connections page and select Reset Metadata from the Gear menu .
  • Temporarily enable the RS - Automatically Refresh Metadata On Every Run option on the Salesforce Connection dialog.

    TIBCO Scribe® Online includes the new customizations the next time the data is replicated.

• If you select specific entities to replicate, be sure to include the new entity.
• If you are replicating either Recommended entities or All entities, your custom entity is automatically included.
• If you add a custom field to existing entities, the new field is added to the existing replicated table.
  • The new field does not display until you reset the metadata for the Salesforce Connection.
  • When the new field is created in Salesforce, the corresponding field values in the target datastore are set to NULL until you update them in Salesforce and rerun the Replication Solution.

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

Native Query

• This Connector supports the Native Query Block. Use this Block to define queries using the Salesforce Object Query Language (SOQL), which is designed specifically to search Salesforce databases.

  For more information about SOQL, see Salesforce Object Query Language (SOQL).

• The Native Query Block supports aggregate fields used to combine values from multiple fields into one field. This aggregated value can then be used in a separate operation.

  As part of the Native Query, you can define an alias for the aggregation result:

  • If you do not define an alias for an aggregation result, the result is returned in the exprn field.

    For example, the following query specifies two aggregations (sum), but does not define an alias for either result. The results of those aggregations are returned in the expr0 and expr1 fields:

    SELECT sum (Amount), sum (TotalOpportunityQuantity) FROM Opportunity

  • If you define an alias for an aggregation result, the result is returned in a field with that alias name.

    For example, the following query specifies two aggregations (sum) and defines an alias for each result (opp_amount, opp_totaloppqty). The results of those aggregations are returned in the opp_amount and opp_totaloppqty fields:

    SELECT sum (Amount) opp_amount, sum (TotalOpportunityQuantity) opp_totaloppqty FROM Opportunity

MALFORMED_QUERY Fatal Error

Some relationships may cause a MALFORMED_QUERY to occur:

• If you perform a Query operation on an entity that is also specified as a related entity on an inner join, a MALFORMED_QUERY error occurs.

  For example, if you Query Account and also specify Account as a related child entity with a ChildAccounts relationship on an inner join, the following error occurs:

  Message : MALFORMED_QUERY:
  WHERE (Id IN (SELECT ParentId FROM Account))
  The inner and outer selects should not be on the same object type

  This error occurs when you preview the Query or run the Solution.

• If you perform a Query operation where the Notes entity is specified as a related entity on an inner join, a MALFORMED_QUERY error occurs.

  For example, if you Query Account and specify Note as a related child entity with a Notes relationship on an inner join, the following error occurs:

  Message : MALFORMED_QUERY:
  WHERE (Id IN (SELECT ParentId FROM Note))
  Entity 'Note' is not supported for semi join inner selects

  This error occurs when you preview the Query or run the Solution.

• A number of Salesforce entities, such as Case and Task, can have polymorphic relationships. These relationships are seen through TIBCO Scribe® Online, but are not currently supported in Salesforce. Therefore, using these relationships in TIBCO Scribe® Online results in the following fatal error from TIBCO Scribe® Online IS:

  MALFORMED_QUERY: SOQL TYPEOF expressions are not supported in this organization

  If you receive this error, TIBCO suggests that you change your Maps to perform a lookup to find the related record fields that you need by using a Lookup Block.

Batch Processing For Salesforce IS/MS

• When integrating data into a Salesforce target or using Salesforce as a source, TIBCO Scribe® Online provides two methods to process records in batch mode:
  • Salesforce Web Services API with batch processing
  • Salesforce Bulk API
• For Integration Maps, you can set TIBCO Scribe® Online Batch Processing options on target Blocks.
• The Upsert Operation can be used with Batch Processing to reduce the number of records processed.

See Batch Processing for additional information.

Using The Salesforce Web Services API With Batch Processing

To use the Web Services API for Batch Processing, make sure that the IS - Use Salesforce Bulk API option is not selected from the TIBCO Scribe® Online Connections dialog for Salesforce.

Using The Salesforce Bulk API With Batch Processing

Make sure that the IS - Use Salesforce Bulk API option is selected from the TIBCO Scribe® Online Connection dialog for Salesforce and that Batch Processing is enabled in the appropriate operation Blocks in the Map. See Enabling Batch Processing for additional information.

Enabling Batch Processing

After you have specified whether to use the Bulk API, you need to enable Batch Processing and specify the batch size for each Block within the Map.

1. From the Connection dialog for Salesforce select IS/MS - Use Salesforce Bulk API For Batch Operations.
2. Begin designing your Integration Map.
3. For any target Blocks where Salesforce is your Connection, select the Process this operation in batches of check box and specify the batch size.

Salesforce Batch Size

The size of a batch can be between 1 and 10,000 records. The default size is 2000. Larger batches use fewer Salesforce API calls, but, especially if the individual records are very large, Salesforce processing may time out. To prevent timeouts the Connector uses the following Salesforce Bulk API limits to control the batch size:

• Maximum of 10,000 records per batch
• Maximum of 10,000,000 total characters for all of the data in a batch
• Maximum of 10MB of data per batch

If all of the data cannot be sent in one batch Bulk API call because of these limits, the Connector submits the data in multiple batch Bulk API calls that do not exceed these limits.

Best practice is to use the Salesforce Bulk API to integrate data that contains large fields and attachments. See the Bulk API and Web Services documentation on the Salesforce.com website for details about how Salesforce processes large amounts of data.

Salesforce Connector As IS/MS Target

Insert, Update, And Upsert With Relationships

TIBCO Scribe® Online provides virtual fields used to link external IDs during Insert, Update, or Upsert operations for child or parent records. Virtual fields eliminate the need for a Lookup when adding or updating records with relationships to the target, thus reducing the number of Salesforce API calls.

External ID fields are custom fields in Salesforce with the External ID attribute enabled. These fields contain unique record identifiers from an external system, such as an email address or an ID number. Any entity can have one or more of these fields to designate relationships with other entities.

In TIBCO Scribe® Online, if you are working with entities that have relationships established by external IDs:

• Virtual fields are displayed on the Fields tab of the Block Properties dialog for every external ID contained in the Salesforce entity. For example, if an entity has a relationship with three other entities, TIBCO Scribe® Online displays three virtual fields.
• Virtual field names are constructed as follows: 

  <Related Entity Name_Relationship Name_External ID Field>

  For example, if you were querying Accounts and then using an Upsert to update or insert Contacts that are children of those Accounts, the Fields tab of the Upsert Block might display the virtual field as follows: 

  Contact_childcontact_customemailaddress

Use Case

If you want to move marketing Leads and Activities from Salesforce Marketing Cloud into Salesforce and create the relationship between each Lead and its associated Activities, the process is as follows:

1. In Salesforce create the following custom fields with the external ID attribute enabled:
   1. On the Leads entity create a custom field named ET_Lead_ID to contain the original Lead ID from Salesforce Marketing Cloud.
   2. On the Activities entity create a custom field named ET_Activity_ID to contain the original Activity ID from Salesforce Marketing Cloud. This allows you to update the Activity record again after it has been migrated to the Salesforce database.
2. Using TIBCO Scribe® Online migrate Leads from Salesforce Marketing Cloud to Salesforce making sure that the ET_Lead_ID custom field is populated with the Lead ID from the Salesforce Marketing Cloud database. Salesforce creates a unique Lead ID for each lead record, therefore, you cannot use that field for the Salesforce Marketing Cloud Lead ID.
3. Using TIBCO Scribe® Online migrate Activities from Salesforce Marketing Cloud to Salesforce. TIBCO Scribe® Online retrieves the relationship between Leads and Activities with the metadata from Salesforce. Any custom field in Salesforce with an Attribute of External ID on a parent or child entity displays in the Fields tab of the operation Block as a virtual field similar to the following:

   Activities_ChildActivities_ET_Lead_ID

4. When setting up the Insert Block in the Map to migrate Activities, link the source Lead ID on the Salesforce Marketing Cloud Activity entity to the target virtual field that represents the ET_Lead_ID custom field you created on the Leads entity in Salesforce. In this use case, the field name would be:

   Activities_ChildActivities_ET_Lead_ID

   TIBCO Scribe® Online uses the Salesforce Marketing Cloud ID contained in this virtual field to look up the Salesforce Lead ID and put that Salesforce ID in the Activity record in the Salesforce database. This process creates the relationship between each activity and its parent lead.

5. Link the source Activity ID on the Salesforce Marketing Cloud Activity entity to the target virtual field that represents the ET_Activity_ID custom field you created on the Activities entity in Salesforce. This field is used to update the Activity record in Salesforce from Salesforce Marketing Cloud at a later date using the Activity record's former Salesforce Marketing Cloud ID.

Batch Processing

• The batch processing method depends on the options selected when you configured the Salesforce Connection. For information, see Batch Processing For Salesforce IS/MS.
• The Upsert operation is available if the target contains an external ID field or a lookup field.

Upsert Operation

For Salesforce Connections, where you can map to an external ID. a Lookup field, or another ID field, select the Upsert operation to perform the following single-step operation:

• If a matching record is not found in the target, insert a new record.
• If a matching record is found, update the existing record.
• If more than one match is found, none of the matching records is updated and an error is generated.

An external ID field is a custom field created in Salesforce. If you map to multiple external ID fields, the Connector needs to know which ID takes priority when attempting to match records. To indicate which external ID field takes priority, enter the name of the external ID field in the ScribeExternalIDFieldName virtual field. When using an Upsert Block, note the following:

• Only one external ID field is used for the Upsert operation.
• If you have entered the name of the external ID field you want to use in the ScribeExternalIdFieldName virtual field, that ID is used.
• If the ScribeExternalIdFieldName virtual field is blank, the priority for IDs is as follows: 
  1. Oldest External ID field
  2. Lookup fields
  3. ID fields

Case Assignments

• Scribe_CaseAssignmentId field — Links the case assignment to the Salesforce case ID.

  This field is only available in the Create Block.

• If you are using the Bulk API and have configured automatic case assignments, those case assignments are executed successfully, but automatic emails are not sent.
• Creating cases in a batch operation impacts Map performance and causes a larger number of API calls to be executed if the batch contains a large number of case IDs.

  To increase Map performance and reduce the number of API calls executed, do one of the following:

  • Reduce the number of case IDs included in each batch. As the number of different case IDs increases, Map performance decreases.
  • Include an If/Else Block in the Map to sort the records by case ID before executing. By grouping the records by case ID, each group can be processed more efficiently.

Send Operation

• The Send operation is used to make API Calls to Salesforce APIs. The Send operation can be used to support custom calls to Salesforce SOAP, REST, Composite, and other APIs.
• Send supports the Request entity used to build the Http call 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
  [authToken]	"00D1I000002dozd!ARMAQM27CvjgXvYQc3KU0igVKnKPjd50nFe5x45fs MBEbIxFUkHFs12GSI7S4IVsDFBqHiPeO2yjZJWroPnVrgYVDUPeZ85_"
  [endpointUrl]	"https://na73.salesforce.com"
  [organizationId]	"00D1I000001dozdUAA"

  • authToken — The Connector derives the value of the [authToken] variable from either the authentication token or the session ID associated with the authentication method 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] 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

  • endpointUrl — The Connector derives the value of the [endpointUrl] from the Salesforce organization associated with the Connection configuration. This is the Custom Domain URL for your Salesforce organization. Use the [endpointUrl] to construct the URI for the HTTP request. Note that the value of the variable includes "https://". For example, if your domain name is tibcouser.my.salesforce.com, the [endpointUrl] contains https://tibcouser.my.salesforce.com.

    

    
    

  • organizationId — The Connector derives the value of the [organizationId] from the Salesforce organization associated with the Connection configuration. This is the Id of your Salesforce organization. [organizationId] is used wherever the organizationId is specified as a parameter in the Salesforce API documentation.

    

    

    Note: You can provide [organizationId] in the Request.QueryParameters or in the Uri field of Request Entity.

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

Notes On Standard Entities

Order

• Required fields for creating an Order are Account ID, EffectiveDate, and Status. If Account ID is missing, the error message indicates that both Account ID and StatusCode are required. However, StatusCode is not required. Do not map values in the StatusCode field because this generates errors that can be ignored.
• If the Order has OrderItems, the Order must include the PriceBook2ID field. Without this field, OrderItems cannot be added to the Order.

OrderItem

• Required fields for creating an OrderItem are OrderID (parent), PriceBookEntryID, Quantity, and UnitPrice. UnitPrice is retrieved from a PriceBook2, but can be overridden.

Site

• Data for the DailyBandwidthUsed and DailyRequestTimeUsed fields is stored as a decimal, but is interpreted by the Salesforce API as an integer. Returned values may not be as precise as expected, for example, 6.4 is returned as 6.

Miscellaneous

Performance

Under some circumstances, using Salesforce as a source can result in extremely slow processing. To improve performance:

1. On the computer where the Agent is installed, update the Microsoft .NET Framework to v4.7.2.
2. Install any associated Microsoft Windows updates.
3. Restart the Agent service.

Errors

You may receive one of the following record errors when using Salesforce:

Status Code: REQUIRED_FIELD_MISSING || Error: Required fields are missing: XYZ

Resolution: There is a required field in your data that has not been mapped. Check the field mappings in your Map to make sure that all target fields in bold are properly mapped.

Status Code: DUPLICATE_VALUE || Error: Duplicate external id specified: XYZ field = ABC field

Resolution: You are trying to upsert data to a target entity with records that use the same external ID. If you are using the Upsert operation to a Salesforce target, make sure that all external ID fields are unique. This error is also generated if you are using Batch Processing and your source data contains more than one record with the same external ID within a single batch.

INVALID_TYPE_ON_FIELD_IN_RECORD

Resolution: On at least one field, your source and target data are of incompatible data types, such as if you attempt to map an ID of type GUID in the source to an Integer in the target. Make sure that data types are compatible or use one of the Data Conversion Functions.

TIBCO Scribe® Online API Considerations

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

Connector Name	Salesforce
Connector ID	8ADD76FC-525F-4B4B-B79E-945A6A762792

TIBCO Scribe® Online Connection Properties

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

Name	Data Type	Required	Secured	Usage
DeploymentType	string	Yes	No	User Credentials
Url	string	Yes	No
UserId	string	Yes	No
Password	string	Yes	Yes
SecurityToken	string	No	No
QueryPageSize	integer	No	No	Range between 200 and 2000. If not provided, defaults to 2000.
UseBulkApiRS	string	Yes	No	true or false
UseBulkApiSYS	string	Yes	No	true or false
IncludeDeletedItemsSYS	string	Yes	No	true or false
RefreshMetaDataUponReconnect	string	Yes	No	true or false

License Agreement

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