camunda-external-task-client

Implement your BPMN Service Task in NodeJS.

This package is an ECMAScript module (ESM) and provides no CommonJS exports.

NodeJS >= v18 is required

Installing

1npm install -s camunda-external-task-client-js

Or:

1yarn add camunda-external-task-client-js

Usage

1. Make sure to have Camunda running.
2. Create a simple process model with an External Service Task and define the topic as 'topicName'.
3. Deploy the process to the Camunda Platform engine.
4. In your NodeJS script:

1import { Client, logger } from "camunda-external-task-client-js";
2
3// configuration for the Client:
4//  - 'baseUrl': url to the Process Engine
5//  - 'logger': utility to automatically log important events
6const config = { baseUrl: "http://localhost:8080/engine-rest", use: logger };
7
8// create a Client instance with custom configuration
9const client = new Client(config);
10
11// susbscribe to the topic: 'creditScoreChecker'
12client.subscribe("creditScoreChecker", async function({ task, taskService }) {
13  // Put your business logic
14  // complete the task
15  await taskService.complete(task);
16});

Note: Although the examples used in this documentation use async await for handling asynchronous calls, you can also use Promises to achieve the same results.

About External Tasks

External Tasks are service tasks whose execution differs particularly from the execution of other service tasks (e.g. Human Tasks). The execution works in a way that units of work are polled from the engine before being completed.

camunda-external-task-client.js allows you to create easily such client in NodeJS.

Features

Fetch and Lock

Done through polling.

Complete

1// Susbscribe to the topic: 'topicName'
2client.subscribe("topicName", async function({ task, taskService }) {
3  // Put your business logic
4  // Complete the task
5  await taskService.complete(task);
6});

Handle Failure

1// Susbscribe to the topic: 'topicName'
2client.subscribe("topicName", async function({ task, taskService }) {
3  // Put your business logic
4  // Handle a Failure
5  await taskService.handleFailure(task, {
6    errorMessage: "some failure message",
7    errorDetails: "some details",
8    retries: 1,
9    retryTimeout: 1000
10  });
11
12});

Handle BPMN Error

1// Susbscribe to the topic: 'topicName'
2client.subscribe("topicName", async function({ task, taskService }) {
3  // Put your business logic
4
5  // Create some variables
6  const variables = new Variables().set('date', new Date());
7
8  // Handle a BPMN Failure
9  await taskService.handleBpmnError(task, "BPMNError_Code", "Error message", variables);
10});

Extend Lock

1// Susbscribe to the topic: 'topicName'
2client.subscribe("topicName", async function({ task, taskService }) {
3  // Put your business logic
4  // Extend the lock time
5  await taskService.extendLock(task, 5000);
6});

Unlock

1// Susbscribe to the topic: 'topicName'
2client.subscribe("topicName", async function({ task, taskService }) {
3  // Put your business logic
4  // Unlock the task
5  await taskService.unlock(task);
6});

Lock

1// Susbscribe to the topic: 'topicName'
2client.subscribe("topicName", async function({ task, taskService }) {
3  // Task is locked by default
4  // Put your business logic, unlock the task or let the lock expire
5
6  // Lock a task again
7  await taskService.lock(task, 5000);
8});

Exchange Process & Local Task Variables

1import { Variables } from "camunda-external-task-client-js";
2
3client.subscribe("topicName", async function({ task, taskService }) {
4  // get the process variable 'score'
5  const score = task.variables.get("score");
6
7  // set a process variable 'winning'
8  const processVariables = new Variables();
9  processVariables.set("winning", score > 5);
10
11  // set a local variable 'winningDate'
12  const localVariables = new Variables();
13  localVariables.set("winningDate", new Date());
14
15  // complete the task
16  await taskService.complete(task, processVariables, localVariables);
17});

API

• Client
  • new Client(options)
  • client.start()
  • client.subscribe(topic, [options], handler)
  • client.stop()
  • Client Events)
  • About the Handler Function
• Variables
  • new Variables(options)
  • variables.get(variableName)
  • variables.getTyped(variableName)
  • variables.getAll()
  • variables.getAllTyped()
  • variables.set(variableName)
  • variables.setTyped(variableName)
  • variables.setAll(values)
  • variables.setAllTyped(typedValues)
  • About JSON & Date Variables
• File
  • new File(options)
  • file.load()
  • File Properties
• BasicAuthInterceptor
  • new BasicAuthInterceptor(options)
• KeycloakAuthInterceptor
  • new KeycloakAuthInterceptor(options)
• logger
  • logger.success(text)
  • logger.error(text)

Contributing

Have a look at our contribution guide for how to contribute to this repository.

Help and support

• Documentation
• Forum
• Stackoverflow

License

The source files in this repository are made available under the Apache License Version 2.0.