soql/executeWithPagination

Execute a SOQL query and automatically follow all nextRecordsUrl pages until all matching records are retrieved.

Automatic Pagination: The Salesforce REST API returns a maximum of 2,000 records per response page. This operation automatically follows each nextRecordsUrl response until done = true, then returns the full combined records array. Use this for queries that may return more than 2,000 records.

When to Use

Export all contacts from a large Salesforce org for sync to a data warehouse.
Full historical data export for migration or backup purposes.
Sync all records of a given object type to an external analytics platform.
Any query where the total result count may exceed 2,000 records.

Configuration

Connection

Field	Type	Required	Description
`InstanceUrl`	string	required	Salesforce org URL.
`AccessToken`	string	required	Valid OAuth2 access token.

Operation Fields

Field	Type	Required	Description
`Query`	string	required	A valid SOQL query string. Do not include a `LIMIT` clause if you need all records; the pagination handler fetches all pages automatically.

Sample Configuration

{
  "Resource": "soql",
  "Operation": "executeWithPagination",
  "InstanceUrl": "https://myorg.my.salesforce.com",
  "AccessToken": "{{credentials.salesforce.accessToken}}",
  "Query": "SELECT Id, FirstName, LastName, Email, AccountId FROM Contact WHERE IsDeleted = false ORDER BY CreatedDate ASC"
}

Validation Errors

Error Code	Condition
`CFG_MISSING_INSTANCE`	`InstanceUrl` is missing.
`CFG_MISSING_TOKEN`	`AccessToken` is missing.
`VAL_MISSING_FIELD`	`Query` is missing or empty.
`UNEXPECTED_ERROR`	Unexpected exception or SOQL syntax error.

Output

Success Port

Field	Type	Description
`records`	array	Combined array of all records from all pages. Contains every record matching the query.
`totalSize`	int	Total count of all records retrieved across all pages.
`done`	bool	Always `true` — all pages have been fetched.
`resource`	string	Always `soql`.
`operation`	string	Always `executeWithPagination`.

Error Port

Field	Type	Description
`errorCode`	string	Machine-readable error code.
`message`	string	Error description.

Sample Output

{
  "records": [
    { "Id": "0035g000006LmnOPQ", "FirstName": "Alex", "LastName": "Rivera", "Email": "alex@acme.com" },
    { "Id": "0035g000006XyzABC", "FirstName": "Sam", "LastName": "Torres", "Email": "sam@beta.com" }
    // ... all remaining records from all pages
  ],
  "totalSize": 15000,
  "done": true,
  "resource": "soql",
  "operation": "executeWithPagination"
}

Expression Reference

Expression	Description
`{{nodes.SOQLPaginated.records}}`	All records from all pages combined.
`{{nodes.SOQLPaginated.totalSize}}`	Total record count across all pages.
`{{nodes.SOQLPaginated.done}}`	Always `true` on success.

Node Policies & GuardRails

Policy	Detail
SOQL injection prevention	Never interpolate unsanitized user input into the `Query` field.
API quota consumption	Each page fetch uses one API call. A 20,000-record result set uses ~10 API calls. Monitor quota usage in high-volume orgs.
Memory consideration	Very large result sets (100,000+ records) accumulate in memory before the node completes. Use Bulk API for mass data operations instead.
Credential storage	Store `AccessToken` in BizFirst Credentials Manager.
Error port wiring	Always wire the error port.

Examples

Full Contact Export to Data Warehouse

{
  "Query": "SELECT Id, FirstName, LastName, Email, Phone, AccountId, CreatedDate FROM Contact WHERE IsDeleted = false ORDER BY CreatedDate ASC"
}
// Pass {{nodes.SOQLPaginated.records}} to a data warehouse write node

All Open Opportunities for Analytics

{
  "Query": "SELECT Id, Name, Amount, StageName, CloseDate, AccountId FROM Opportunity WHERE IsClosed = false ORDER BY CloseDate ASC"
}

Historical Audit — All Cases This Year

{
  "Query": "SELECT Id, CaseNumber, Subject, Status, Priority, CreatedDate FROM Case WHERE CreatedDate = THIS_YEAR ORDER BY CreatedDate ASC"
}