@bonsae/node-red-salesforce

Salesforce nodes for Node-RED built with @bonsae/nrg.

Nodes

Node	Description
Connection	OAuth 2.0 PKCE authentication with token management
SOQL	Execute SOQL queries and return matching records
DML	Create, read, update, delete, and upsert SObjects
Bulk	Bulk API 2.0 operations for large data volumes
Describe	Retrieve SObject metadata (fields, relationships, record types)
Streaming	Subscribe to Platform Events and Change Data Capture via Pub/Sub API (gRPC)
Apex Invocation	Call existing Apex REST endpoints or Invocable Actions
Apex Code	Deploy and execute custom inline Apex code (Invocable or REST)

Prerequisites

• Node.js >= 22
• pnpm >= 10.11.0
• A Salesforce org with a Connected App configured for OAuth 2.0 with PKCE

Installation

pnpm add @bonsae/node-red-salesforce

Connected App Setup

Create a Connected App in Salesforce Setup:

1. Go to Setup > App Manager > New Connected App
2. Enable OAuth Settings
3. Set the Callback URL to {your-node-red-url}/salesforce/auth/callback
4. Enable Require Proof Key for Code Exchange (PKCE)
5. Add required OAuth scopes (api, refresh_token)
6. Save and copy the Consumer Key (Client ID)

Usage

1. Drag a Salesforce node onto the canvas
2. Double-click to configure
3. Select or create a Connection config node
4. In the Connection config, enter your Login URL, Client ID, and API Version
5. Click Authorize with Salesforce to complete the OAuth PKCE flow
6. Configure the node's specific settings (query, SObject type, etc.)

SOQL Query

Wire an inject node to a SOQL node configured with a query like SELECT Id, Name FROM Account. The output msg.payload contains the array of records, msg.totalSize the total count, and msg.done whether all records were fetched.

DML Operations

Set the operation (create, read, update, delete, upsert) and SObject type. Pass record data in msg.payload:

• create/update/upsert: a record object or array of records
• read/delete: a record ID or array of IDs
• upsert: also set the External ID Field

Bulk API 2.0

For large data volumes. Supports three input types:

• Record array: msg.payload as Record[] for ingest operations
• CSV string: msg.payload as a CSV string
• Readable stream: msg.payload as a Node.js Readable stream (for streaming from files)
• SOQL string: msg.payload as a SOQL query string when operation is "query"

Operations: insert, update, upsert, delete, hardDelete, query.

For ingest operations, the output msg.payload contains { successfulResults, failedResults, unprocessedRecords }. For queries, each record is streamed as a separate message. Job lifecycle progress is reported via the status port.

Describe

Pass the SObject API name and receive the full describe result including fields, child relationships, and record type info.

Streaming (Pub/Sub API)

Subscribes to Salesforce Platform Events and Change Data Capture events using the gRPC-based Pub/Sub API. This node has no input port -- it emits messages when events are received.

Configure the channel (e.g., /event/MyEvent__e), subscribe type (LATEST, EARLIEST, or CUSTOM with a replay ID), and batch size.

Apex Invocation

Call existing Apex endpoints deployed in your Salesforce org. Select the type (REST or Invocable), then pick the endpoint or action from a dropdown that queries your org. For REST, choose the HTTP method and endpoint path. For Invocable, select the action by name. The payload is passed in msg.payload.

Apex Code

Deploy and execute custom Apex code directly from Node-RED. Select the type (Invocable or REST), enter a class name, and write your Apex method body in the built-in code editor. The node automatically deploys the class to Salesforce on Node-RED deploy and removes it when the node is deleted.

Your code receives the input as a payload string and returns any value:

// Invocable example
Map<String, Object> data = (Map<String, Object>) JSON.deserializeUntyped(payload);
String name = (String) data.get('name');
return 'Hello, ' + name + '!';

// REST example
return new Map<String, Object>{ 'message' => 'Received: ' + payload };

The class name prefix defaults to NRG_ and can be overridden in settings.js:

salesforceApexCodeClassPrefix: "MY_"

For REST mode, you also configure the URL mapping (e.g., /my/endpoint/*).

Development

# Install dependencies
pnpm install

# Start dev server (launches Node-RED with hot reload)
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm tsc:server
pnpm tsc:client

# Lint and format
pnpm lint
pnpm format

Locales

Labels and auto-generated help docs are available in:

• English (en-US)
• German (de)
• Spanish (es-ES)
• French (fr)
• Japanese (ja)
• Korean (ko)
• Portuguese (pt-BR)
• Russian (ru)
• Chinese Simplified (zh-CN)
• Chinese Traditional (zh-TW)

License

MIT