Client Reference

class pyzeebe.ZeebeClient(grpc_channel: grpc.aio._base_channel.Channel, max_connection_retries: int = 10)

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

cancel_process_instance(process_instance_key: int) → int

Cancel a running process instance

Parameters:

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

The process_instance_key
Return type:

int
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
  • UnkownGrpcStatusCodeError – If Zeebe returns an unexpected status code
deploy_process(*process_file_path) → None

Deploy one or more processes

Parameters:

process_file_path (str) – The file path to a process definition file (bpmn/yaml)
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
  • UnkownGrpcStatusCodeError – If Zeebe returns an unexpected status code
publish_message(name: str, correlation_key: str, variables: Dict[KT, VT] = None, time_to_live_in_milliseconds: int = 60000, message_id: str = None) → None

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.
Raises:
  • MessageAlreadyExistError – 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
  • UnkownGrpcStatusCodeError – If Zeebe returns an unexpected status code
run_process(bpmn_process_id: str, variables: Dict[KT, VT] = None, version: int = -1) → int

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)
Returns:

process_instance_key, the unique id of the running process generated by Zeebe.
Return type:

int
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
  • UnkownGrpcStatusCodeError – If Zeebe returns an unexpected status code
run_process_with_result(bpmn_process_id: str, variables: Dict[KT, VT] = None, version: int = -1, timeout: int = 0, variables_to_fetch: List[str] = None) → Tuple[int, Dict[KT, VT]]

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
Returns:

(The process instance key, A dictionary of the end state of the process instance)
Return type:

tuple
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
  • UnkownGrpcStatusCodeError – If Zeebe returns an unexpected status code
class pyzeebe.SyncZeebeClient(grpc_channel: grpc.aio._base_channel.Channel, max_connection_retries: int = 10)
cancel_process_instance(process_instance_key: int) → int

Cancel a running process instance

Parameters:

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

The process_instance_key
Return type:

int
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
  • UnkownGrpcStatusCodeError – If Zeebe returns an unexpected status code
deploy_process(*process_file_path) → None

Deploy one or more processes

Parameters:

process_file_path (str) – The file path to a process definition file (bpmn/yaml)
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
  • UnkownGrpcStatusCodeError – If Zeebe returns an unexpected status code
publish_message(name: str, correlation_key: str, variables: Dict[KT, VT] = None, time_to_live_in_milliseconds: int = 60000, message_id: str = None) → None

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.
Raises:
  • MessageAlreadyExistError – 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
  • UnkownGrpcStatusCodeError – If Zeebe returns an unexpected status code
run_process(bpmn_process_id: str, variables: Dict[KT, VT] = None, version: int = -1) → int

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)
Returns:

process_instance_key, the unique id of the running process generated by Zeebe.
Return type:

int
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
  • UnkownGrpcStatusCodeError – If Zeebe returns an unexpected status code
run_process_with_result(bpmn_process_id: str, variables: Dict[KT, VT] = None, version: int = -1, timeout: int = 0, variables_to_fetch: List[str] = None) → Tuple[int, Dict[KT, VT]]

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
Returns:

(The process instance key, A dictionary of the end state of the process instance)
Return type:

tuple
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
  • UnkownGrpcStatusCodeError – If Zeebe returns an unexpected status code