{"id":21393357,"url":"https://github.com/camunda-community-hub/camunda-external-task-client-python3","last_synced_at":"2025-04-05T05:06:21.743Z","repository":{"id":40890512,"uuid":"264141998","full_name":"camunda-community-hub/camunda-external-task-client-python3","owner":"camunda-community-hub","description":"Camunda 7 External Task Client in Python","archived":false,"fork":false,"pushed_at":"2025-01-24T14:15:30.000Z","size":182,"stargazers_count":76,"open_issues_count":18,"forks_count":56,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-29T04:07:54.058Z","etag":null,"topics":["camunda","camunda-7","camunda-bpm","camunda-bpm-runtime","camunda-client","camunda-engine","camunda-external-task","camunda-python-client","hacktoberfest","hacktoberfest-accepted","hacktoberfest2020","python3","python37"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/camunda-community-hub.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-05-15T08:40:45.000Z","updated_at":"2025-03-10T11:03:05.000Z","dependencies_parsed_at":"2023-12-03T09:41:01.799Z","dependency_job_id":"3e75e7b0-56e3-4c27-9730-b3acb26fa9eb","html_url":"https://github.com/camunda-community-hub/camunda-external-task-client-python3","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda-community-hub%2Fcamunda-external-task-client-python3","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda-community-hub%2Fcamunda-external-task-client-python3/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda-community-hub%2Fcamunda-external-task-client-python3/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/camunda-community-hub%2Fcamunda-external-task-client-python3/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/camunda-community-hub","download_url":"https://codeload.github.com/camunda-community-hub/camunda-external-task-client-python3/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289427,"owners_count":20914464,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["camunda","camunda-7","camunda-bpm","camunda-bpm-runtime","camunda-client","camunda-engine","camunda-external-task","camunda-python-client","hacktoberfest","hacktoberfest-accepted","hacktoberfest2020","python3","python37"],"created_at":"2024-11-22T14:11:26.236Z","updated_at":"2025-04-05T05:06:21.713Z","avatar_url":"https://github.com/camunda-community-hub.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Community Extension](https://img.shields.io/badge/Community%20Extension-An%20open%20source%20community%20maintained%20project-FF4700)](https://github.com/camunda-community-hub/community)[![Lifecycle: Stable](https://img.shields.io/badge/Lifecycle-Stable-brightgreen)](https://github.com/Camunda-Community-Hub/community/blob/main/extension-lifecycle.md#stable-)\n\n# camunda-external-task-client-python3\n![camunda-external-task-client-python3](https://github.com/trustfactors/camunda-external-task-client-python3/workflows/camunda-external-task-client-python3/badge.svg)\n\nThis repository contains Camunda External Task Client written in Python3.\n\n\nImplement your [BPMN Service Task](https://docs.camunda.org/manual/latest/user-guide/process-engine/external-tasks/) in Python3.\n\n\u003e Python \u003e= 3.7 is required\n\n## Installing\nAdd following line to `requirements.txt` of your Python project.\n```\ngit+https://github.com/trustfactors/camunda-external-task-client-python3.git/#egg=camunda-external-task-client-python3\n```\n\nOr use pip to install as shown below:\n```\npip install camunda-external-task-client-python3\n```\n\n## Running Camunda with Docker\nTo run the examples provided in [examples](./examples) folder, you need to have Camunda running locally or somewhere.\n\nTo run Camunda locally with Postgres DB as backend, you can use [docker-compose.yml](./docker-compose.yml) file.\n\n```\n$\u003e docker-compose -f docker-compose.yml up\n```\n### Auth Basic Examples\n\nTo run the examples with Auth Basic provided in [examples/examples_auth_basic](./examples/examples_auth_basic) folder, you need to have Camunda with AuthBasic, running locally or somewhere.\n\nTo run Camunda with AuthBasic locally with Postgres DB as backend, you can use [docker-compose-auth.yml](./docker-compose-auth.yml) file.\n\n```\n$\u003e docker-compose -f docker-compose-auth.yml up\n```\n\n## Usage\n\n1.  Make sure to have [Camunda](https://camunda.com/download/) running.\n2.  Create a simple process model with an External Service Task and define the topic as 'topicName'.\n3.  Deploy the process to the Camunda BPM engine.\n4.  In your Python code:\n\n```python\nimport time\nfrom camunda.external_task.external_task import ExternalTask, TaskResult\nfrom camunda.external_task.external_task_worker import ExternalTaskWorker\n\n# configuration for the Client\ndefault_config = {\n    \"maxTasks\": 1,\n    \"lockDuration\": 10000,\n    \"asyncResponseTimeout\": 5000,\n    \"retries\": 3,\n    \"retryTimeout\": 5000,\n    \"sleepSeconds\": 30\n}\n\ndef handle_task(task: ExternalTask) -\u003e TaskResult:\n    \"\"\"\n    This task handler you need to implement with your business logic.\n    After completion of business logic call either task.complete() or task.failure() or task.bpmn_error() \n    to report status of task to Camunda\n    \"\"\"\n    # add your business logic here\n    # ...\n    \n    # mark task either complete/failure/bpmnError based on outcome of your business logic\n    failure, bpmn_error = random_true(), random_true() # this code simulate random failure\n    if failure:\n        # this marks task as failed in Camunda\n        return task.failure(error_message=\"task failed\",  error_details=\"failed task details\", \n                            max_retries=3, retry_timeout=5000)\n    elif bpmn_error:\n        return task.bpmn_error(error_code=\"BPMN_ERROR_CODE\", error_message=\"BPMN Error occurred\", \n                                variables={\"var1\": \"value1\", \"success\": False})\n    \n    # pass any output variables you may want to send to Camunda as dictionary to complete()\n    return task.complete({\"var1\": 1, \"var2\": \"value\"}) \n\ndef random_true():\n    current_milli_time = int(round(time.time() * 1000))\n    return current_milli_time % 2 == 0\n\nif __name__ == '__main__':\n   ExternalTaskWorker(worker_id=\"1\", config=default_config).subscribe(\"topicName\", handle_task)\n```\n\n## About External Tasks\n\nExternal Tasks are service tasks whose execution differs particularly from the execution of other service tasks (e.g. Human Tasks).\nThe execution works in a way that units of work are polled from the engine before being completed.\n\n**camunda-external-task-client-python** allows you to create easily such client in Python3.\n\n## Features\n\n### [Start process](https://docs.camunda.org/manual/latest/reference/rest/process-definition/post-start-process-instance/)\nCamunda provides functionality to start a process instance for a given process definition.\n\nTo start a process instance, we can use `start_process()` from [engine_client.py](./camunda/client/engine_client.py#L24)\n\nYou can find a usage example [here](./examples/start_process.py).\n\n```python\nclient = EngineClient()\nresp_json = client.start_process(process_key=\"PARALLEL_STEPS_EXAMPLE\", variables={\"intVar\": \"1\", \"strVar\": \"hello\"},\n                                 tenant_id=\"6172cdf0-7b32-4460-9da0-ded5107aa977\", business_key=str(uuid.uuid1()))\n```\n\n### [Fetch and Lock](https://docs.camunda.org/manual/latest/reference/rest/external-task/fetch/)\n\n`ExternalTaskWorker(worker_id=\"1\").subscribe(\"topicName\", handle_task)` starts long polling of the Camunda engine for external tasks.\n\n* Polling tasks from the engine works by performing a fetch \u0026 lock operation of tasks that have subscriptions. It then calls the handler function passed to `subscribe()` function. i.e. `handle_task` in above example.\n* Long Polling is done periodically based on the `asyncResponseTimeout` configuration. Read more about [Long Polling](https://docs.camunda.org/manual/latest/user-guide/process-engine/external-tasks/#long-polling-to-fetch-and-lock-external-tasks).\n\n### [Complete](https://docs.camunda.org/manual/latest/reference/rest/external-task/post-complete/)\n```python\nfrom camunda.external_task.external_task import ExternalTask, TaskResult\nfrom camunda.external_task.external_task_worker import ExternalTaskWorker\ndef handle_task(task: ExternalTask) -\u003e TaskResult:\n    # add your business logic here\n    \n    # Complete the task\n    # pass any output variables you may want to send to Camunda as dictionary to complete()\n    return task.complete({\"var1\": 1, \"var2\": \"value\"})\n\nExternalTaskWorker(worker_id=\"1\").subscribe(\"topicName\", handle_task)\n```\n\n### [Handle Failure](https://docs.camunda.org/manual/latest/reference/rest/external-task/post-failure/)\n```python\nfrom camunda.external_task.external_task import ExternalTask, TaskResult\nfrom camunda.external_task.external_task_worker import ExternalTaskWorker\ndef handle_task(task: ExternalTask) -\u003e TaskResult:\n    # add your business logic here\n    \n    # Handle task Failure\n    return task.failure(error_message=\"task failed\",  error_details=\"failed task details\", \n                        max_retries=3, retry_timeout=5000)\n    # This client/worker uses max_retries if no retries are previously set in the task\n    # if retries are previously set then it just decrements that count by one before reporting failure to Camunda\n    # when retries are zero, Camunda creates an incident which then manually needs to be looked into on Camunda Cockpit            \n\nExternalTaskWorker(worker_id=\"1\").subscribe(\"topicName\", handle_task)\n```\n\n### [Handle BPMN Error](https://docs.camunda.org/manual/latest/reference/rest/external-task/post-bpmn-error/)\n```python\nfrom camunda.external_task.external_task import ExternalTask, TaskResult\nfrom camunda.external_task.external_task_worker import ExternalTaskWorker\ndef handle_task(task: ExternalTask) -\u003e TaskResult:\n    # add your business logic here\n    \n    # Handle a BPMN Failure\n    return task.bpmn_error(error_code=\"BPMN_ERROR\", error_message=\"BPMN error occurred\")\n\nExternalTaskWorker(worker_id=\"1\" ).subscribe(\"topicName\", handle_task)\n```\n\n### Access Process Variables\n```python\nfrom camunda.external_task.external_task import ExternalTask, TaskResult\nfrom camunda.external_task.external_task_worker import ExternalTaskWorker\ndef handle_task(task: ExternalTask) -\u003e TaskResult:\n    # add your business logic here\n    # get the process variable 'score'\n    score = task.get_variable(\"score\")\n    if int(score) \u003e= 100:\n        return task.complete(...)\n    else:\n        return task.failure(...)        \n\nExternalTaskWorker().subscribe(\"topicName\", handle_task)\n```\n\n### [Correlate message](https://docs.camunda.org/manual/7.13/reference/bpmn20/events/message-events/)\nCamunda provides functionality to send a message event to a running process instance.\n\nYou can read more about the message events here: https://docs.camunda.org/manual/7.13/reference/bpmn20/events/message-events/\n\nIn our to send a message event to a process instance, a new function called `correlate_message()` is added to [engine_client.py](./camunda/client/engine_client.py#L60)\n\nWe can correlate the message by:\n- process_instance_id\n- tenant_id\n- business_key\n- process_variables\n\nYou can find a usage example [here](./examples/correlate_message.py).\n\n```python\nclient = EngineClient()\nresp_json = client.correlate_message(\"CANCEL_MESSAGE\", business_key=\"b4a6f392-12ab-11eb-80ef-acde48001122\")\n```\n## AuthBasic Usage\n\nTo create an EngineClient with AuthBasic simple\n\n```python\nclient = EngineClient(config={\"auth_basic\": {\"username\": \"demo\", \"password\": \"demo\"}})\nresp_json = client.start_process(process_key=\"PARALLEL_STEPS_EXAMPLE\", variables={\"intVar\": \"1\", \"strVar\": \"hello\"},\n                                 tenant_id=\"6172cdf0-7b32-4460-9da0-ded5107aa977\", business_key=str(uuid.uuid1()))\n```\n\nTo create an ExternalTaskWorker with AuthBasic simple\n\n```python\nfrom camunda.external_task.external_task import ExternalTask, TaskResult\nfrom camunda.external_task.external_task_worker import ExternalTaskWorker\n\nconfig = {\"auth_basic\": {\"username\": \"demo\", \"password\": \"demo\"}}\n\ndef handle_task(task: ExternalTask) -\u003e TaskResult:\n    # add your business logic here\n    \n    # Complete the task\n    # pass any output variables you may want to send to Camunda as dictionary to complete()\n    return task.complete({\"var1\": 1, \"var2\": \"value\"})\n\nExternalTaskWorker(worker_id=\"1\", config=config).subscribe(\"topicName\", handle_task)\n```\n\n## License\nThe source files in this repository are made available under the [Apache License Version 2.0](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcamunda-community-hub%2Fcamunda-external-task-client-python3","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcamunda-community-hub%2Fcamunda-external-task-client-python3","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcamunda-community-hub%2Fcamunda-external-task-client-python3/lists"}