@camunda8/sdk
    Preparing search index...

    Class ZeebeGrpcClient

    A client for interacting with a Zeebe broker. With the connection credentials set in the environment, you can use a "zero-conf" constructor with no arguments. All constructor parameters for configuration are optional. If no configuration is provided, the SDK will use environment variables to configure itself. See CamundaSDKConfiguration for the complete list of configuration parameters. Values can be passed in explicitly in code, or set via environment variables (recommended: separate configuration and application logic). Explicitly set values will override environment variables, which are merged into the configuration.

    const zbc = new ZeebeGrpcClient()
    zbc.topology().then(info =>
    console.log(JSON.stringify(info, null, 2))
    )

    Hierarchy (View Summary)

    Index

    Constructors

    • Parameters

      • Optionaloptions: {
            config?: DeepPartial<
                {
                    CAMUNDA_AUTH_STRATEGY: | "BASIC"
                    | "OAUTH"
                    | "BEARER"
                    | "COOKIE"
                    | "NONE";
                    CAMUNDA_BASIC_AUTH_PASSWORD: undefined
                    | string;
                    CAMUNDA_BASIC_AUTH_USERNAME: undefined | string;
                    CAMUNDA_CONSOLE_BASE_URL: undefined | string;
                    CAMUNDA_CONSOLE_CLIENT_ID: undefined | string;
                    CAMUNDA_CONSOLE_CLIENT_SECRET: undefined | string;
                    CAMUNDA_CONSOLE_OAUTH_AUDIENCE: string;
                    CAMUNDA_COOKIE_AUTH_PASSWORD: string;
                    CAMUNDA_COOKIE_AUTH_URL: string;
                    CAMUNDA_COOKIE_AUTH_USERNAME: string;
                    CAMUNDA_CUSTOM_CERT_CHAIN_PATH: undefined | string;
                    CAMUNDA_CUSTOM_PRIVATE_KEY_PATH: undefined | string;
                    CAMUNDA_CUSTOM_ROOT_CERT_PATH: undefined | string;
                    CAMUNDA_CUSTOM_ROOT_CERT_STRING: undefined | string;
                    CAMUNDA_CUSTOM_USER_AGENT_STRING: undefined | string;
                    CAMUNDA_JOB_WORKER_MAX_BACKOFF_MS: number;
                    CAMUNDA_LOG_LEVEL:
                        | "none"
                        | "error"
                        | "http"
                        | "warn"
                        | "info"
                        | "verbose"
                        | "debug"
                        | "silly";
                    CAMUNDA_MODELER_BASE_URL: string;
                    CAMUNDA_MODELER_OAUTH_AUDIENCE: undefined
                    | string;
                    CAMUNDA_OAUTH_DISABLED: boolean;
                    CAMUNDA_OAUTH_TOKEN: undefined | string;
                    CAMUNDA_OAUTH_TOKEN_REFRESH_THRESHOLD_MS: number;
                    CAMUNDA_OAUTH_URL: undefined | string;
                    CAMUNDA_OPERATE_BASE_URL: undefined | string;
                    CAMUNDA_OPERATE_OAUTH_AUDIENCE: string;
                    CAMUNDA_OPTIMIZE_BASE_URL: undefined | string;
                    CAMUNDA_OPTIMIZE_OAUTH_AUDIENCE: string;
                    CAMUNDA_SECURE_CONNECTION: undefined | boolean;
                    CAMUNDA_SUPPORT_LOG_ENABLED: boolean;
                    CAMUNDA_SUPPORT_LOG_FILE_PATH: undefined | string;
                    CAMUNDA_TASKLIST_BASE_URL: undefined | string;
                    CAMUNDA_TASKLIST_OAUTH_AUDIENCE: string;
                    CAMUNDA_TENANT_ID: undefined | string;
                    CAMUNDA_TOKEN_CACHE_DIR: undefined | string;
                    CAMUNDA_TOKEN_DISK_CACHE_DISABLE: boolean;
                    CAMUNDA_TOKEN_SCOPE: undefined | string;
                    CAMUNDA_ZEEBE_OAUTH_AUDIENCE: undefined | string;
                    ZEEBE_ADDRESS: undefined | string;
                    ZEEBE_CLIENT_ID: undefined | string;
                    ZEEBE_CLIENT_SECRET: undefined | string;
                    ZEEBE_GRPC_ADDRESS: string;
                    ZEEBE_REST_ADDRESS: string;
                    ZEEBE_TOKEN_AUDIENCE: string;
                    zeebeGrpcSettings: {
                        GRPC_HTTP2_MAX_PINGS_WITHOUT_DATA: number;
                        GRPC_HTTP2_MIN_PING_INTERVAL_WITHOUT_DATA_MS: number;
                        GRPC_HTTP2_MIN_TIME_BETWEEN_PINGS_MS: number;
                        GRPC_INITIAL_RECONNECT_BACKOFF_MS: string | 1000;
                        GRPC_KEEPALIVE_PERMIT_WITHOUT_CALLS: number;
                        GRPC_KEEPALIVE_TIME_MS: number;
                        GRPC_KEEPALIVE_TIMEOUT_MS: number;
                        GRPC_MAX_RECONNECT_BACKOFF_MS: string | 10000;
                        GRPC_MIN_RECONNECT_BACKOFF_MS: string | 5000;
                        ZEEBE_CLIENT_LOG_LEVEL: "NONE" | "DEBUG" | "INFO";
                        ZEEBE_CLIENT_LOG_TYPE: "JSON" | "SIMPLE";
                        ZEEBE_GRPC_CLIENT_CONNECTION_TOLERANCE_MS: number;
                        ZEEBE_GRPC_CLIENT_EAGER_CONNECT: boolean;
                        ZEEBE_GRPC_CLIENT_INITIAL_CONNECTION_TOLERANCE_MS: undefined | number;
                        ZEEBE_GRPC_CLIENT_MAX_RETRIES: number;
                        ZEEBE_GRPC_CLIENT_MAX_RETRY_TIMEOUT_SECONDS: number;
                        ZEEBE_GRPC_CLIENT_RETRY: boolean;
                        ZEEBE_GRPC_WORKER_LONGPOLL_SECONDS: number;
                        ZEEBE_GRPC_WORKER_POLL_INTERVAL_MS: number;
                        ZEEBE_INSECURE_CONNECTION: undefined | boolean;
                    };
                },
            >;
            oAuthProvider?: IHeadersProvider<AuthHeader>;
        }

      Returns ZeebeGrpcClient

    Properties

    connected?: boolean = undefined
    connectionTolerance: MaybeTimeDuration
    gatewayAddress: string
    loglevel: Loglevel
    onConnectionError?: (err: Error) => void
    onReady?: () => void
    readied: boolean = false

    Methods

    • Cancel a process instance by process instance key.

      Parameters

      • processInstanceKey: string
      • OptionaloperationReference: number | LosslessNumber

      Returns Promise<void>

      const zbc = new ZeebeGrpcClient()

      zbc.cancelProcessInstance(processInstanceId)
      .catch(
      (e: any) => console.log(`Error cancelling instance: ${e.message}`)
      )
    • Gracefully shut down all workers, draining existing tasks, and return when it is safe to exit.

      Parameters

      • Optionaltimeout: number

      Returns Promise<null>

      const zbc = new ZeebeGrpcClient()

      zbc.createWorker({
      taskType:
      })

      setTimeout(async () => {
      await zbc.close()
      console.log('All work completed.')
      }),
      5 * 60 * 1000 // 5 mins
      )
    • Explicitly complete a job. The method is useful for manually constructing a worker.

      Parameters

      Returns Promise<void>

      const zbc = new ZeebeGrpcClient()
      zbc.activateJobs({
      maxJobsToActivate: 5,
      requestTimeout: 6000,
      timeout: 5 * 60 * 1000,
      type: 'process-payment',
      worker: 'my-worker-uuid'
      }).then(jobs =>
      jobs.forEach(job =>
      // business logic
      zbc.completeJob({
      jobKey: job.key,
      variables: {}
      ))
      )
      })
    • Delete a resource.

      Parameters

      • resourceId: { operationReference?: number | LosslessNumber; resourceKey: string }

        The key of the resource that should be deleted. This can either be the key of a process definition, the key of a decision requirements definition or the key of a form.

      Returns Promise<Record<string, never>>

    • Deploys a single resources (e.g. process or decision model) to Zeebe.

      Errors: PERMISSION_DENIED:

      • if a deployment to an unauthorized tenant is performed INVALID_ARGUMENT:
      • no resources given.
      • if at least one resource is invalid. A resource is considered invalid if:
        • the content is not deserializable (e.g. detected as BPMN, but it's broken XML)
        • the content is invalid (e.g. an event-based gateway has an outgoing sequence flow to a task)
      • if multi-tenancy is enabled, and:
        • a tenant id is not provided
        • a tenant id with an invalid format is provided
      • if multi-tenancy is disabled and a tenant id is provided

      Parameters

      • resource:
            | { processFilename: string; tenantId?: string }
            | { name: string; process: Buffer; tenantId?: string }

      Returns Promise<DeployResourceResponse<ProcessDeployment>>

      import {join} from 'path'
      const zbc = new ZeebeGrpcClient()

      zbc.deployResource({ processFilename: join(process.cwd(), 'bpmn', 'onboarding.bpmn' })
      zbc.deployResource({ decisionFilename: join(process.cwd(), 'dmn', 'approval.dmn')})
    • Deploys a single resources (e.g. process or decision model) to Zeebe.

      Errors: PERMISSION_DENIED:

      • if a deployment to an unauthorized tenant is performed INVALID_ARGUMENT:
      • no resources given.
      • if at least one resource is invalid. A resource is considered invalid if:
        • the content is not deserializable (e.g. detected as BPMN, but it's broken XML)
        • the content is invalid (e.g. an event-based gateway has an outgoing sequence flow to a task)
      • if multi-tenancy is enabled, and:
        • a tenant id is not provided
        • a tenant id with an invalid format is provided
      • if multi-tenancy is disabled and a tenant id is provided

      Parameters

      • resource:
            | { decisionFilename: string; tenantId?: string }
            | { decision: Buffer; name: string; tenantId?: string }

      Returns Promise<DeployResourceResponse<DecisionDeployment>>

      import {join} from 'path'
      const zbc = new ZeebeGrpcClient()

      zbc.deployResource({ processFilename: join(process.cwd(), 'bpmn', 'onboarding.bpmn' })
      zbc.deployResource({ decisionFilename: join(process.cwd(), 'dmn', 'approval.dmn')})
    • Deploys a single resources (e.g. process or decision model) to Zeebe.

      Errors: PERMISSION_DENIED:

      • if a deployment to an unauthorized tenant is performed INVALID_ARGUMENT:
      • no resources given.
      • if at least one resource is invalid. A resource is considered invalid if:
        • the content is not deserializable (e.g. detected as BPMN, but it's broken XML)
        • the content is invalid (e.g. an event-based gateway has an outgoing sequence flow to a task)
      • if multi-tenancy is enabled, and:
        • a tenant id is not provided
        • a tenant id with an invalid format is provided
      • if multi-tenancy is disabled and a tenant id is provided

      Parameters

      • resource:
            | { formFilename: string; tenantId?: string }
            | { form: Buffer; name: string; tenantId?: string }

      Returns Promise<DeployResourceResponse<FormDeployment>>

      import {join} from 'path'
      const zbc = new ZeebeGrpcClient()

      zbc.deployResource({ processFilename: join(process.cwd(), 'bpmn', 'onboarding.bpmn' })
      zbc.deployResource({ decisionFilename: join(process.cwd(), 'dmn', 'approval.dmn')})
    • Deploys one or more resources (e.g. processes or decision models) to Zeebe. Note that this is an atomic call, i.e. either all resources are deployed, or none of them are.

      Errors: PERMISSION_DENIED:

      • if a deployment to an unauthorized tenant is performed INVALID_ARGUMENT:
      • no resources given.
      • if at least one resource is invalid. A resource is considered invalid if:
        • the content is not deserializable (e.g. detected as BPMN, but it's broken XML)
        • the content is invalid (e.g. an event-based gateway has an outgoing sequence flow to a task)
      • if multi-tenancy is enabled, and:
        • a tenant id is not provided
        • a tenant id with an invalid format is provided
      • if multi-tenancy is disabled and a tenant id is provided

      Parameters

      • resources: Resource[]
      • OptionaltenantId: string

      Returns Promise<DeployResourceResponse<unknown>>

      const zbc = new ZeebeGrpcClient()

      const result = await zbc.deployResources([
      {
      processFilename: './src/__tests__/testdata/Client-DeployWorkflow.bpmn',
      },
      {
      decisionFilename: './src/__tests__/testdata/quarantine-duration.dmn',
      },
      {
      form: fs.readFileSync('./src/__tests__/testdata/form_1.form'),
      name: 'form_1.form',
      },
      ])
    • Type Parameters

      • K extends EventKey<
            {
                backoff: "backoff";
                close: "close";
                connectionError: "connectionError";
                ready: "ready";
                streamError: "streamError";
                unknown: "unknown";
            },
        >

      Parameters

      • eventName: K
      • Optionalparams: {
            backoff: "backoff";
            close: "close";
            connectionError: "connectionError";
            ready: "ready";
            streamError: "streamError";
            unknown: "unknown";
        }[K]

      Returns void

    • Evaluates a decision. The decision to evaluate can be specified either by using its unique key (as returned by DeployResource), or using the decision ID. When using the decision ID, the latest deployed version of the decision is used.

      Parameters

      Returns Promise<EvaluateDecisionResponse>

      const zbc = new ZeebeGrpcClient()
      zbc.evaluateDecision({
      decisionId: 'my-decision',
      variables: { season: "Fall" }
      }).then(res => console.log(JSON.stringify(res, null, 2
    • Fail a job. This is useful if you are using the decoupled completion pattern or building your own worker. For the retry count, the current count is available in the job metadata.

      Parameters

      Returns Promise<void>

      const zbc = new ZeebeGrpcClient()
      zbc.failJob( {
      jobKey: '345424343451',
      retries: 3,
      errorMessage: 'Could not get a response from the order invoicing API',
      retryBackOff: 30 * 1000 // optional, otherwise available for reactivation immediately
      })
    • Return an array of task types contained in a BPMN file or array of BPMN files. This can be useful, for example, to do

      Parameters

      • files: string | string[]

      Returns Promise<string[]>

      const zbc = new ZeebeGrpcClient()
      zbc.getServiceTypesFromBpmn(['bpmn/onboarding.bpmn', 'bpmn/process-sale.bpmn'])
      .then(tasktypes => console.log('The task types are:', tasktypes))
    • Type Parameters

      • K extends EventKey<
            {
                backoff: "backoff";
                close: "close";
                connectionError: "connectionError";
                ready: "ready";
                streamError: "streamError";
                unknown: "unknown";
            },
        >

      Parameters

      • eventName: K
      • fn: EventReceiver<
            {
                backoff: "backoff";
                close: "close";
                connectionError: "connectionError";
                ready: "ready";
                streamError: "streamError";
                unknown: "unknown";
            }[K],
        >

      Returns void

    • Type Parameters

      • K extends EventKey<
            {
                backoff: "backoff";
                close: "close";
                connectionError: "connectionError";
                ready: "ready";
                streamError: "streamError";
                unknown: "unknown";
            },
        >

      Parameters

      • eventName: K
      • fn: EventReceiver<
            {
                backoff: "backoff";
                close: "close";
                connectionError: "connectionError";
                ready: "ready";
                streamError: "streamError";
                unknown: "unknown";
            }[K],
        >

      Returns ZeebeGrpcClient

    • Resolve an incident by incident key.

      Parameters

      Returns Promise<void>

      type JSONObject = {[key: string]: string | number | boolean | JSONObject}

      const zbc = new ZeebeGrpcClient()

      async updateAndResolveIncident({
      processInstanceId,
      incidentKey,
      variables
      } : {
      processInstanceId: string,
      incidentKey: string,
      variables: JSONObject
      }) {
      await zbc.setVariables({
      elementInstanceKey: processInstanceId,
      variables
      })
      await zbc.updateRetries()
      zbc.resolveIncident({
      incidentKey
      })
      zbc.resolveIncident(incidentKey)
      }
    • Directly modify the variables is a process instance. This can be used with resolveIncident to update the process and resolve an incident.

      Type Parameters

      Parameters

      Returns Promise<void>

      type JSONObject = {[key: string]: string | number | boolean | JSONObject}

      const zbc = new ZeebeGrpcClient()

      async function updateAndResolveIncident({
      incidentKey,
      processInstanceKey,
      jobKey,
      variableUpdate
      } : {
      incidentKey: string
      processInstanceKey: string
      jobKey: string
      variableUpdate: JSONObject
      }) {
      await zbc.setVariables({
      elementInstanceKey: processInstanceKey,
      variables: variableUpdate
      })
      await zbc.updateJobRetries({
      jobKey,
      retries: 1
      })
      return zbc.resolveIncident({
      incidentKey
      })
      }
    • Create a worker that uses the StreamActivatedJobs RPC to activate jobs. NOTE: This will only stream jobs created after the worker is started. To activate existing jobs, use activateJobs or createWorker.

      Type Parameters

      Parameters

      Returns Promise<{ close: () => void }>

      const zbc = new ZB.ZeebeGrpcClient()

      const zbStreamWorker = zbc.streamJobs({
      type: 'demo-service',
      worker: 'my-worker-uuid',
      taskHandler: myTaskHandler,
      timeout: 30000 // 30 seconds
      })

      ....
      // Close the worker stream when done
      zbStreamWorker.close()

      // A job handler must return one of job.complete, job.fail, job.error, or job.forward
      // Note: unhandled exceptions in the job handler cause the library to call job.fail
      async function myTaskHandler(job) {
      zbWorker.log('Task variables', job.variables)

      // Task worker business logic goes here
      const updateToBrokerVariables = {
      updatedProperty: 'newValue',
      }

      const res = await callExternalSystem(job.variables)

      if (res.code === 'SUCCESS') {
      return job.complete({
      ...updateToBrokerVariables,
      ...res.values
      })
      }
      if (res.code === 'BUSINESS_ERROR') {
      return job.error({
      code: res.errorCode,
      message: res.message
      })
      }
      if (res.code === 'ERROR') {
      return job.fail({
      errorMessage: res.message,
      retryBackOff: 2000
      })
      }
      }
    • Fail a job by throwing a business error (i.e. non-technical) that occurs while processing a job. The error is handled in the workflow by an error catch event. If there is no error catch event with the specified errorCode then an incident will be raised instead. This method is useful when building a worker, for example for the decoupled completion pattern.

      Parameters

      Returns Promise<void>

      type JSONObject = {[key: string]: string | number | boolean | JSONObject}

      interface errorResult {
      resultType: 'ERROR' as 'ERROR'
      errorCode: string
      errorMessage: string
      }

      interface successResult {
      resultType: 'SUCCESS' as 'SUCCESS'
      variableUpdate: JSONObject
      }

      type Result = errorResult | successResult

      const zbc = new ZeebeGrpcClient()


      // This could be a listener on a return queue from an external system
      async function handleJob(jobKey: string, result: Result) {
      if (resultType === 'ERROR') {
      const { errorMessage, errorCode } = result
      zbc.throwError({
      jobKey,
      errorCode,
      errorMessage
      })
      } else {
      zbc.completeJob({
      jobKey,
      variables: result.variableUpdate
      })
      }
      }
    • Update the number of retries for a Job. This is useful if a job has zero remaining retries and fails, raising an incident.

      Parameters

      Returns Promise<void>

      type JSONObject = {[key: string]: string | number | boolean | JSONObject}

      const zbc = new ZeebeGrpcClient()

      async function updateAndResolveIncident({
      incidentKey,
      processInstanceKey,
      jobKey,
      variableUpdate
      } : {
      incidentKey: string
      processInstanceKey: string
      jobKey: string
      variableUpdate: JSONObject
      }) {
      await zbc.setVariables({
      elementInstanceKey: processInstanceKey,
      variables: variableUpdate
      })
      await zbc.updateJobRetries({
      jobKey,
      retries: 1
      })
      return zbc.resolveIncident({
      incidentKey
      })
      }
    • Updates the deadline of a job using the timeout (in ms) provided. This can be used for extending or shortening the job deadline.

      Errors: NOT_FOUND: - no job exists with the given key

      INVALID_STATE: - no deadline exists for the given job key

      Parameters

      Returns Promise<void>