Dell Boomi AtomSphere

Salesforce operation

The Salesforce operation defines how to interact with your Salesforce account.

The operation represents a specific action (Query, Create, Update, Delete, etc.) to be performed against a specific Salesforce record type or object (Account, Opportunity, Contact, etc.). Create a separate operation component for each action/object combination required for your integration. Not all actions are available for every object.

The Salesforce operation supports the following actions:

  • Get: Query

  • Send: Create, Delete, Merge, Update, Upsert, convertLead (available only in version 15 and more recent versions of Salesforce, and only for Lead objects).

NOTE: Contact your Salesforce representative to learn about the API field-level requirements for Salesforce and how to access additional Help documentation.

Query

This action, the only Get action available for the Salesforce connector, returns zero-to-many object record documents from a single Query request based on zero or more filters. As shown in the following image, the bottom half of the operation component page contains configuration options to choose the fields to return, add filters to limit the results, and select sorting options.

Operation component page.

The Import Wizard builds an object list. After you select an object, the Wizard logs into Salesforce and creates an object tree from which you can select parent and child objects to import. For each object, you can access a parent of the child object and then apply the configuration to the parent for the query execution.

  • Use Salesforce to define multiple expressions and group them into logical sub-groups to create sophisticated query logic. The operator at the logical group level defines how the multiple expressions and/or logical sub-groups within that logical group are evaluated.

  • Use the In and Not In filter operators in a Query request to generate IN and NOT IN SOQL comparisons as part of the WHERE clause. Specify the input parameter as a comma-separated list of values. For example, to find all objects having a ‘state’ field value of ‘pa’ or ‘nj’, set up a filter for the ‘state’ field using the In operator. Specify the input parameter as pa,nj. The WHERE clause generated in SOQL is WHERE state IN ('pa','nj'). For more information, see the Salesforce developer documentation about “comparison operators” in the SOQL and SOSL Reference Guide.

  • Use the Includes and Excludes filter operators in a Query request to filter selected fields from a multi-select list (i.e., where multiple fields can be selected). For example, on a job application form an applicant can select multiple interests such as “music, programming, sports.” The Includes filter retrieves data that contains any of the specified values (music or programming or sports) in the SOQL statement. The Excludes filter retrieves data that does not contain any of the specified values.

    NOTE: Use the Include or Exclude filters only on multi-select lists. Do not use In or Not In to filter multi-select lists. That combination creates bad results without an execution error. Do not use the Include or Exclude filters to filter non-multi-select lists. That combination results in an execution error.

Object tree to select objects to import.

Click the Show SOQL button to display the query syntax that is sent to Salesforce. The syntax is automatically modified as you configure the fields, filters, and sorts. You cannot edit the syntax directly, but you can use it to verify complex nested logic.

Create

This action creates new records in the Salesforce object defined in the Create operation. The internal "ID" field is generated automatically for each document sent to the operation.

Update

This action updates existing records in the Salesforce object defined in the Update operation. Supply the internal "ID" field in the request to update the existing object record. If this internal ID is not readily available in your source data, consider using a Connector Call function to Query data based on a standard value such as Name.

Name Description
Update Options tab Click the object name in the tree to the left.
Reference Fields tab Fields in the primary update object that can link the record to other associated objects (for example, Acct to Parent Acct, Oppty to Acct).
Use External ID For Reference Determines if a specific value should be used to perform the reference. Reference Fields use internalID by default.
Object Type Indicates the object type to which the reference field is linked.
Ref External ID Identifies the data that is used to perform the reference.

Upsert

The Upsert action is a convenient way to do common "insert-new-or-update-existing" integrations. Instead of doing a lookup against Salesforce (the destination system) to determine if a given record exists and then perform separate insert or update mappings and calls accordingly, simply perform one map to the Upsert request and let Salesforce determine whether to do an insert or update. To use this feature, customize the particular Salesforce object to designate at least one field as the External ID. Because objects can have multiple External IDs defined, select which one to use in the operation.

Name Description
Upsert Options tab Select the object name in the tree to the left and then click the Browse icon to choose an External ID from the list.
Reference Fields tab Fields in the primary upsert object that can link the record to other associated objects (for example, Acct to Parent Acct, Oppty to Acct).
External ID The External ID to use for the upsert. Salesforce looks for a record with a matching value and either updates it (found) or creates it (not found).
Use External ID For Reference Determines if a specific value should be used to perform the reference. Reference Fields use internalID by default.
Object Type Indicates the object type to which the reference field is linked.
Ref External ID Identifies the data that is used to perform the reference.

Delete

This action deletes an existing record in the Salesforce object defined in the Delete operation. You must supply the internal "ID" field in the request to delete the existing object record. If this internal ID is not readily available in your source data, consider using a Connector Call function to Query data based on a standard value such as Name.

Merge

This action merges Salesforce records of the same object type into one record. It merges the records into one of the records, called the master record, deletes the other records, and re-parents the related records. Use the masterRecord/ID field to indicate which of the records is the master record. If there are any field values from the other records that should supersede the values in the master record, set the field names and their new values in the master record’s fields in the merge request.

The following limitations apply to the Merge action:

  • Use Merge only with these object types: Account, Contact, and Lead.

  • Merge up to three records in a single request, including the master record. To merge more than three records, use the same master record in each request.

  • Merge up to 200 requests in a single SOAP call.

  • Do not use External ID fields.

For more information about merging records, see the Salesforce API documentation.

convertLead

This action converts Leads to an Account, Contact, or Opportunity. It is available only in version 15 and more recent versions of Salesforce.

Options tab

Select a connector action, then use the Import Wizard to select the object with which you want to integrate. The following table describes the fields for each action type:

Name Description
Object An object defines what you want to integrate or the action to execute, which you select in the Import Wizard.
Action Displays the action you specified in the Import Wizard.
Request/Response Profile The XML profile definition that represents the structure that is being sent or received by the connector.
Use Bulk API (Query, Create, Update, Upsert, and Delete) The Bulk API reduces the number of API calls you need to make. It uses the Salesforce Bulk API, which is an asynchronous API for loading larger data sets into Salesforce. The Bulk API can have up to 10,000 objects in a single call compared to the regular API, which can have up to 200 objects.

Set the batch size in the Batch Count field. The connector processes the batches it sends to the Bulk API and adjusts batch sizes based on processing times. There is a 10-minute limit for processing a batch and a five-minute limit for processing 100 records. If there is a timeout, the connector splits the batch into smaller batches and retries them. There is a limit of three retries.

Although the Bulk API is asynchronous, the Salesforce connector waits for a response. Because the Bulk API allows parallel processing, Dell Boomi recommends using a Flow Control shape with parallel processing enabled in your process.

Dell Boomi suggests the following when enabling Use Bulk API:

  • For Bulk Send, use a Flow Control shape with parallel processing enabled in your process. Bulk API is asynchronous, however the Salesforce connector waits for a response.
  • Enable Purge Data in Atom management. This prevents exhausting disk space; Bulk Query may store gigabytes of data.

  • Purge data regularly if you do not have Purge Data Immediately enabled. This helps bulk query performance.

  • Increase your Atom’s default read timeout when querying large records. This avoids read timeout errors.

Query Limit (Query only) Numeric field that allows you to specify the maximum number of rows/documents to return. The default is -1, which returns all results.
Return Application Error Responses (Create, Update, Upsert, Delete, Merge, and convertLead) When an error prevents an operation from completing, this setting does the following:
  • If selected, continues processing and passes the error response to the next component to be processed. Successful documents return an XML response with a success status of true and the object's internalID. Failed documents have a status of false.

  • If cleared, aborts processing and reports the error on the Process Reporting page.

Batch Count (Create, Update, Upsert, Delete, Merge, and convertLead) Numeric field to specify the number of documents to send in one Salesforce request. The default is 200. When Use Bulk API is selected, the batch size is set to 5000 behind the scenes and cannot be changed.

Dell Boomi suggests the following when setting the Batch Count:

  • When operating in low-latency mode on an Atom worker, consider reducing the Batch Count to 100 or lower. This can help improve the efficiency and performance of the Atom worker when multiple processes are competing for memory space.

Advanced tab

(Get only) The Salesforce connector options shown on the Advanced tab are a subset of the options on the Options tab.

Include Deleted (Get only) If selected, returns deleted records in results (QueryAll).
Batch Results (Get only) Works only with standard queries. If selected, combines results into a single list document. If you use this feature, there is an additional step you need to take. The connector combines the results by adding an element above the top level of the incoming document elements. As a result, your profile no longer matches downstream components. To amend this mismatch, either manually edit your profile adding the element or use the inbound document to create a new profile.
Log SOQLThis setting determines whether the full SOQL is written to process logs for all types of Salesforce operations, including bulk operations.
  • If selected, the full SOQL appears in process logs after a process is executed. The SOQL includes both the SOQL and the input parameters. Having the full SOQL is useful when troubleshooting process issues, such as when a request in your SOQL fails.

  • If cleared, the SOQL does not appear in process logs after a process is executed.

Archiving tab

See the Connector operation’s Archiving tab for more information.

Tracking tab

See the Connector operation’s Tracking tab for more information.

Caching tab

See the Connector operation’s Caching tab for more information.

Additional resources

Bulk API Developer's Guide
Related Tasks
Related References