Client Reference

class pyzeebe.ZeebeClient(grpc_channel: Channel, max_connection_retries: int = 10)

A zeebe client that can connect to a zeebe instance and perform actions.

__init__(grpc_channel: Channel, max_connection_retries: int = 10) → None

Parameters:

grpc_channel (grpc.aio.Channel) – GRPC Channel connected to a Zeebe gateway
max_connection_retries (int) – Amount of connection retries before client gives up on connecting to zeebe. To setup with infinite retries use -1

async cancel_process_instance(process_instance_key: int) → CancelProcessInstanceResponse

Cancel a running process instance

Parameters:

process_instance_key (int) – The key of the running process to cancel

Returns:

response from Zeebe.

Return type:

CancelProcessInstanceResponse

Raises:

ProcessInstanceNotFoundError – If no process instance with process_instance_key exists
ZeebeBackPressureError – If Zeebe is currently in back pressure (too many requests)
ZeebeGatewayUnavailableError – If the Zeebe gateway is unavailable
ZeebeInternalError – If Zeebe experiences an internal error
UnknownGrpcStatusCodeError – If Zeebe returns an unexpected status code

async deploy_resource(*resource_file_path: str, tenant_id: str | None = None) → DeployResourceResponse

Deploy one or more processes

New in Zeebe 8.0.

Parameters:

resource_file_path (str) – The file path to a resource definition file (bpmn/dmn/form)
tenant_id (str) – The tenant ID of the resources to deploy. New in Zeebe 8.3.

Returns:

response from Zeebe.

Return type:

DeployResourceResponse

Raises:

ProcessInvalidError – If one of the process file definitions is invalid
ZeebeBackPressureError – If Zeebe is currently in back pressure (too many requests)
ZeebeGatewayUnavailableError – If the Zeebe gateway is unavailable
ZeebeInternalError – If Zeebe experiences an internal error
UnknownGrpcStatusCodeError – If Zeebe returns an unexpected status code

async publish_message(name: str, correlation_key: str, variables: Variables | None = None, time_to_live_in_milliseconds: int = 60000, message_id: str | None = None, tenant_id: str | None = None) → PublishMessageResponse

Publish a message

Parameters:

name (str) – The message name
correlation_key (str) – The correlation key. For more info: https://docs.zeebe.io/glossary.html?highlight=correlation#correlation-key
variables (dict) – The variables the message should contain.
time_to_live_in_milliseconds (int) – How long this message should stay active. Default: 60000 ms (60 seconds)
message_id (str) – A unique message id. Useful for avoiding duplication. If a message with this id is still active, a MessageAlreadyExists will be raised.
tenant_id (str) – The tenant ID of the message. New in Zeebe 8.3.

Returns:

response from Zeebe.

Return type:

PublishMessageResponse

Raises:

MessageAlreadyExistsError – If a message with message_id already exists
ZeebeBackPressureError – If Zeebe is currently in back pressure (too many requests)
ZeebeGatewayUnavailableError – If the Zeebe gateway is unavailable
ZeebeInternalError – If Zeebe experiences an internal error
UnknownGrpcStatusCodeError – If Zeebe returns an unexpected status code

async run_process(bpmn_process_id: str, variables: Variables | None = None, version: int = -1, tenant_id: str | None = None) → CreateProcessInstanceResponse

Run process

Parameters:

bpmn_process_id (str) – The unique process id of the process.
variables (dict) – A dictionary containing all the starting variables the process needs. Must be JSONable.
version (int) – The version of the process. Default: -1 (latest)
tenant_id (str) – The tenant ID of the process definition. New in Zeebe 8.3.

Returns:

response from Zeebe.

Return type:

CreateProcessInstanceResponse

Raises:

ProcessDefinitionNotFoundError – No process with bpmn_process_id exists
InvalidJSONError – variables is not JSONable
ProcessDefinitionHasNoStartEventError – The specified process does not have a start event
ZeebeBackPressureError – If Zeebe is currently in back pressure (too many requests)
ZeebeGatewayUnavailableError – If the Zeebe gateway is unavailable
ZeebeInternalError – If Zeebe experiences an internal error
UnknownGrpcStatusCodeError – If Zeebe returns an unexpected status code

async run_process_with_result(bpmn_process_id: str, variables: Variables | None = None, version: int = -1, timeout: int = 0, variables_to_fetch: Iterable[str] | None = None, tenant_id: str | None = None) → CreateProcessInstanceWithResultResponse

Run process and wait for the result.

Parameters:

bpmn_process_id (str) – The unique process id of the process.
variables (dict) – A dictionary containing all the starting variables the process needs. Must be JSONable.
version (int) – The version of the process. Default: -1 (latest)
timeout (int) – How long to wait until a timeout occurs. Default: 0 (Zeebe default timeout)
variables_to_fetch (list[str]) – Which variables to get from the finished process
tenant_id (str) – The tenant ID of the process definition. New in Zeebe 8.3.

Returns:

response from Zeebe.

Return type:

CreateProcessInstanceWithResultResponse

Raises:

ProcessDefinitionNotFoundError – No process with bpmn_process_id exists
InvalidJSONError – variables is not JSONable
ProcessDefinitionHasNoStartEventError – The specified process does not have a start event
ProcessTimeoutError – The process was not finished within the set timeout
ZeebeBackPressureError – If Zeebe is currently in back pressure (too many requests)
ZeebeGatewayUnavailableError – If the Zeebe gateway is unavailable
ZeebeInternalError – If Zeebe experiences an internal error
UnknownGrpcStatusCodeError – If Zeebe returns an unexpected status code

class pyzeebe.SyncZeebeClient(grpc_channel: Channel, max_connection_retries: int = 10)

__init__(grpc_channel: Channel, max_connection_retries: int = 10) → None

cancel_process_instance(process_instance_key: int) → CancelProcessInstanceResponse

Cancel a running process instance

Parameters:

process_instance_key (int) – The key of the running process to cancel

Returns:

response from Zeebe.

Return type:

CancelProcessInstanceResponse

Raises:

ProcessInstanceNotFoundError – If no process instance with process_instance_key exists
ZeebeBackPressureError – If Zeebe is currently in back pressure (too many requests)
ZeebeGatewayUnavailableError – If the Zeebe gateway is unavailable
ZeebeInternalError – If Zeebe experiences an internal error
UnknownGrpcStatusCodeError – If Zeebe returns an unexpected status code

deploy_resource(*resource_file_path: str, tenant_id: str | None = None) → DeployResourceResponse

Deploy one or more processes

New in Zeebe 8.0.

Parameters:

resource_file_path (str) – The file path to a resource definition file (bpmn/dmn/form)
tenant_id (str) – The tenant ID of the resources to deploy. New in Zeebe 8.3.

Returns:

response from Zeebe.

Return type:

DeployResourceResponse

Raises:

ProcessInvalidError – If one of the process file definitions is invalid
ZeebeBackPressureError – If Zeebe is currently in back pressure (too many requests)
ZeebeGatewayUnavailableError – If the Zeebe gateway is unavailable
ZeebeInternalError – If Zeebe experiences an internal error
UnknownGrpcStatusCodeError – If Zeebe returns an unexpected status code

publish_message(name: str, correlation_key: str, variables: Variables | None = None, time_to_live_in_milliseconds: int = 60000, message_id: str | None = None, tenant_id: str | None = None) → PublishMessageResponse

Publish a message

Parameters:

name (str) – The message name
correlation_key (str) – The correlation key. For more info: https://docs.zeebe.io/glossary.html?highlight=correlation#correlation-key
variables (dict) – The variables the message should contain.
time_to_live_in_milliseconds (int) – How long this message should stay active. Default: 60000 ms (60 seconds)
message_id (str) – A unique message id. Useful for avoiding duplication. If a message with this id is still active, a MessageAlreadyExists will be raised.
tenant_id (str) – The tenant ID of the message. New in Zeebe 8.3.

Returns:

response from Zeebe.

Return type:

PublishMessageResponse

Raises:

MessageAlreadyExistsError – If a message with message_id already exists
ZeebeBackPressureError – If Zeebe is currently in back pressure (too many requests)
ZeebeGatewayUnavailableError – If the Zeebe gateway is unavailable
ZeebeInternalError – If Zeebe experiences an internal error
UnknownGrpcStatusCodeError – If Zeebe returns an unexpected status code

run_process(bpmn_process_id: str, variables: Variables | None = None, version: int = -1, tenant_id: str | None = None) → CreateProcessInstanceResponse

Run process

Parameters:

bpmn_process_id (str) – The unique process id of the process.
variables (dict) – A dictionary containing all the starting variables the process needs. Must be JSONable.
version (int) – The version of the process. Default: -1 (latest)
tenant_id (str) – The tenant ID of the process definition. New in Zeebe 8.3.

Returns:

response from Zeebe.

Return type:

CreateProcessInstanceResponse

Raises:

ProcessDefinitionNotFoundError – No process with bpmn_process_id exists
InvalidJSONError – variables is not JSONable
ProcessDefinitionHasNoStartEventError – The specified process does not have a start event
ZeebeBackPressureError – If Zeebe is currently in back pressure (too many requests)
ZeebeGatewayUnavailableError – If the Zeebe gateway is unavailable
ZeebeInternalError – If Zeebe experiences an internal error
UnknownGrpcStatusCodeError – If Zeebe returns an unexpected status code

run_process_with_result(bpmn_process_id: str, variables: Variables | None = None, version: int = -1, timeout: int = 0, variables_to_fetch: Iterable[str] | None = None, tenant_id: str | None = None) → CreateProcessInstanceWithResultResponse

Run process and wait for the result.

Parameters:

bpmn_process_id (str) – The unique process id of the process.
variables (dict) – A dictionary containing all the starting variables the process needs. Must be JSONable.
version (int) – The version of the process. Default: -1 (latest)
timeout (int) – How long to wait until a timeout occurs. Default: 0 (Zeebe default timeout)
variables_to_fetch (list[str]) – Which variables to get from the finished process
tenant_id (str) – The tenant ID of the process definition. New in Zeebe 8.3.

Returns:

response from Zeebe.

Return type:

CreateProcessInstanceWithResultResponse

Raises:

ProcessDefinitionNotFoundError – No process with bpmn_process_id exists
InvalidJSONError – variables is not JSONable
ProcessDefinitionHasNoStartEventError – The specified process does not have a start event
ProcessTimeoutError – The process was not finished within the set timeout
ZeebeBackPressureError – If Zeebe is currently in back pressure (too many requests)
ZeebeGatewayUnavailableError – If the Zeebe gateway is unavailable
ZeebeInternalError – If Zeebe experiences an internal error
UnknownGrpcStatusCodeError – If Zeebe returns an unexpected status code