{"id":24805355,"url":"https://github.com/viadee/external-task-retry-aspect","last_synced_at":"2026-01-27T12:35:02.228Z","repository":{"id":37963804,"uuid":"337691758","full_name":"viadee/external-task-retry-aspect","owner":"viadee","description":"This tool helps to control the retry-behaviour in external-task-handlers based on the official java-client provided by Camunda BPM","archived":false,"fork":false,"pushed_at":"2024-09-16T11:43:22.000Z","size":278,"stargazers_count":26,"open_issues_count":1,"forks_count":5,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-09-16T13:27:26.670Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/viadee.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":"2021-02-10T10:39:52.000Z","updated_at":"2024-09-12T12:34:42.000Z","dependencies_parsed_at":"2024-08-20T09:11:38.044Z","dependency_job_id":"735cef82-7f1c-411b-9626-8e87e7aaa739","html_url":"https://github.com/viadee/external-task-retry-aspect","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viadee%2Fexternal-task-retry-aspect","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viadee%2Fexternal-task-retry-aspect/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viadee%2Fexternal-task-retry-aspect/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/viadee%2Fexternal-task-retry-aspect/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/viadee","download_url":"https://codeload.github.com/viadee/external-task-retry-aspect/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236309796,"owners_count":19128390,"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":[],"created_at":"2025-01-30T07:18:08.117Z","updated_at":"2026-01-27T12:35:02.221Z","avatar_url":"https://github.com/viadee.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# external-task-retry-aspect\n[![](https://img.shields.io/maven-central/v/de.viadee.bpm.camunda/external-task-retry-aspect-spring-boot-starter)](https://search.maven.org/artifact/de.viadee.bpm.camunda/external-task-retry-aspect-spring-boot-starter)\n![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/viadee/external-task-retry-aspect)\n[![](https://img.shields.io/badge/Camunda%20External%20Task%20Handler-7.24.0-orange.svg)](https://docs.camunda.org/manual/7.24/user-guide/ext-client/spring-boot-starter)\n[![](https://img.shields.io/badge/Operaton%20External%20Task%20Handler-1.0.3-white.svg)](https://docs.operaton.org/docs/documentation/user-guide/process-engine/external-tasks/)\n![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/viadee/external-task-retry-aspect/maven-build.yml)\n[![](https://img.shields.io/github/issues/viadee/external-task-retry-aspect)](https://github.com/viadee/external-task-retry-aspect/issues)\n[![](https://img.shields.io/github/stars/viadee/external-task-retry-aspect)](https://github.com/viadee/external-task-retry-aspect/stargazers)\n\n## ℹ️ Description\nThis tool helps to control the retry-behaviour in external-task-handlers based on the\nofficial [java-client](https://docs.camunda.org/manual/latest/user-guide/ext-client/) provided\nby [Camunda BPM](https://docs.camunda.org/manual/latest/user-guide/ext-client/).\n\n## ⚠️ Important notice\nWith the latest release support for the Camunda 7 Fork [Operaton](https://operaton.org) is added. \nIn this release we try to keep the compatibility to the previous releases as high as possible. \nTherefor the artifact is still located under `de.viadee.bpm.camunda`, we take the liberty to change this in upcoming releases.\nWe also consider splitting this library into two releases one for each engine or dropping support for Camunda 7 in upcoming releases.\n\n## ⭐ Features\n* Retry-behaviour for external-tasks can be configured in process-models as known from `JavaDelegates`\n  like `R3/PT1M`, meaning *three times each after one minute*\n* Every `Exception` leads to a retry  - no manual handling within handlers necessary\n* Special error-type to force instant incidents - skipping any retry-behaviour\n* Additional error-type to create a business-error, which must be handled in process\n* Configurable default retry-behaviour\n\n## 🚀 How to use\n\n### 🆕 New Feature\nStarting with Release `1.12.0` to use this library with [Operaton](https://operaton.org), \nsimply replace the `camunda-external-task-client` dependency with the following, the retry-aspect automatically detects which library to bind to:\n\n```xml\n \u003c!-- works either with the original external-task-client... --\u003e    \n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.operaton.bpm\u003c/groupId\u003e\n    \u003cartifactId\u003eoperaton-external-task-client\u003c/artifactId\u003e\n    \u003cversion\u003e...\u003c/version\u003e\n\u003c/dependency\u003e\n        \n\u003c!-- ...or with new spring-boot-starter-external-task-client --\u003e\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.operaton.bpm.springboot\u003c/groupId\u003e\n    \u003cartifactId\u003eoperaton-bpm-spring-boot-starter-external-task-client\u003c/artifactId\u003e\n    \u003cversion\u003e...\u003c/version\u003e\n\u003c/dependency\u003e\n\n```\n\n\n\n1. Besides the `camunda-external-task-client` dependency, the following maven-coordinate needs to be added to the `pom.xml`. As\na `spring-boot-starter`, the aspect will be loaded automatically as soon as the handler-application starts:\n```xml\n\u003cdependencies\u003e\n  \n    \u003c!-- works either with the original external-task-client... --\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.camunda.bpm\u003c/groupId\u003e\n        \u003cartifactId\u003ecamunda-external-task-client\u003c/artifactId\u003e\n        \u003cversion\u003e...\u003c/version\u003e\n    \u003c/dependency\u003e\n    \n    \u003c!-- ...or with new spring-boot-starter-external-task-client since version 7.15.0 --\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.camunda.bpm.springboot\u003c/groupId\u003e\n        \u003cartifactId\u003ecamunda-bpm-spring-boot-starter-external-task-client\u003c/artifactId\u003e\n        \u003cversion\u003e...\u003c/version\u003e\n    \u003c/dependency\u003e\n\n    \u003c!-- finally: the retry-aspect itself  --\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003ede.viadee.bpm.camunda\u003c/groupId\u003e\n        \u003cartifactId\u003eexternal-task-retry-aspect-spring-boot-starter\u003c/artifactId\u003e\n        \u003cversion\u003e...\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n2. Add extension-property to an external-task:\n![](docs/external-task-extension-properties.png)\n   - The property-name is configurable (see below), default: `RETRY_CONFIG`\n   - Possible values might be, default: `R3/PT5M`\n     - `R1/P1D`: 1 retry after 1 day\n     - `R2/PT2H`: 2 retries after 2 hours each\n     - `R3/PT3M`: 3 retries after 3 minutes each\n     - `PT5M,PT10M,PT20M,PT1H,PT12H,P1D`: 6 increasing retries; 5, 10, 20 minutes, 12 hours, 1 day\n\n\n3. Make sure, the `ExternalTaskHandler` is capable to access extension-properties :\n```java\npublic class HandlerConfig {\n\n    @Autowired // e.g. spring component\n    private ExternalTaskHandler myExternalTaskHandler;\n    \n    public void openHandler() {\n        new ExternalTaskClientBuilderImpl()\n                .baseUrl(\"http://camunda/engine-rest\").build()\n                    .subscribe(\"worker-topic\")\n                    .handler(myExternalTaskHandler)   // injected spring component\n                    .includeExtensionProperties(true) // important, bc. the default: false\n                    .open();\n    }\n}\n```\nAlternatively, if using `spring-boot-starter-external-task-client`, activate extension-properties e.g. in the application.yaml ([more information](https://docs.camunda.org/manual/latest/user-guide/ext-client/spring-boot-starter/)):\n```yaml\ncamunda.bpm.client:\n  subscriptions: \n    worker-topic:\n      include-extension-properties: true\n```\n### Configuration options\nThese properties are available, they can be set e.g. in `application.properties`:\n\n```properties\n# Default retry-behaviour, if no retry is configured. \n# Whenever this property is configured incorrectly, 'R3/PT5M' is also used as fallback\nde.viadee.bpm.camunda.external-task.retry-config.default-behavior=R3/PT5M\n\n# Identifier used in bpmn-extension-properties, default=RETRY_CONFIG\nde.viadee.bpm.camunda.external-task.retry-config.identifier=RETRY_CONFIG\n```\n\n#### 🆕 New Feature\nStarting with Version `1.12.0` for Operaton based engines, the configuration properties can also be the following, support for the camunda based properties is still available:\n```properties\n# Default retry-behaviour, if no retry is configured. \n# Whenever this property is configured incorrectly, 'R3/PT5M' is also used as fallback\nde.viadee.bpm.operaton.external-task.retry-config.default-behavior=R3/PT5M\n\n# Identifier used in bpmn-extension-properties, default=RETRY_CONFIG\nde.viadee.bpm.operaton.external-task.retry-config.identifier=RETRY_CONFIG\n```\n\n## 🧙 How this might help?\nA comparison of some `ConventionalHandler` with an `AspectedHandler` explains how the error-handling \ncan be completely left out, because anything is done by the `retry-aspect`:\n\n### `ConventionalHandler` without Retry-Aspect\n```java\n@Component\npublic class ConventionalHandler implements ExternalTaskHandler {\n\n    public void execute(ExternalTask task, ExternalTaskService service) {\n        try {\n            // do some business-logic and complete if fine...\n            service.complete(task);\n\n            // ...or maybe end with some bpmn-error, that has to be handled within process\n            service.handleBpmnError(task, \"bpmn-error-code\");\n\n        } catch (Exception error) {\n            // catch errors and think about retries and timeout\n            service.handleFailure(task,\n                    \"error-message\",        // shown in Camunda Cockpit\n                    \"error-details\",        // e.g. stacktrace, available in Camunda Cockpit\n                    task.getRetries() - 1,  // how many retries are left? (initial null)\n                    300000L);               // time to next retry in ms\n        }\n    }\n}\n\n```\n\n### `AspectedHandler` using Retry-Aspect\n\n* No `try-catch` needed, this is done automatically, i.e. all errors thrown in an `ExternalTaskHandler` `execute()`-method will be caught automatically and handled as follows:\n    * `ExternalTaskBusinessError` can be used to trigger `handleBpmnError()`\n    * `InstantIncidentException` can be used to skip retries and create an incident instantly\n    * Any other exception leads to the specified retry-behaviour\n\n```java\n@Component\n@ExternalTaskSubscription(\"my-topic\")\npublic class AspectedHandler implements ExternalTaskHandler {\n\n    public void execute(ExternalTask task, ExternalTaskService service) {\n        // do some business-logic and complete if fine...\n        service.complete(task);\n\n        // ...or maybe end with some bpmn-error, that has to be handled within process\n        throw ExternalTaskBusinessError(\"bpmn-error-code\");\n    }\n}\n```\n\n## :computer: Versions\nThe following versions are used. Older versions are probably not maintained, but in most cases, it should be possible to \nuse a newer version of the Retry-Aspect in combination with an older version of the External-Task-Client. If you encounter\nany issue, please feel free to contact me.\n\n| Retry-Aspect | Camunda External-Task-Client | Operaton External-Task-Client |                     Spring Boot |  \n|-------------:|-----------------------------:|------------------------------:|--------------------------------:|\n|        1.2.x |                       7.15.0 |                   Unsupported |                           2.5.x |\n|        1.3.x |                       7.16.0 |                   Unsupported |                           2.6.x |\n|        1.4.x |                       7.17.0 |                   Unsupported |                           2.6.x |\n|        1.4.2 |                       7.17.0 |                   Unsupported |                           2.7.x |\n|        1.5.x |                       7.18.0 |                   Unsupported |                           2.7.x |\n|        1.6.x |                       7.19.0 |                   Unsupported |                           2.7.x |\n|        1.7.x |                       7.19.0 |                   Unsupported |                           2.7.x |\n|        1.8.x |                       7.20.0 |                   Unsupported |                           3.1.x |\n|        1.9.0 |                       7.21.0 |                   Unsupported |                           3.3.x |\n|       1.9.1+ |                       7.22.0 |                   Unsupported |                           3.3.x |\n|       1.10.0 |                       7.23.0 |                   Unsupported |                           3.4.x |\n|      1.11.0+ |                       7.24.0 |                   Unsupported |                           3.5.x |\n|      1.12.0+ |                       7.24.0 |                         1.0.3 |                           3.5.x |\n\n\n## 🤹 Collaboration\nThis tool was build by viadee Unternehmensberatung AG. If you are interested to find out what \nelse we are doing, check out our website [viadee.de](https://www.viadee.de/en). \nIf you have any feedback, ideas or extensions feel free to contact or create a GitHub issue.\n\n## 🏆 Thanks\n\n* Many thanks to [@ChrisSchoe][u_chrisschoe] for making the external-task-retry-aspect spring-boot-3-ready ([#107][i_107])\n* Many thanks to [@jschneider97][u_jschneider97] for making the external-task-retry-aspect ready for Operaton and Springboot 4 ([#147][i_147])\n\n## 🔑 License\n\n[![](https://img.shields.io/github/license/viadee/external-task-retry-aspect)](https://github.com/viadee/external-task-retry-aspect/blob/master/LICENSE)\n\n---  \n[i_107]: https://github.com/viadee/external-task-retry-aspect/issues/107\n[i_147]: https://github.com/viadee/external-task-retry-aspect/issues/147\n[u_ChrisSchoe]: https://github.com/ChrisSchoe\n[u_jschneider97]: https://github.com/jschneider97\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviadee%2Fexternal-task-retry-aspect","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fviadee%2Fexternal-task-retry-aspect","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fviadee%2Fexternal-task-retry-aspect/lists"}