@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 Method or REST Resource), enter a class name, and write your Apex code in the built-in editor. The node automatically deploys the class to Salesforce on Node-RED deploy and removes it when the node is deleted.

You write the run() method and any helper methods or inner classes. The node wraps your code in the required Salesforce boilerplate (annotations, Input/Output classes, etc.):

private static Object run(String payload) {
    Map<String, Object> data = (Map<String, Object>) JSON.deserializeUntyped(payload);
    String name = (String) data.get('name');
    return 'Hello, ' + name + '!';
}

You can add helper methods and inner classes alongside run():

private static Object run(String payload) {
    Processor p = new Processor();
    return p.process(payload);
}

public class Processor {
    public String process(String input) {
        return input.reverse();
    }
}

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

salesforceApexCodeClassPrefix: "MY_"

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

Apex Language Server (optional)

The Apex Code editor supports an optional Language Server that provides autocompletions, hover documentation, signature help, diagnostics, and SObject field completions from your connected org.

Prerequisites: Java 11+

Setup:

# 1. Download the Apex Language Server JAR (one-time)
chmod +x scripts/setup-apex-lsp.sh
./scripts/setup-apex-lsp.sh

# 2. Start the WebSocket bridge
node scripts/apex-lsp-server.mjs

Configure in Node-RED settings.js:

salesforceApexCodeLanguageServerUrl: "ws://localhost:3001"

The bridge spawns a Java LSP process per editor session and creates a temporary SFDX workspace for type resolution. SObject definitions are fetched from the connected org and cached for 30 minutes.

The bridge accepts --port and --jar flags:

node scripts/apex-lsp-server.mjs --port 3002 --jar /path/to/apex-jorje-lsp.jar

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