Client Reference

class pyzeebe.ZeebeClient(hostname: str = None, port: int = None, credentials: pyzeebe.credentials.base_credentials.BaseCredentials = None, channel: grpc.Channel = None, secure_connection: bool = False, max_connection_retries: int = 10)

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

cancel_workflow_instance(workflow_instance_key: int) → int

Cancel a running workflow instance

Parameters:

workflow_instance_key (int) – The key of the running workflow to cancel
Returns:

The workflow_instance_key
Return type:

int
Raises:
  • WorkflowInstanceNotFound – If no workflow instance with workflow_instance_key exists
  • ZeebeBackPressure – If Zeebe is currently in back pressure (too many requests)
  • ZeebeGatewayUnavailable – If the Zeebe gateway is unavailable
  • ZeebeInternalError – If Zeebe experiences an internal error
deploy_workflow(*workflow_file_path) → None

Deploy one or more workflows

Parameters:

workflow_file_path (str) – The file path to a workflow definition file (bpmn/yaml)
Raises:
  • WorkflowInvalid – If one of the workflow file definitions is invalid
  • ZeebeBackPressure – If Zeebe is currently in back pressure (too many requests)
  • ZeebeGatewayUnavailable – If the Zeebe gateway is unavailable
  • ZeebeInternalError – If Zeebe experiences an internal error
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:
  • MessageAlreadyExist – If a message with message_id already exists
  • ZeebeBackPressure – If Zeebe is currently in back pressure (too many requests)
  • ZeebeGatewayUnavailable – If the Zeebe gateway is unavailable
  • ZeebeInternalError – If Zeebe experiences an internal error
run_workflow(bpmn_process_id: str, variables: Dict[KT, VT] = None, version: int = -1) → int

Run workflow

Parameters:
  • bpmn_process_id (str) – The unique process id of the workflow.
  • variables (dict) – A dictionary containing all the starting variables the workflow needs. Must be JSONable.
  • version (int) – The version of the workflow. Default: -1 (latest)
Returns:

workflow_instance_key, the unique id of the running workflow generated by Zeebe.
Return type:

int
Raises:
  • WorkflowNotFound – No workflow with bpmn_process_id exists
  • InvalidJSON – variables is not JSONable
  • WorkflowHasNoStartEvent – The specified workflow does not have a start event
  • ZeebeBackPressure – If Zeebe is currently in back pressure (too many requests)
  • ZeebeGatewayUnavailable – If the Zeebe gateway is unavailable
  • ZeebeInternalError – If Zeebe experiences an internal error
run_workflow_with_result(bpmn_process_id: str, variables: Dict[KT, VT] = None, version: int = -1, timeout: int = 0, variables_to_fetch: List[str] = None) → Dict[KT, VT]

Run workflow and wait for the result.

Parameters:
  • bpmn_process_id (str) – The unique process id of the workflow.
  • variables (dict) – A dictionary containing all the starting variables the workflow needs. Must be JSONable.
  • version (int) – The version of the workflow. 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 workflow
Returns:

A dictionary of the end state of the workflow instance
Return type:

dict
Raises:
  • WorkflowNotFound – No workflow with bpmn_process_id exists
  • InvalidJSON – variables is not JSONable
  • WorkflowHasNoStartEvent – The specified workflow does not have a start event
  • ZeebeBackPressure – If Zeebe is currently in back pressure (too many requests)
  • ZeebeGatewayUnavailable – If the Zeebe gateway is unavailable
  • ZeebeInternalError – If Zeebe experiences an internal error