Retrieving Salesforce records

Use the SalesforceRequest node to retrieve records from the Salesforce system.

About this task

You can retrieve Salesforce records by specifying Retrieve in the Operation property of the SalesforceRequest node. You can retrieve all records of a particular type by specifying the object type in the Salesforce object property of the node. This object type can be overridden by a value specified in the LocalEnvironment.Destination.Salesforce.Request.object local environment variable.

Alternatively, you can retrieve a specific record by specifying a Salesforce ID in the LocalEnvironment.Destination.Salesforce.Request.id environment variable. The returned record appears as a JSON object in the location that is specified by the Output data location property of the node.

If an external ID name and value are specified in the LocalEnvironment.Destination.Salesforce.Request.externalIdName and LocalEnvironment.Destination.Salesforce.Request.externalId environment variables, all records with that external ID are returned. The returned records appear as a JSON array in the location specified by the Output data location property.

If neither a Salesforce ID nor an external ID is specified, all records of the specified type are returned by default.

You can control the records that are returned by using the LocalEnvironment.Destination.Salesforce.Request.filter environment variable to specify a filter with one of the following clauses:
  • where
  • limit
  • skip
  • order
  • field

You can control which records are returned by specifying a filter with a where, limit, or skip clause. If no ID has been specified, this filter is used to select the records to be returned.

If you specify a filter with an order clause, the records are returned in the specified order. For more information, see Filtering the records retrieved from Salesforce.

You can also restrict the records that are returned by specifying a filter with a field clause, so that only the specified field is returned. Filtering with a field clause optimizes performance by reducing unnecessary processing.

By default, the retrieval of records is determined by the following properties, in order of precedence:
  • Salesforce ID
  • External ID
  • Filter

If no Salesforce records are found, the output tree contains nothing under JSON.data.

JSON schema are supplied for a wide range of Salesforce objects, and you can use them as input and output for message maps in a Mapping node. For example, you can transform the message tree for a returned Salesforce Account record in a Mapping node by using the JSON schema for the Account object. For more information, see Using Salesforce models.

Procedure

Follow these steps to retrieve Salesforce records:

  1. Set up a Salesforce account on Salesforce.com.
  2. Configure a connection to Salesforce.com.
    For more information, see Configuring a secure connection to Salesforce.com
  3. Create a flow containing a SalesforceRequest node, and set the following properties on the Basic tab:
    1. In the Salesforce URL property, specify the URL of the external Salesforce system.
    2. In the Operation property, specify Retrieve.
    3. In the Salesforce object property, select the type of Salesforce records that you want to retrieve.
    4. In the Security identity property, specify the security identity that you will use when connecting to the Salesforce system. For information about configuring the security identity on the integration node, see Configuring a secure connection to Salesforce.com.
    5. In the Timeout property, specify the time (in milliseconds) that the node waits for Salesforce to process the operation.
    For more information, see SalesforceRequest node.
  4. Send the required message through the flow to the Salesforce system.
    You will receive a response from the Salesforce system to confirm that the records have been retrieved.

Example

See Example: Retrieving all Account records from Salesforce for a specific example of how to use the SalesforceRequest node to retrieve records from a Salesforce system.