Note: To apply these Salesforce Best Practices, you should be familiar with general Process Development, Building Connectors and the Salesforce Connector components.
Querying Records
When querying records from Salesforce, each record found will be returned as a separate Document and be processed independently. By default, the Query action ignores deleted or archived records. If you would like to return records in these states, check the "Include Deleted" option in the Operation. For users familiar with the Salesforce API, this is the queryAll call.
Using the Like - Filter Operator
There are cases when performing a Salesforce query where you would like to select approximate matches for a filter parameter (fuzzy search). For example, you could have many Account records in your organization that have the term 'ABC' in the Company Name. In a standard query case, you would use the 'Equal To' operator to match the Name to a static value.
Equal To - Example
Query: Select NAME from ACCOUNT where NAME = 'ABC'
Results: ABC
This straightforward query may not yield any results, so the LIKE operator paired with your Expression may be the best strategy. In order to implement a LIKE query, you must use the % character on either side of the Static parameter value; similar to standard SQL syntax.
Like - Example
Query: Select NAME from ACCOUNT where NAME LIKE '%ABC%'
Parameter Definition: %ABC%
Results: ABC, ABC Company, ABC Industries, Company ABC, ABC Corp.
Updating Records
Updating a specific record in Salesforce requires that you pass in the internal Salesforce ID for that record in the update request. This value is typically an 18-character alphanumeric value that looks like this: 0015000000MJtnHAAT. If this value doesn't exist in the source data you will need to look it up from Salesforce.
Note that this ID is slightly different than the 15-character ID you may see in the Salesforce UI or in the browser address bar.
As a best practice, if the other application has a field that can be used to capture an external ID, populate it with the Salesforce ID so you don't have to do a lookup to get the ID in your Process.
To do this, in the Map that maps from the source Profile to the Salesforce Update Profile, use a Map Function that performs a Connector Call to Salesforce. The Connector Call's Operation should do a Query action against the particular object type. Add a Filter to the Operation that you can pass in the key value(s) from the source data as an Input Parameter to limit the results to a single record. The Map Function should return the object's Id field as an Output Parameter. Map this Output Parameter to the Id Element in the destination Profile.
If a particular record does not already exist in Salesforce, the Id Element in the Update Profile will be empty after the Map. If a request without an Id is then sent to the Salesforce Connector, it will throw an error. If this is a possibility in your integration scenario, you should use a Decision Step after the Map to check that the Id is populated in each record before sending the data to the Salesforce Connector.
Upserting Records
The Upsert capability of the Salesforce API is a convenient way to do common "insert-new-or-update-existing" integrations. Instead of having to do a lookup against Salesforce to determine if a given record exists and then perform separate insert or update mappings and calls accordingly, you can simply perform one map to the Upsert request and let Salesforce determine whether it needs to do an insert or update.
Upserts can be used with standard or custom objects that have a custom "External ID" field configured. This External ID field should represent the primary key of the source system or some other uniquely identifying value. This will be helpful when integrating in the opposite direction. If you don't currently have an External ID field, it is recommended you identify one or create a new custom field to use specifically use for the integration. The Import Wizard within the Salesforce Operation retrieves the list of designated External ID fields for each object type for you to choose. You must select an External ID for the object.
| If there isn't a single field in the source data to use as an External ID, see if you can uniquely identify a record by the combination of two or more fields. If so, use a Map Function to concatenate them together and map to the External ID field. |
Depending on an object's relationships as defined in Salesforce, you may have the ability to upsert or at least reference related records by their External IDs as well. For example, you can upsert an Opportunity based on an Opportunity's External ID (e.g. "Order Number") and associate it with an Account record by specifying the Account's External ID (e.g. "Legacy Customer Number"). To enable this, in the Operation configuration select the object and then select a Reference Field. Check to box to "Use External Id for Reference" and select the appropriate Object Type and Ref External Id. Then in your map, you can map some value from your source data and avoid making a Connector call to retrieve the Salesforce internal ID.
Not all objects support the Upsert action. Refer to the Salesforce API Guide for a complete list of supported actions per object.
Using Reference Fields
Reference fields in Salesforce refer to the object fields that can be used to attach a record to a parent or associated object. These reference fields are generally available in the Send Request XML by their name (Ex. AccountId, OwnerId, etc). By default, the request input expects the object's internal ID; however, this ID may not be readily available based on the source data. The Upsert action allows you specify other External ID fields to use in place of the default internal ID. This can save you the need of performing a Salesforce query (Connector Call lookup) to find the internalID based on another value such as Name from your source data.
Example - Upserting an Account record and linking it to a Parent Account based on the Parent Account's Name
- Choose
main External ID custom field for Upsert
- Highlight the ParentId field in the Reference Fields list
- Check 'Use External ID For Reference'
- Ensure Account is selected in the Object Type dropdown
- Choose the External ID custom field (Ex. ExternalID__c) for the Ref External ID
- Map the Account Name from your source data to the ParentID field
When the upsert is performed, Salesforce will accept the name in the ParentID request field and refer to the proper Account's internal ID.
Other Example: Attaching an Opportunity to a Campaign based on Campaign Name or External ID
High Volume API Best Practices
When developing Processes that send/receive high volumes of data to and from Salesforce, refer to these design considerations to ensure that you are optimizing processing efficiency and not exceeding Salesforce API usage limits.
Get Actions
- Use Filters - This will limit the number of inbound records based on key field criteria
- Query multiple objects in one request - In the Query Operation Import Wizard, select associated Parent and/or Child objects (eg. Contact - Parent: Account) if you need to reference this data in your mappings. This will prevent the need for Connector Calls (API web service requests) later in the Process for each individual contact record.
- Query by Last Modified Date - If you are building a synchronization Process that is continually passing updates, add a LastModifiedDate filter for the object in the Operation so you can set a time window in which you would like to grab modified data. This will prevent the need to run entire object data sets through for each Process execution.
- Set a Query Limit - Maximize the number of records you would like returned in one request by setting this number in the Operation. You can then update the retrieved records in Salesforce (eg. Contact > Custom Retrieved_Status field) at the end of your Process flow and prevent the same records from being re-processed in the future by filtering on the custom field.
Send Actions
- Configure the Batch Count - The outbound Salesforce connector operation is automatically configured to batch the XML requests into 1 group of 200 documents. This is the maximum amount allowed in one call by the SFDC API. This will help considerably with API usage statistics.
- Limit the inbound data - Depending on your source for the outbound Salesforce integration, you will want to consider minimizing the number of records processed during a single execution. In a Database integration for example, you should consider only querying a maximum of 1,000 - 10,000 records at a time.
- Use the Upsert Action - The Upsert action will perform the logic to either insert or update a Salesforce record automatically. This will prevent the need for: 1) A preliminary Salesforce lookup to see if the record exists. 2) A unique Salesforce Insert operation. 3) A unique Salesforce Update operation.
Understanding Custom Fields and Objects
One of the great strengths of Salesforce is the ability to easily create custom fields and objects. Because of this, the Boomi Salesforce Connector connects to your Salesforce organization and browses the available interfaces in real time. Custom objects and fields are handled no differently than standard objects and fields. Custom objects/fields can be identified by the __c suffix. If you don't see your custom object or field when importing an object, make sure the security permissions for that object/field allow at least read-only access to the security profile assigned to the user name you're using to connect. If you modify an object in Salesforce after importing it in Boomi, you will need to edit the Operation Component and go through the import wizard again to re-import the recent changes.
Understanding the Salesforce Date Format
Salesforce Date/Time XML Profile elements should be configured with the following format:
yyyy-MM-dd'T'HH:mm:ssZ
Additional Resources
Salesforce API Guide
This page
Other pages
Account
