Salesforce Lookup

In this article

Overview

The Salesforce Lookup Snap is a Read-type Snap that provides the ability to format WHERE clause from input document stream for a SOQL (Salesforce Object Query Language) query. See Introduction to SOQL and SOSL for more information.

Prerequisites

A valid Salesforce account with the required permissions.

Support for Ultra Pipelines

Works in Ultra Pipelines.

In Ultra mode, ensure that you enable the Single Lookup Request property checkbox to process one document at a time.

Limitations and Known Issues

None.

Snap Views

TypeFormatNumber of ViewsExamples of Upstream and Downstream SnapsDescription
InputDocument
  • Min:1
  • Max:1
  • JSON Formatter
  • Mapper
This Snap has exactly one input view and receives Document(s) in the view. Expressions in the Object type, Output fields, Conditions and Correlation ID properties can be evaluated with values from the input view during the execution.
OutputDocument
  • Min:1
  • Max:1
  • Mapper
  • Copy
  • File Writer
Documents
Error


The error view contains error, reason, resolution and stack trace. For more information, see Handling Errors with an Error Pipeline.

Snap Settings

Field

Field Type

Description


Label*

 

String

Specify a unique name for the Snap. You can modify this to be more specific, especially if you have more than one of the same Snap in your Pipeline.

Default ValueSalesforce Lookup
ExampleSalesforce Lookup

Service Version*

String/Expression

 

Specify the version number associated with the Salesforce service that you want to connect to. Alternatively, click the Suggestion  icon to fetch the list of versions and select the desired version.

Default Value52.0 
Example41.0

Salesforce API*


Dropdown list

This property sets the Salesforce API mode to Bulk API or REST API during the pipeline execution. In preview mode, the Snap always executes in REST API.

Default Value: REST API
Example: Bulk API

Object Type*

String/Expression/Suggestion

Specify the object type that enables you to define the name of the Salesforce object, such as Account.

Default Value:  Account
Example:  Account

Output Fields*

Use this field set to define the field names for the Salesforce Object Query Language (SOQL) SELECT statement. Specify each output field as a separate row. Click  to add a new row. This field set contains the Output Fields field.

Output Fields*String/Expression/Suggestion

Specify a list of field names for the SOQL SELECT statement. Alternatively, click the Suggestion  icon to fetch the list of field names associated with the object type and select a field.

The value for this field can also be an expression that will be evaluated against the values configured in Pipeline parameters only.

Default Value: N/A
ExampleId, Name, ShippingAddress

Conditions*Use this field set to define conditions. Specify each condition as a separate row. Click  to add a new row. This field set contains the Conditions field.

Conditions*

String/Expression

Specify the condition for the WHERE clause.

The values in this field forms an AND clause in the SOQL WHERE statement. Each entry in the Conditions row can be an expression to be evaluated with the values from the input view. The Snap receives a stream of document data, where each document is formatted into an AND clause and all AND clauses are ORed together to form an entire WHERE statement. If the size of SOQL statement exceeds 10,000 characters, the Snap sends the SOQL query request, retrieves the resulting records which are sent to the output view, and restarts forming a new WHERE statement.

Example: "Name = '" + $Name + "'"
The above example is an expression which can be evaluated to "Name = 'O\'Connor'", if $Name is a JSON path to a value "O'Connor" in the input document data. The value of the Name field is a string type which must be enclosed by a pair of single quotes. If there is any single quote in the value, like the above example, it is escaped with a backslash by the Snap automatically. Otherwise, Salesforce.com will reject the SOQL request.


Using quotes in the WHERE clause

  • Do not use quotes for field names in the WHERE clause. Using quotes results in an error.
  • Use only single quotes for values in the WHERE clause as using double quotes results in an error.
  • The above rules do not apply when you are using SnapLogic expressions, you can use quotes for the field names and values as applicable. 

Default Value: N/A
Example:  "Name = '" + $Name + "'"

Correlation ID

String/Expression/Suggestion

Specify an ID field name which the Snap uses to correlate input document to the output record when you want to pass through input data to the output view. Alternatively, click the Suggestion icon to fetch a list of IDs and select a ID.

  • The value for this field can be an expression that will be evaluated against the values configured in the Pipeline parameters only.
  • The value of this field must be unique throughout the entire records in the selected object type, so that it identifies a specific record in an SObject type. External ID field names fit into this category. This field may be left empty if users do not want to pass through input document to the output view. 

Default Value: N/A
ExampleId

Single Lookup Request*


Checkbox

Select this checkbox to enable the Snap to send one lookup request for each input document. In Ultra mode, ensure that you select this checkbox to process one document at a time.

Default Value: Not selected 

Polling Interval*


Integer/Expression

Specify the polling interval in seconds for the Bulk API query execution. At each polling interval, the Snap checks the status of the Bulk API query batch processing.

Maximum value:: 60 

This field can be an expression that will be evaluated against the values configured in Pipeline parameters only.

Default Value: 5
Example: 5

Polling Timeout*

 

Integer/Expression

Specify the polling timeout in seconds for the Bulk API read batch execution. If the timeout occurs while waiting for the completion of the read batch execution, the Snap throws a SnapExecutionException. 

This field can be an expression that will be evaluated against the values configured in Pipeline parameters only.

Default Value:  3000
Example:  300

Process Date/Time

 

Checkbox

All date/time fields from Salesforce.com  are retrieved as string type. If this property is unchecked, the Snap sends these fields without any conversion.

If checked, the Snap converts date/time fields to corresponding date/time types by accessing the meta data of the given SObject. Salesforce datetime is converted to Joda DateTime, Salesforce date to Joda LocalDate and Salesforce time to Joda LocalTime.

Default Value: 
false

Include Deleted Records

 

Checkbox

Select this checkbox to include deleted records in the query result. This feature is supported in REST API version 29.0 or later and Bulk API version 39.0 or later.

Default Value: Not selected 

Pass-through on No Lookup Match

Checkbox

Select this checkbox to allow the input document to pass through to the output view when there is no lookup matching an input document. Else, the input document is written to the error view as an error condition.

Default ValueNot selected

Match Data Type


 

Checkbox

Select this checkbox to match the data types of the Bulk API results with the data types in REST API. This property applies if the content type is not JSON in Bulk API. In Bulk API, Salesforce.com returns all values as strings if Bulk content type is XML or Batch size is for PK Chunking. If this property is checked, the Snap attempts to convert strings values to the corresponding data types if the original data type is one of boolean, integer, double, currency, and percent.

This property is ignored in REST API or with JSON Bulk content type. In Bulk API (not with JSON Bulk content type), Salesforce.com does not return any value for null. Therefore, if the value is null, the key-value entry is not present in the output document, which is different from the REST API result.


Default Value
:  Not selected

Snap Execution

Dropdown list

Select one of the three modes in which the Snap executes. Available options are:

  • Validate & Execute: Performs limited execution of the Snap, and generates a data preview during Pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during Pipeline runtime.
  • Execute only: Performs full execution of the Snap during Pipeline execution without generating preview data.
  • Disabled: Disables the Snap and all Snaps that are downstream from it.


The field labels for this Snap are updated to title case. If you have existing Pipelines that include the field names in the error messages, you must update those Pipelines to use the new field labels.

Example


Looking up Records

In the following example Pipeline, the Salesforce Lookup Snap shows how Salesforce object records can be looked up:

We use the Mapper Snap to map an account number to the AccountNumber field of a Salesforce object record.

 

The Salesforce Lookup Snap queries the Salesforce Object Account for the provided account number and specifies the output to contain only the BillingStreet value.

 

Successful validation of the Snap gives the following output.

Looking-up Records with REST API Using the Correlation ID

In this Pipeline, we read data from the Salesforce Read Snap using filter condition in WHERE clause, take the first 10 rows of data in Head Snap and pass those values in the Salesforce Lookup Snap using the Correlation Id property.  

The Salesforce Read Snap reads the data from the SObject type Account, with the desired output fields as Name, Id, BillingCity and AccountNumber.  

 
The output preview of the Salesforce Read Snap: 

 
 The Head Snap reads the first ten documents starting from 0, and the output preview is as displayed:


 
The values are passed from the Head Snap to the Salesforce Lookup Snap. The Salesforce Lookup Snap with the output fields, Id, Name and Type, and Id, given as the where condition. The Correlation ID is set to the ID.

 

 
Successful execution of the Pipeline displays the below output preview.

 

Looking-up Records with a Single Lookup Request

In this Pipeline, the Salesforce Read Snap reads the records from an object, maps the value of an ID, and passes the values to the Salesforce Lookup Snap.

 The Salesforce Read Snap retrieves the records for the object, Account _c.

The Mapper Snap maps the values of the ID for the Account_c object and passes them to the Salesforce Lookup Snap.

The Salesforce Lookup Snap retrieves the data from the object, for the specified output fields and generates a SQL statement based on the condition ""Id = '" + $Id + "'".

The Successful execution of the pipeline displays the below output preview.

Looking-up Records Using Correlation ID

In this Pipeline, the Salesforce Read Snap reads the records from an object, maps the value of an ID, and passes the values to the Salesforce Lookup Snap.

 The Salesforce Read Snap retrieves the records for the object, Account _c.

The Mapper Snap maps the values for the ID and the custom field, '$Customer_enq__c' for the object, Account_c, and passes them to the Salesforce Lookup Snap.

The Salesforce Lookup Snap retrieves the data from the object, for the specified output fields and generates a SQL statement based on the condition ""Id = '" + $Id + "'". selecting the custom field ($Customer_enq__c) as correlation ID, 

The successful execution of the pipeline displays the below output preview:

Downloads

Important steps to successfully reuse Pipelines

  1. Download and import the Pipeline into SnapLogic.
  2. Configure Snap accounts as applicable.
  3. Provide Pipeline parameters as applicable.

  File Modified

File Example_salesforce_Lookup_Records.slp

Mar 10, 2022 by Subhajit Sengupta

Snap Pack History

 Click to view/expand
Release Snap Pack VersionDateType  Updates
4.29main15993 StableUpgraded with the latest SnapLogic Platform release.
4.28 Patch428patches14355 

Latest

Fixed an issue with Salesforce Snaps where the Service Version could not be retrieved from SFDC due to a blocked URL, failing the Snap execution.

4.28main14627 StableUpgraded with the latest SnapLogic Platform release.
4.27 Patch

427patches14079

 Latest

Fixed an issue with the Salesforce Subscriber Snap where the Snap was unable to re-subscribe to a topic if it did not receive any message for 72 hours —stopped and displayed an error message. With this fix, the Snap automatically sets the Replay ID value to -2 when:

  • the specified Replay ID is invalid or outside the retention window.

  • the most recently received Replay ID for an event is outside the 72-hour retention window.

4.27 Patch427patches13944 LatestFixed an issue with Salesforce accounts, where an account password containing special characters and an empty security token was not properly encoded and the account was not validated.
4.27 Patch427patches13789 Latest

Fixed the following issues with Salesforce Snaps:

  • High memory use due to leaked resources.

  • Hung Pipelines due to blocked threads.

4.27main12833Stable
4.26 Patch426patches12054 Latest

Enhanced the Salesforce Subscriber Snap with improved resilience to network failures and fixed an issue with duplicate documents.

4.26main11181 StableUpgraded with the latest SnapLogic Platform release.
4.25 Patch425patches10182 LatestFixed an issue with the Salesforce Read Snap where the retry fields do not work as expected when a Pipeline has more than ten Snaps. 
4.25 Patch425patches9609 LatestEnhanced the Salesforce Read Snap to allow you to add an optional second output view that exposes the schema of the target object as the output document. The output view of the Snap has a minimum of one output and a maximum of two outputs. 
4.25main9554
 
Stable
  • Enhanced the Salesforce Upsert Snap to support CSV payload using the new field Bulk Content Type in Bulk API mode as Salesforce API has recently been supporting CSV payload as well. Earlier, this Snap supported only XML data type; you can now select CSV content type from the Bulk Content Type drop-down list. The default content type is set to XML to preserve backward compatibility. 
    This enhancement also addresses the null values issue during Bulk API mode. 
  • Enhanced the Snaps in the Salesforce Snap Pack by updating the field labels to title case. If you have existing Pipelines using Salesforce Snaps that include the field names in the error messages, you must update those Pipelines to use the new field labels.
4.24 Patch 424patches9024 Latest
4.24 Patch 424paches8569 Latest

Fixes an issue in Salesforce Bulk Upsert, Salesforce Bulk Update, and Salesforce Bulk Create Snaps that fail to process Related object and Related external ID values by modifying the input schema that formats the CSV data.

Potential Breaking Change

This Salesforce Snap patch contains an issue affecting the Salesforce Subscriber and Salesforce Publisher Snaps. If you do not use these Snaps in your Pipelines, then you can use this patch version. Else, we recommend you to not use this patch version as Pipelines will fail. We will fix this issue soon in an upcoming patch.

4.24main8556
StableUpgraded with the latest SnapLogic Platform release.
4.23 Patch 423patches7888 Latest
4.23main7430
 
StableUpgraded with the latest SnapLogic Platform release.
4.22main6403
 
StableUpgraded with the latest SnapLogic Platform release.
4.21 Patch salesforce8829 Latest

Fixed the Salesforce Create, Update, Bulk Create, Bulk Update, and Bulk Upsert Snaps, enabling you to upload files containing duplicate values across multiple fields.

4.21snapsmrc542

 

StableUpgraded with the latest SnapLogic Platform release.
4.20 Patch salesforce8814 Latest

Fixed the Salesforce Create, Update, Bulk Create, Bulk Update, and Bulk Upsert Snaps, enabling you to upload files containing duplicate values across multiple fields.

4.20 Patch salesforce8797 Latest

Fixed the Salesforce Subscriber Snap wherein the Salesforce Subscriber and Mapper Snap combination generates Null output for Array object type.

4.20snapsmrc535
 
Stable

Added the Salesforce Bulk Query Snap, which enables you to perform bulk SOQL queries on Salesforce.

4.19snaprsmrc528
 
Stable
4.18 Patch salesforce7832 Latest

Enhanced the Salesforce Subscriber Snap to capture Change Data Capture (CDC) events.

4.18snapsmrc523
 
StableUpgraded with the latest SnapLogic Platform release.
4.17 Patch salesforce7474 Latest

Added Order by clause and Limit clause properties to the Salesforce Reader Snap to fix an issue wherein the Snap throws an error while fetching records.

4.17ALL7402
 
Latest

Pushed automatic rebuild of the latest version of each Snap Pack to SnapLogic UAT and Elastic servers.

4.17snapsmrc515
 
Latest

Added the Snap Execution field to all Standard-mode Snaps. In some Snaps, this field replaces the existing Execute during preview check box.

4.16 Patch salesforce6889 LatestAdded two new properties, Number of retries and Retry interval, to the Salesforce Read, SOQL, Publisher, and Subscriber Snaps. These properties let you handle retry attempts and intervals in case of a network failure.
4.16snapsmrc508
 
Stable
  • Added two new Snaps: 
    • Salesforce Publisher: Publish Salesforce platform event records to a given event custom sObject (Salesforce Object).
    • Salesforce Subscriber: Subscribe to Salesforce platform event records for a given event custom sObject.
4.15 Patch salesforce6405 Latest

Fixed an issue with resource leak in PK Chunking in Salesforce Read and SOQL Snaps.

4.15 Patch salesforce6349 Latest

Fixed an issue with the Salesforce SOQL Snap timing out while waiting for a connection from the pool.

4.15snapsmrc500
 
StableUpgraded with the latest SnapLogic Platform release.

4.14 Patch 

salesforce5670

 LatestFixed the Salesforce SOQL Snap that fails to execute if the parameter values of a SOQL query expression contain the WHERE clause.
4.14snapsmrc490
 
StableUpgraded with the latest SnapLogic Platform release.
4.13

snapsmrc486

 
Stable
  • Fixed an issue where the Salesforce Read Snap fails to download the PK-Chunking CSV file due to network failure or running out of disk space.
  • Fixed an issue where theSalesforce Lookup Snap does not match the datatype with the Bulk API; for instance, boolean data returns string.
  • Fixed an issue where the Salesforce SOQL Snap does not preview data in pipelines. 
  • Fixed an issue where PK Chunking files are not deleted from the temp directory.
4.12 Patchsalesforce4839 Latest

Fixed a defect that occurs when downstream Snaps are slow in processing documents downloaded from SFDC.

4.12 Patchsalesforce4773 Latest

Added a new option in Advanced properties - "Validate record count downloaded in Bulk API" that compares the number of records processed vs downloaded and routes output to Error View (if Error View is enabled) if there is a mismatch.

4.12

snapsmrc480

 
Stable
  • Updated Salesforce SOQL and Lookup Snaps to ensure that they are consistent with SnapLogic guidelines of writing Snap data exceptions to error views and continuing to process next documents vs. hard stopping.
  • Enhanced the Salesforce read operations for the Read, SOQL, and SOSL Snaps to display the original Salesforce error cause, reason, and resolution.
4.11 Patchsalesforce4299 Latest
  • Fixed an issue wherein the Salesforce SOQL Snap did not get an input stream from the next records URL.
  • Fixed an issue with the Salesforce SOQL Snap querying deleted records using Bulk API.
4.11snapsmrc465
 
Stable

Polling timeout property's default value increased to 3000 from 300 for Salesforce Lookup, Salesforce Poller, Salesforce Read, and Salesforce SOQL Snaps.

4.10 Patchsalesforce4005 Latest

Salesforce Poller Snap: Includes the success field in the output.

4.10

snapsmrc414

 
StableUpgraded with the latest SnapLogic Platform release.
4.9.0 Patchsalesforce3218 Latest

Fixed the error in PK Chunking when a downstream Snap is blocking the pipeline

4.9.0 Patchsalesforce3247 Latest

Addressed an issue withSalesforce Poller Snap causing JSON Formatter to throw ConcurrentModificationException.

4.9.0 Patchsalesforce3225 Latest

Addressed a null pointer exception in the Salesforce Update Snap. This exception was present in both salesforce3082 and salesforce3122.

4.9snapsmrc405
 
Stable

Updated the Salesforce Create, Batch Create, Delete, Poller, Update and Upsert Snaps with Pass through property.

4.8.0 Patchsalesforce2884 Latest
  • Addressed an issue with inconsistent behavior between Preview and Execution.
  • Addressed an issue with Salesforce SOQL Snap failing to download PK-Chunking.
4.8

snapsmrc398

 
Stable
  • Updated the Salesforce Lookup Snap with Correlation ID property. This property is an ID field name which the Snap uses to correlate input document to the output record when users want to pass through input data to the output view.
  • Updated the Salesforce Read Snap with Output field limit and Output field offset properties. Output field limit is the number of fields to return in the order of Salesforce describe object field index. Output field offset defines a starting field index for the output fields.
  • Info tab added to accounts.
4.7.0 Patch salesforce2284  Latest

Added log to troubleshoot a deploy issue.

4.7.0 Patch salesforce2255  Latest

Addressed SFDC SOQL Snap routing to the error view & validate PK Chunking record numbers.

4.7.0 Patch salesforce2244  Latest

Addressed possible leak with threads waiting to download PK Chunking responses.

4.7.0 Patch salesforce2218 Latest

SFDC SOQL Snap route to the error view & validate PK Chuning record numbers.

4.7.0 Patch salesforce2209 Latest

SOQL Snap now correctly routes to the error view & validates PK Chunking record numbers.

4.7

snapsmrc382

 
Stable
  • Updated the Salesforce SOQL, Read, & Lookup Snaps with Match data type field.
  • Updated the Salesforce Upsert, Update, Create and Delete Snaps with 'Standardize error output' field.
4.6.0 Patch salesforce1931 Latest
  • Implemented a new property "Match data type in XML"
  • Implemented a new global.properties entry "SFDC_SESSION_TIMEOUT_MINUTES" so that users can reduce the frequency of logins.
4.6snapsmrc362
 
Stable
  • Doc Enhancement: Examples added to Salesforce Snap documentation.
  • Resolved an issue in Salesforce Snaps that prevented extraction of access tokens.
4.5.1

salesforce1633

 
Stable
  • Salesforce Read Snap is updated to support Output fields and Where clause specifications. For more information, see Salesforce Read.
  • Salesforce Read & SOQL Snaps are updated to support JSON representation of Bulk API result data and a parsing issue encountered (in Bulk API mode) has been rectified.
  • Fixed errors around upload and output preview for Salesforce Wave Analytics Snap.
4.5snapsmrc344NALatest
  • Pass through and Ignore empty results added to Salesforce SOQL, Read and SOSL Snaps.
  • Resolved an issue in Salesforce Batch Create Snap to appropriately create multiple records in REST API.
4.4.1
 Stable
  • Resolved an issue with Connection pool times out with Salesforce Snaps.
  • Salesforce Lookup: Resolve a 'The session ID or OAuth token used has expired or is invalid' exception when running in an Ultra Task.
4.4
 Stable

Resolved an issue with Salesforce Query returning inconsistent result sets.

4.3.2
 Stable
  • SalesForce Lookup Snap: Implemented Pass-through on no lookup match property
  • Resolved an issue with Salesforce Upsert Snap failing with an error 'not valid for the type xsd:double'.
  • Resolved an issue with Salesforce SOQL Snap returning fewer results than SFDC returns.
  • Performance improvements made to Salesforce Read/SOQL Snaps with Bulk API in PK Chunking mode.
4.3
NA
  • NEW! Salesforce Batch Create added in this release.
  • Salesforce Wave ID field suggestions now include upstream schema.
  • Resolved an issue in Salesforce Lookup Snap failing to generate an output schema if more than 50 records are found.
4.22
NA
  • NEW! Salesforce Batch Create added in this release.
  • Resolved an issue with Salesforce Wave analytics throwing an error when metadata contained a hash symbol in number format.
  • Resolved an issue the failing to validate the account if the password contained a colon (:).
  • Salesforce Snaps now default to the latest Salesforce API version.
  • Create/Update/Upsert Snaps did not support related object mappings.


 
  • Salesforce Upsert - intermittently throws ViewChannelException since document was send to the closed output view
  • Salesforce Delete not using passthrough platform service


 
  • Salesforce Account: added custom login URL (for support of CipherCloud)
  • Salesforce Read: various updates for errors and performance improvements for > 1m rows being retrieved in Bulk API
  • Salesforce Write in Bulk API: enhanced batching support


 
  • NEW! Salesforce Wave Analytics added in this release.
  • Salesforce Upsert: External ID field is now suggestible.

  • Salesforce Read & Salesforce SOQL now accept 200 as a batch size.

  • Snaps with a Polling timeout property no longer have a maximum timeout limit.


 
  • Addressed the following issues:
    • Salesforce Account: Could not login to Salesforce, Endpoint Exception Error message is displayed.
    • Salesforce Analytics null pointer
    • Salesforce Attachment: NPE is displayed for Invalid Account.


 
  • The account settings for Salesforce.com now gives you the choice of either entering a token or entering an IP while list address range. If you need to create a token, you will need a non-admin user to generate the token for SnapLogic.
  • The Security Token is no longer required for Salesforce.com accounts.