Salesforce Query

Controlled node

Overview

The Salesforce Query node allows you to execute SOQL (Salesforce Object Query Language) queries against your connected Salesforce instance. This node is essential for retrieving data from Salesforce objects such as Accounts, Contacts, Opportunities, and custom objects.

The node requires a valid Salesforce connection configured in your project settings. Once connected, you can write SOQL queries to fetch specific records, filter data, and retrieve related records. The query results are returned as a list of records that can be processed by downstream nodes in your workflow.

SOQL Syntax

SOQL is similar to SQL but designed specifically for Salesforce. For example: SELECT Id, Name, Email FROM Contact WHERE CreatedDate = LAST_N_DAYS:30. Refer to Salesforce documentation for complete SOQL syntax and limitations.

Inputs

Input	Type	Description	Default
Run	Event	Triggers the execution of the SOQL query.	-
SOQL	Text	The SOQL query string to execute against Salesforce. Must be valid SOQL syntax.	-
Connection	Connection	The Salesforce connection to use for the query. Configure this in your project connections panel.	-

Outputs

Output	Type	Description
Done	Event	Fires when the query has completed successfully or failed.
Records	Data	Contains the list of records returned by the SOQL query. Returns an error object if the query fails.

Runtime Behavior and Defaults

• Controlled Execution: This node requires a Run event to execute. It will not run automatically when data changes.
• Connection Validation: The node validates that a Salesforce connection is provided before executing. If no connection is specified, it returns an error.
• Query Validation: The SOQL query must be provided as a string. If empty or invalid, the node returns an error.
• Error Handling: If the query fails (invalid SOQL, insufficient permissions, etc.), the Records output will contain an error object with the failure message.
• Result Format: Successful queries return an array of record objects. Each object contains the fields specified in your SELECT clause.

Example Usage

Basic Contact Query

To retrieve recently created contacts:

1. Connect a Start node or any event-triggering node to the Run input.
2. Set the SOQL input to: SELECT Id, FirstName, LastName, Email FROM Contact WHERE CreatedDate = LAST_N_DAYS:7
3. Configure the Connection input with your Salesforce connection.
4. Connect the Records output to a node that processes the contact data (e.g., Show node to view results, or For Each to iterate through contacts).

Query with Variables

You can use template variables in your SOQL query by connecting data inputs:

SELECT Id, Name FROM Opportunity WHERE StageName = '{{stageName}}' AND Amount > {{minAmount}}

Connect a Text node or variable to provide dynamic values for stageName and minAmount.

Error Handling Pattern

Connect the Done event to an If node that checks if Records contains an error:

// Check if query failed
{{#if records.error}}
  // Handle error
{{else}}
  // Process records
{{/if}}