Salesforce Integration Guide


The Salesforce connector connects seamlessly to any native Salesforce application, including Sales Cloud and Service Cloud as well any Custom Cloud or Force.com. As a Salesforce user, you can use the Salesforce connector to integrate with any other cloud or localise application.

 

User Guide Articles

Here are some links to our User Guide, which you may find useful when using and configuring the Salesforce Connector.

 

Process Library Examples

 

Common Scenarios

 

Scenario 1: 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.

 

Scenario 2: 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 does not 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.

 

Scenario 3: 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 is not 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.

 

Scenario 4: Deleting Records

A few things to keep in mind when deleting records.

You must always supply the Salesforce internal Id value. External IDs can't be used.

Known Issue (BOOMI-8454: Salesforce Connector throws an exception after successful delete when multiple IDs are used): When wishing to delete multiple records, the request document sent to the Salesforce connector must contain only one Id per document. (This must be done even though the "Id" element in the request profile is configured as Max Occurs=Unbounded by default.) If multiple Ids are present in a single document, the records will actually be deleted in Salesforce, however the connector will error with the "Number of results does not match number of SObjects" message when processing the response. To avoid this, use a Data Process step to split the request data. This can be done before the Map step to the Salesforce delete profile, or afterward (splitting the Delete profile XML on the OBJECT/DeleteIds/Id element.

 

Scenario 5: 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:

 

Send Actions:

 

Scenario 6: 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.

 

Scenario 7: 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

 

Scenario 8: How to use the OR logical operator between two objects in Salesforce

Question:

It appears that the AND logical operator works between two objects, ie, parent to grandchild, but the OR logical operator does not seem to work. Is it available? How does it work? Are there any constraints/limitations?

 

Answer:

The SOQL query is automatically generated based on the configuration of the filters.

Currently the filters do not allow expressions fields from different objects within the same logical sub-group.

As a workaround, you may need to implement two separate connectors, one that reads from the parent object and then another that reads from the other object. Then use a Decision step to filter the data.

Based on Salesforce documentation: http://www.salesforce.com/us/developer/docs/api/Content/sforce_api_calls_soql_relationships.htm#i1422304,

It says "Any query (including subqueries) can include a WHERE clause, which applies to the object in the FROM clause of the current query. These clauses can filter on any object in the current scope (reachable from the root element of the query), via the parent relationships."

 

Scenario 9: How to Retrieve Attachments in Salesforce (Full Example)

Please visit the following link to review this scenario: How to Retrieve Attachments in Salesforce (Full Example).

 

Scenario 10: How to use the Batch Results Option on SFDC Query Operations

Please visit the following link to review this scenario: How to use the Batch Results Option on SFDC Query Operations.

 

Common Errors

Salesforce Integration Guide: Common Errors
 

FAQ

How do I generate a security token in Salesforce developer account?

In order to access Salesforce via Boomi Enterprise Platform, you must replace your current password with a combination of your password and a security token like this:

     MypasswordMytoken

If and when you change your password, you will need to request a new security token.

To request a security token:

  1. Log into your Salesforce account as the user for whom you wish to reset the token.

  2. View your User Profile > Settings > My Personal Information, Reset My Security Token. Click Reset Security Token button to triggers an email containing the new security token.

  3. Carefully copy and paste (do not copy any trailing spaces), append to your Salesforce password, and paste into the Salesforce connection's Password field.

 

Is there a way to monitor the number of API calls that are made while accessing an object from Salesforce?

Per the Salesforce API guidance (which is accessible via link from the Boomi guidance on Salesforce connector), the Salesforce query result object contains up to 500 rows of data by default. If the query results exceed 500 rows, then the client application uses the queryMore() call and a server-side cursor to retrieve additional rows in 500-row chunks. You can increase the default size up to 2,000 in the QueryOptions header, as described in Changing the Batch Size in Queries. For more guidance, you can refer to the Salesforce API Guide.

The Boomi guidance at the following link shows the standard Get fields which include a field for batching results and setting the batch count: Salesforce operation.

So, if you set the batch count higher, you can figure out how many API calls will be made, by dividing the number of records (e.g. 1.6 million) by the batch count setting.

See also the Salesforce developer guide for how to monitor API traffic: Developer Guide - Section: Using the API with Salesforce Features > Implementation Considerations > Monitoring API Traffic: https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/implementation_considerations.htm
 

The import did not allow for the selection of the child object.  Can a SFDC upsert can be performed on a parent and child objects in the same Salesforce connector operation?

Per Salesforce’s API, “you can process records for one more than object type in an create() or update() call, but all records must have the same object type in an upsert() call.”

Therefore a separate upsert operation must be implemented for each object. Therefore, it’s not possible to do an upsert on 2 different objects (even if they are parent-child) in the same connector operation.

https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/sforce_api_calls_upsert.htm

 

What is the filterValue that I should specify to fetch the records whose EndTime is Not Null in Salesforce?

In the Query filter section of Object Event, create a filter criteria similar to:

Filter Name: EndTime

Field : EndDateTime

Operator : Not Equal To

 

Then in the Connector Parameter section, specified the following:

Input : EndTime

Type : Static

Static Value : 'null'

 

Why am I Unable to see Action or Object picklist after connecting to SF sandbox?

Change the connection URL from:

https://test.salesforce.com/services/Soap/u/31.0

to a previous version:

https://test.salesforce.com/services/Soap/u/30.0

 

Save the connection, re-import or re-create the object, until you see the Action or Object in the pick list.

 

Why can I not see a particular field that I know exists in Salesforce?

Verify that the user configured in the connector has the appropriate permission to see that field.

 

Also, please check what version of the Salesforce API you are using. Is there a more current version (44.0 vs. 38.0)?

If so, modify the URL in the Salesforce connection with the new API version. For example: https://www.salesforce.com/services/Soap/u/44.0

After saving this change and re-importing the profile, check the object for the necessary field.

 

How do I sync the process when a new custom field is added in Salesforce?

  1. Open the Salesforce operation component
  2. Use the Import button to open Salesforce Import wizard.The wizard will guide you on how to complete the import asking for connection,Salesforce object,fields etc.
  3. Save the operation component and re-save the process.Finally redeploy the process for the changes to take effect.

 

How do I call a Salesforce Apex webservice class?

To call a custom Apex class exposed as a web service, use the Apex Connector instead of the Salesforce Connector.

 

How do I send/load data from Salesforce using the Bulk API?

There are two options that you need to look at:

  1. Use Bulk API – to tell the connector to load data to Salesforce using Bulk API
  2. Batch Count – the maximum number of records in a batch

To have your data upload with Bulk API, you just need to check on the “Use Bulk API” checkbox and specify the Batch Count (the default value is 200) in the operation configuration screen. The Boomi Salesforce connector will handle everything for you automatically at the backend including preparing the data into batch according to the Batch Count.

As there is no option to turn on serial model, some options to address lock contention in Salesforce could be:

Please note that the Salesforce connector only supports the BULK API option in parallel mode.

 

How do I Identify the Salesforce record processed within Boomi?

In order to identify the SF record processed within Boomi, you may have to manually search for the record/data from the XML profile returned by the Salesforce connector. You will need to use the record ID, or some other field in Salesforce that uniquely identifies the record.

Alternatively, if you configure the connector's "Tracked Fields", then you would be able to see the recordID in the process reporting data. For reference:

http://help.boomi.com/Boomi Enterprise Platform/GUID-103F06E6-94BF-472A-9C50-F3780CE5B497.html

http://help.boomi.com/Boomi Enterprise Platform/GUID-C84D1FEF-BD90-46CE-BFD2-33CE720572EE.html

 

How do I construct complex SOQL using the Salesforce REST API?

Salesforce REST API is needed to be used in order to execute a complex SOQL.

Use HTTP Client with GET action in order to use REST API to login to Salesforce. Connection URL should look something similar to this: https://cs18.salesforce.com/services/Soap/u/44.0

You should pass SOAPAction: login in Request Headers.

 

The request profile should be similar to this:

<?xml version="1.0" encoding="utf-8" ?>
<env:Envelope xmlns:xsd="
http://www.w3.org/2001/XMLSchema
"    xmlns:xsi="
http://www.w3.org/2001/XMLSchema-instance
"    xmlns:env="
http://schemas.xmlsoap.org/soap/envelope/
">    

<env:Body>      
<n1:login xmlns:n1="urn:partner.soap.sforce.com">          
<n1:username>{1}</n1:username>          
<n1:password>{2}{3}</n1:password>
</n1:login>
</env:Body>
</env:Envelope>

The Login Response profile will return a sessionID which will be used as Authorization value in the subsequent calls.

Build your SOQL and pass it as a parameter into an HTTP Client Connector:

 

The process should look similar to this:

User-added image

 

How do I connect to Salesforce REST API with OAuth 2.0?

Please see How to Connect to Salesforce REST API with OAuth 2.0.