Writing Type-Safe Workers

This section only applies if you are using TypeScript

The job parameter that is passed to your worker handler is, by default, partially typed.

The metadata from the broker is strongly typed, but the customHeaders and variables are typed as any.

The argument that you pass to the complete.success() function is also typed as object.

You can provide explicit type information for these fields to provide greater type-safety and Intellisense support in your IDE.

Explicitly typing Job Variables and the complete function

import { ZBClient } from 'zeebe-node'

interface JobVariables {
    customerId: number

interface CompleteVariables extends JobVariables {
    customerData: CustomerRecord

interface CustomerRecord {
    name: string

const mockData: {[key: number]: CustomerRecord} = {
    1: {
        name: "Joe Bloggs"

const mockDB = {
    get: (id: number): CustomerRecord | undefined => mockData[id]

const zbc = new ZBClient()

zbc.createWorker<JobVariables, any, CompleteVariables>(null, 'get-customer', (job, complete, worker) => {
    const id = job.variables.customerId
    const customer = mockDB.get(id)
    worker.log(`Retrieved customer ${customer?.name}`) // TS 3.7+
    return customer ?
            customerData: customer
        }) :
        complete.failure(`Customer with id ${id} not found`)
// Only applicable to TypeScript

Explicitly typing Custom Headers

Your task instances in the BPM can specify custom headers. You can use this feature to do things like write a generic Slack messaging worker, and derive the message to send from the job variables, and the specify which channel to send it to in the task instance via a custom header:

import { ZBClient } from 'zeebe-node'
import { sendSlackMessage } from './slack'

interface JobVariables {
    message: string

interface CompleteVariables {
    message: '' // erase message after sending

interface CustomHeaders {
    channel: string

const zbc = new ZBClient()

zbc.createWorker<JobVariables, CustomHeaders, CompleteVariables>
async (null, 'send-slack-message', (job, complete, worker) => {
    const { message } = job.variables
    const { channel } = job.customHeaders
    worker.log(`Sending ${message} to ${channel}`)
    try {
        await sendSlackMessage({
        return complete.success({
            message: ''
    } catch (e) {
        return complete.failure(e.message)
// Only applicable to TypeScript

Explicitly typing Task Types

Task types are arbitrary strings. This can lead to hard to diagnose bugs. To aid you in catching these as far forward as possible, the Node client can generate type information from your BPMN files.

Install the zeebe-node package globally:

npm i -g zeebe-node

You now have a zeebe-node command that takes a file path to a .bpmn file, and emits type information to the console.

This will help you to identify all the task types in your process, and also give you type safety for your task types when writing worker handlers.

For example:

➜ zeebe-node src/__tests__/testdata/hello-world.bpmn
import { ZBClient } from "zeebe-node"

const zbc = new ZBClient()

// @TODO Update with the shape of your job variables
// For better intellisense and type-safety
export interface WorkflowVariables {
        [key: string]: any

// Autogenerated constants for hello-world.bpmn

export enum TaskType {
    CONSOLE_LOG = "console-log"

export enum MessageName {
    WAITING_FOR_A_TRAIN_THAT_NEVER_ARRIVES = "Waiting For A Train That Never Arrives"

// Worker for tasks of type "console-log"
interface ConsoleLogCustomHeaders {
    message: string

export const ConsoleLogWorker = zbc.createWorker<
>(null, TaskType.CONSOLE_LOG, (job, complete, worker) => {
// Only applicable to TypeScript