Camunda 8 Connector SDK for Node.js

Note: This is EXPERIMENTAL. The official Camunda (Java) SDK is still in active development, and this community SDK follows it.

This a community project - a pure Node.js implementation of the official Camunda 8 Connector SDK. It is designed to follow the official Java SDK API ergonomics as closely as possible.

Supports secret replacement and non-nullable (required) input process variables.

For a tutorial in using this SDK to write a connector for Camunda 8, see this article.

Outbound Connector

To create an outbound connector:

Scaffold a new project and add the Node.js Connector SDK:

mkdir my-outbound-connector
cd my-outbound-connector
npm init --yes
tsc --init
npm i camunda-connector-sdk

Edit the tsconfig.json and enable the following two options:

"experimentalDecorators": true,                
"emitDecoratorMetadata": true,       

Here is an example Outbound connector:

import {
    BPMNError,
    Secret,
    OutboundConnector,
    OutboundConnectorFunction,
    OutboundConnectorContext,
    NotNull
} from 'camunda-connector-sdk'

class myDTO {
    @NotNull @Secret auth!: string
    @NotNull lat!: string
    @NotNull long!: string
    mightbe?: number
}

@OutboundConnector({
    name: "Test Connector",
    type: "io.camunda:connector-1",
    inputVariables: ["auth", "lat", "long", "mightbe"]
})
export class MyConnector implements OutboundConnectorFunction {
    async execute(context: OutboundConnectorContext) {
        const vars = context.getVariablesAsType(myDTO)
        context.validate(vars)
        context.replaceSecrets(vars)

        try {
            const outcome = await this.businessLogic(vars)
            
            // How to signal success, failure, or error

            if (outcome.status === 'OK') {
                // any return value is added to the process variables
                return { result: outcome.result }
            }

            if (outcome.status === 'BUSINESS_ERROR') {
                // Throw a BPMNError to raise a BPMN Error in the engine
                throw new BPMNError(outcome.message)
            }
        } catch (e: any) {
            // Throw to fail the job
            throw new Error('Technical error: ' + e.message)
        }
    }

    async businessLogic(vars: myDTO): string {
        // some business logic here
        // throw here to bubble up technical failure to the execute method
        return worked ? {
            status: 'OK',
            result
         } : {
            status: 'BUSINESS_ERROR'
            message
         }
    }
}

To expose your connector for Connector Runtimes, in the index.ts of your module, export your connector class as Connector, like this:

import { MyConnector } from "./lib/MyConnector"
const Connector = MyConnector
export Connector

This provides a normalised interface for Connector Runtimes to be able to load your connector by convention.

For the Job Worker Connector Runtime see connector-runtime-worker.