Camunda External Task Client for NodeJS

To use the client, follow these steps:

1. Ensure Camunda is running.
2. Create a BPMN process with an External Service Task and define a topic name (e.g., creditScoreChecker).
3. Deploy the process to the Camunda engine.
4. Use the Client to subscribe to the topic and handle tasks using the provided taskService.

Note: While examples use async/await, you can also use Promises.

import { Client, logger } from "camunda-external-task-client-js";

// configuration for the Client:
//  - 'baseUrl': url to the Process Engine
//  - 'logger': utility to automatically log important events
const config = { baseUrl: "http://localhost:8080/engine-rest", use: logger };

// create a Client instance with custom configuration
const client = new Client(config);

// subscribe to the topic: 'creditScoreChecker'
client.subscribe("creditScoreChecker", async function({ task, taskService }) {
  // Put your business logic
  // complete the task
  await taskService.complete(task);
});

The Variables class automatically handles serialization and deserialization for Date and JSON types.

Date Variables

• Setting: You can pass a JavaScript Date object directly to .set() or .setTyped(). Alternatively, you can pass a date string to .setTyped() with type: "date".
• Getting: .get() and .getTyped().value will return a JavaScript Date object.

JSON Variables

• Setting: You can pass a JavaScript object directly to .set() or .setTyped(). The type will be automatically detected as json.
• Getting: .get() and .getTyped().value will return the original JavaScript object.

// --- Date Example ---
variables.set("someDate", new Date());

// Setting via string in setTyped
variables.setTyped("anotherDate", { 
  type: "date", 
  value: "2016-01-25T13:33:42.165+0100", 
  valueInfo: {}
});

console.log(typeof variables.get("anotherDate")); // "object" (a Date instance)

// --- JSON Example ---
variables.set("meal", { id: 0, name: "pasta" });

const meal = variables.get("meal");
console.log(meal.name); // "pasta"

A handler function is an asynchronous function used to process a fetched task. It receives an object containing the task and the taskService. You use the taskService to communicate the outcome of your business logic back to the Camunda engine (e.g., completing the task, handling failures, or extending locks).

To use a handler, subscribe to a specific topic using client.subscribe(topicName, handler).

const { Client, logger, Variables } = require("camunda-external-task-client-js");

// create a Client instance with custom configuration
const client = new Client({ baseUrl: "http://localhost:8080/engine-rest", use: logger });

// create a handler function
const handler = async function({ task, taskService }) {
  // get the process variable 'score'
  const score = Variables.get("score");
  // set a process variable 'winning'
  const processVariables = new Variables().set("winning", score > 5);
  // set a local variable 'winningDate'
  const localVariables = new Variables().set("winningDate", new Date());

  // complete the task
  await taskService.complete(task, processVariables, localVariables);
};

// susbscribe to the topic: 'topicName'
client.subscribe("topicName", handler);

If your Camunda REST API is protected by Keycloak Gatekeeper, use the KeycloakAuthInterceptor to automatically add a Bearer token header to all requests. This interceptor handles the OpenID Connect flow by requesting a token from the Keycloak token endpoint using a client ID and client secret.

To use it, instantiate KeycloakAuthInterceptor with your Keycloak configuration and pass the instance into the interceptors array of the Client constructor.

const {
  Client,
  KeycloakAuthInterceptor
} = require("camunda-external-task-client-js");

const keycloakAuthentication = new KeycloakAuthInterceptor({
  tokenEndpoint: "https://your.keyclock.domain/realms/your-realm/protocol/openid-connect/token",
  clientId: "your-client-id",
  clientSecret: "your-client-secret"
});

const client = new Client({
  baseUrl: "http://localhost:8080/engine-rest",
  interceptors: keycloakAuthentication
});