External Task

This module provides access to the external task REST api of Camunda.

ExternalTask

class pycamunda.externaltask.ExternalTask(activity_id: str, activity_instance_id: str, error_message: str, error_details: str, execution_id: str, id_: str, process_definition_id: str, process_definition_key: str, process_instance_id: str, tenant_id: str, retries: int, worker_id: str, priority: str, topic_name: str, lock_expiration_time: Optional[datetime.datetime] = None, suspended: Optional[bool] = None, business_key: Optional[str] = None, variables: Optional[Dict[str, Dict[str, Any]]] = None)

Data class of external task as returned by the REST api of Camunda.

business_key = None
lock_expiration_time = None
suspended = None
variables = None

Get

class pycamunda.externaltask.Get(url: str, id_: str, request_error_details: bool = True)

Query for an external task.

Parameters:
  • url – Camunda Rest engine URL.
  • id – Id of the external task.
  • request_error_details – Whether to request error details for tasks. Requires an additional request.
__call__(*args, **kwargs) → pycamunda.externaltask.ExternalTask

Send the request.

GetList

class pycamunda.externaltask.GetList(url: str, id_: Optional[str] = None, topic_name: Optional[str] = None, worker_id: Optional[str] = None, locked: bool = False, not_locked: bool = False, with_retries_left: bool = False, no_retries_left: bool = False, lock_expiration_after: Optional[datetime.datetime] = None, lock_expiration_before: Optional[datetime.datetime] = None, activity_id: Optional[str] = None, activity_id_in: Optional[Iterable[str]] = None, execution_id: Optional[str] = None, process_instance_id: Optional[str] = None, process_definition_id: Optional[str] = None, tenant_id_in: Optional[Iterable[str]] = None, active: bool = False, priority_higher_equals: Optional[int] = None, priority_lower_equals: Optional[int] = None, suspended: bool = False, sort_by: Optional[str] = None, ascending: bool = True, first_result: Optional[int] = None, max_results: Optional[int] = None, request_error_details: bool = True)

Query for a list of external tasks using a list of parameters. The size of the result set can be retrieved by using the Get Count request.

Parameters:
  • url – Camunda Rest engine URL.
  • id – Filter by the id of the external task.
  • topic_name – Filter by the topic name of the external task.
  • worker_id – Filter by the id of the worker the task was locked by last.
  • locked – Include only locked external tasks.
  • not_locked – Include only unlocked tasks.
  • with_retries_left – Include only external tasks that have retries left.
  • no_retries_left – Include only external tasks that have no retries left.
  • lock_expiration_after – Include only external tasks with a lock that expires after the provided date.
  • lock_expiration_before – Include only external tasks with a lock that expires before the provided date.
  • activity_id – Filter by activity id the external task is created for.
  • activity_id_in – Filter whether activity id is one of multiple ones.
  • execution_id – Filter by the execution id the external task belongs to.
  • process_instance_id – Filter by the process instance id the external task belongs to.
  • process_definition_id – Filter by the process definition id the external task belongs to.
  • tenant_id_in – Filter whether the tenant id is one of multiple ones.
  • active – Include only external tasks that are active.
  • priority_higher_equals – Include only external tasks with a priority higher than or equals to the given value.
  • priority_lower_equals – Include only external tasks with a priority lower than or equals to the given value.
  • suspended – Include only external tasks that are suspended.
  • sort_by – Sort the results by id_, lock_expiration_time, `process_instance_id, process_definition_key, tenant_id or task_priority.
  • ascending – Sort order.
  • first_result – Pagination of results. Index of the first result to return.
  • max_results – Pagination of results. Maximum number of results to return.
  • request_error_details – Whether to request error details for tasks. Requires additional requests.
__call__(*args, **kwargs) → Tuple[pycamunda.externaltask.ExternalTask]

Send the request.

Count

class pycamunda.externaltask.Count(url: str, id_: Optional[str] = None, topic_name: Optional[str] = None, worker_id: Optional[str] = None, locked: bool = False, not_locked: bool = False, with_retries_left: bool = False, no_retries_left: bool = False, lock_expiration_after: Optional[datetime.datetime] = None, lock_expiration_before: Optional[datetime.datetime] = None, activity_id: Optional[str] = None, activity_id_in: Optional[Iterable[str]] = None, execution_id: Optional[str] = None, process_instance_id: Optional[str] = None, process_definition_id: Optional[str] = None, tenant_id_in: Optional[Iterable[str]] = None, active: bool = False, priority_higher_equals: Optional[int] = None, priority_lower_equals: Optional[int] = None, suspended: bool = False, sort_by: Optional[str] = None, ascending: bool = True, first_result: Optional[int] = None, max_results: Optional[int] = None)

Get the size of the result returned by the Get List request.

Parameters:
  • url – Camunda Rest engine URL.
  • id – Filter by the id of the external task.
  • topic_name – Filter by the topic name of the external task.
  • worker_id – Filter by the id of the worker the task was locked by last.
  • locked – Include only locked external tasks.
  • not_locked – Include only unlocked tasks.
  • with_retries_left – Include only external tasks that have retries left.
  • no_retries_left – Include only external tasks that have no retries left.
  • lock_expiration_after – Include only external tasks with a lock that expires after a date.
  • lock_expiration_before – Include only external tasks with a lock that expires before a date.
  • activity_id – Filter by activity id the external task is created for.
  • activity_id_in – Filter whether activity id is one of multiple ones.
  • execution_id – Filter by the execution id the external task belongs to.
  • process_instance_id – Filter by the process instance id the external task belongs to.
  • process_definition_id – Filter by the process definition id the external task belongs to.
  • tenant_id_in – Filter whether the tenant id is one of multiple ones.
  • active – Include only external tasks that are active.
  • priority_higher_equals – Include only external tasks with a priority higher than or equals to the given value.
  • priority_lower_equals – Include only external tasks with a priority lower than or equals to the given value.
  • suspended – Include only external tasks that are suspended.
  • sort_by – Sort the results by id_, lock_expiration_time, `process_instance_id, process_definition_key, tenant_id or task_priority.
  • ascending – Sort order.
  • first_result – Pagination of results. Index of the first result to return.
  • max_results – Pagination of results. Maximum number of results to return.
__call__(*args, **kwargs) → int

Send the request.

FetchAndLock

class pycamunda.externaltask.FetchAndLock(url: str, worker_id: str, max_tasks: int, async_response_timeout: Optional[int] = None, use_priority: bool = False)

Fetch and lock external tasks for a specific worker. Only external tasks with topics that are added to this request are fetched.

Parameters:
  • url – Camunda Rest engine URL.
  • worker_id – Id of the worker the external tasks are locked for.
  • max_tasks – Maximum number of tasks to fetch.
  • async_response_timeout – Long polling timeout in milliseconds. Cannot be set larger than 1800000 (30 minutes).
  • use_priority – Whether the tasks should be fetched based on their priority.
__call__(*args, **kwargs) → Tuple[pycamunda.externaltask.ExternalTask]

Send the request

add_topic(name: str, lock_duration: int, variables: Optional[Iterable[str]] = None, deserialize_values: bool = False) → None

Add a topic to this request.

Parameters:
  • name – Name of the topic.
  • lock_duration – Duration to lock the fetched external tasks for in milliseconds.
  • variables – Variables to request from the process instance the external task belongs to. If set to None all variables are requested.
  • deserialize_values – Whether serializable variable values are deserialized on server side.

Complete

class pycamunda.externaltask.Complete(url: str, id_: str, worker_id: str)

Complete an external task that is locked for a worker.

Parameters:
  • url – Camunda Rest engine URL.
  • id – Id of the external task.
  • worker_id – Id of the worker the external tasks was locked for.
__call__(*args, **kwargs) → None

Send the request

add_local_variable(name: str, value: str, type_: Optional[str] = None, value_info: Optional[Mapping[KT, VT_co]] = None) → None

Add a local variable to send to Camunda. Local variables are set only in the scope of an external task.

Parameters:
  • name – Name of the variable.
  • value – Value of the variable.
  • type – Value type of the variable.
  • value_info – Additional information regarding the value type.
add_variable(name: str, value: str, type_: Optional[str] = None, value_info: Optional[Mapping[KT, VT_co]] = None) → None

Add a variable to send to the Camunda process instance.

Parameters:
  • name – Name of the variable.
  • value – Value of the variable.
  • type – Value type of the variable.
  • value_info – Additional information regarding the value type.

HandleBPMNError

class pycamunda.externaltask.HandleBPMNError(url: str, id_: str, worker_id: str, error_code: str, error_message: Optional[str] = None)

Report a business error for a running external task.

Parameters:
  • url – Camunda Rest engine URL.
  • id – Id of the external task.
  • worker_id – Id of the worker that locked the external task.
  • error_code – Error code that identifies the predefined error.
  • error_message – Error message that describes the error.
__call__(*args, **kwargs) → None

Send the request

add_variable(name: str, value: str, type_: Optional[str] = None, value_info: Optional[Mapping[KT, VT_co]] = None) → None

Add a variable to send to the Camunda process instance.

Parameters:
  • name – Name of the variable.
  • value – Value of the variable.
  • type – Value type of the variable.
  • value_info – Additional information regarding the value type.

HandleFailure

class pycamunda.externaltask.HandleFailure(url: str, id_: str, worker_id: str, error_message: str, error_details: str, retries: int, retry_timeout: int)

Report a failure to execute a running external task.

A number of retries and a timeout until the external task can be tried can be specified. If retries are set to 0, the external task cannot be fetched anymore and an incident is created. The message of the incident is set to the value of error_message.

Parameters:
  • url – Camunda Rest engine URL.
  • id – Id of the external task.
  • worker_id – Id of the worker that locked the external task.
  • error_message – Error message that describes the reason of the failure.
  • error_details – Error description.
  • retries – How often the external task can be retried.
  • retry_timeout – Timeout in milliseconds until the external task becomes available

again for fetching.

__call__(*args, **kwargs) → None

Send the request

Unlock

class pycamunda.externaltask.Unlock(url: str, id_: str)

Unlock an external task.

Parameters:
  • url – Camunda Rest engine URL.
  • id – Id of the external task.
__call__(*args, **kwargs) → None

Send the request

ExtendLock

class pycamunda.externaltask.ExtendLock(url: str, id_: str, new_duration: int, worker_id: str)

Unlock an external task.

Parameters:
  • url – Camunda Rest engine URL.
  • id – Id of the external task.
  • new_duration – New duration in milliseconds how long the external task wants to be locked.
  • worker_id – Id of the worker that locked this external task.
__call__(*args, **kwargs) → None

Send the request

SetPriority

class pycamunda.externaltask.SetPriority(url: str, id_: str, priority: int)

Sets the priority of an external task.

Parameters:
  • url – Camunda Rest engine URL.
  • id – Id of the external task.
  • priority – New priority of the external task.
__call__(*args, **kwargs) → None

Send the request

SetRetries

class pycamunda.externaltask.SetRetries(url: str, id_: str, retries: int)

Sets the number of retries of an external task.

Parameters:
  • url – Camunda Rest engine URL.
  • id – Id of the external task.
  • retries – New number of retries of the external task.
__call__(*args, **kwargs) → None

Send the request

SetRetriesAsync

class pycamunda.externaltask.SetRetriesAsync(url: str, retries: int, external_task_ids: Iterable[str])

Sets the number of retries of external tasks asynchronously.

Parameters:
  • url – Camunda Rest engine URL.
  • retries – New number of retries of the external tasks.
  • external_task_ids – Ids of the external tasks.
__call__(*args, **kwargs) → pycamunda.batch.Batch

Send the request

SetRetriesSync

class pycamunda.externaltask.SetRetriesSync(url: str, retries: int, external_task_ids: Iterable[str])

Sets the number of retries of external tasks synchronously.

Parameters:
  • url – Camunda Rest engine URL.
  • retries – New number of retries of the external tasks.
  • external_task_ids – Ids of the external tasks.
__call__(*args, **kwargs) → None

Send the request