https://github.com/viadee/external-task-retry-aspect
This tool helps to control the retry-behaviour in external-task-handlers based on the official java-client provided by Camunda BPM
https://github.com/viadee/external-task-retry-aspect
Last synced: 5 months ago
JSON representation
This tool helps to control the retry-behaviour in external-task-handlers based on the official java-client provided by Camunda BPM
- Host: GitHub
- URL: https://github.com/viadee/external-task-retry-aspect
- Owner: viadee
- License: bsd-3-clause
- Created: 2021-02-10T10:39:52.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-09-16T11:43:22.000Z (almost 2 years ago)
- Last Synced: 2024-09-16T13:27:26.670Z (almost 2 years ago)
- Language: Java
- Homepage:
- Size: 271 KB
- Stars: 26
- Watchers: 9
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# external-task-retry-aspect
[](https://search.maven.org/artifact/de.viadee.bpm.camunda/external-task-retry-aspect-spring-boot-starter)
[](https://docs.camunda.org/manual/7.24/user-guide/ext-client/spring-boot-starter)
[](https://docs.operaton.org/docs/documentation/user-guide/process-engine/external-tasks/)
[](https://github.com/viadee/external-task-retry-aspect/issues)
[](https://github.com/viadee/external-task-retry-aspect/stargazers)
## ℹ️ Description
This tool helps to control the retry-behaviour in external-task-handlers based on the
official [java-client](https://docs.camunda.org/manual/latest/user-guide/ext-client/) provided
by [Camunda BPM](https://docs.camunda.org/manual/latest/user-guide/ext-client/).
## ⚠️ Important notice
With the latest release support for the Camunda 7 Fork [Operaton](https://operaton.org) is added.
In this release we try to keep the compatibility to the previous releases as high as possible.
Therefor the artifact is still located under `de.viadee.bpm.camunda`, we take the liberty to change this in upcoming releases.
We also consider splitting this library into two releases one for each engine or dropping support for Camunda 7 in upcoming releases.
## ⭐ Features
* Retry-behaviour for external-tasks can be configured in process-models as known from `JavaDelegates`
like `R3/PT1M`, meaning *three times each after one minute*
* Every `Exception` leads to a retry - no manual handling within handlers necessary
* Special error-type to force instant incidents - skipping any retry-behaviour
* Additional error-type to create a business-error, which must be handled in process
* Configurable default retry-behaviour
## 🚀 How to use
### 🆕 New Feature
Starting with Release `1.12.0` to use this library with [Operaton](https://operaton.org),
simply replace the `camunda-external-task-client` dependency with the following, the retry-aspect automatically detects which library to bind to:
```xml
org.operaton.bpm
operaton-external-task-client
...
org.operaton.bpm.springboot
operaton-bpm-spring-boot-starter-external-task-client
...
```
1. Besides the `camunda-external-task-client` dependency, the following maven-coordinate needs to be added to the `pom.xml`. As
a `spring-boot-starter`, the aspect will be loaded automatically as soon as the handler-application starts:
```xml
org.camunda.bpm
camunda-external-task-client
...
org.camunda.bpm.springboot
camunda-bpm-spring-boot-starter-external-task-client
...
de.viadee.bpm.camunda
external-task-retry-aspect-spring-boot-starter
...
```
2. Add extension-property to an external-task:
- The property-name is configurable (see below), default: `RETRY_CONFIG`
- Possible values might be, default: `R3/PT5M`
- `R1/P1D`: 1 retry after 1 day
- `R2/PT2H`: 2 retries after 2 hours each
- `R3/PT3M`: 3 retries after 3 minutes each
- `PT5M,PT10M,PT20M,PT1H,PT12H,P1D`: 6 increasing retries; 5, 10, 20 minutes, 12 hours, 1 day
3. Make sure, the `ExternalTaskHandler` is capable to access extension-properties :
```java
public class HandlerConfig {
@Autowired // e.g. spring component
private ExternalTaskHandler myExternalTaskHandler;
public void openHandler() {
new ExternalTaskClientBuilderImpl()
.baseUrl("http://camunda/engine-rest").build()
.subscribe("worker-topic")
.handler(myExternalTaskHandler) // injected spring component
.includeExtensionProperties(true) // important, bc. the default: false
.open();
}
}
```
Alternatively, 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/)):
```yaml
camunda.bpm.client:
subscriptions:
worker-topic:
include-extension-properties: true
```
### Configuration options
These properties are available, they can be set e.g. in `application.properties`:
```properties
# Default retry-behaviour, if no retry is configured.
# Whenever this property is configured incorrectly, 'R3/PT5M' is also used as fallback
de.viadee.bpm.camunda.external-task.retry-config.default-behavior=R3/PT5M
# Identifier used in bpmn-extension-properties, default=RETRY_CONFIG
de.viadee.bpm.camunda.external-task.retry-config.identifier=RETRY_CONFIG
```
#### 🆕 New Feature
Starting 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:
```properties
# Default retry-behaviour, if no retry is configured.
# Whenever this property is configured incorrectly, 'R3/PT5M' is also used as fallback
de.viadee.bpm.operaton.external-task.retry-config.default-behavior=R3/PT5M
# Identifier used in bpmn-extension-properties, default=RETRY_CONFIG
de.viadee.bpm.operaton.external-task.retry-config.identifier=RETRY_CONFIG
```
## 🧙 How this might help?
A comparison of some `ConventionalHandler` with an `AspectedHandler` explains how the error-handling
can be completely left out, because anything is done by the `retry-aspect`:
### `ConventionalHandler` without Retry-Aspect
```java
@Component
public class ConventionalHandler implements ExternalTaskHandler {
public void execute(ExternalTask task, ExternalTaskService service) {
try {
// do some business-logic and complete if fine...
service.complete(task);
// ...or maybe end with some bpmn-error, that has to be handled within process
service.handleBpmnError(task, "bpmn-error-code");
} catch (Exception error) {
// catch errors and think about retries and timeout
service.handleFailure(task,
"error-message", // shown in Camunda Cockpit
"error-details", // e.g. stacktrace, available in Camunda Cockpit
task.getRetries() - 1, // how many retries are left? (initial null)
300000L); // time to next retry in ms
}
}
}
```
### `AspectedHandler` using Retry-Aspect
* 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:
* `ExternalTaskBusinessError` can be used to trigger `handleBpmnError()`
* `InstantIncidentException` can be used to skip retries and create an incident instantly
* Any other exception leads to the specified retry-behaviour
```java
@Component
@ExternalTaskSubscription("my-topic")
public class AspectedHandler implements ExternalTaskHandler {
public void execute(ExternalTask task, ExternalTaskService service) {
// do some business-logic and complete if fine...
service.complete(task);
// ...or maybe end with some bpmn-error, that has to be handled within process
throw ExternalTaskBusinessError("bpmn-error-code");
}
}
```
## :computer: Versions
The following versions are used. Older versions are probably not maintained, but in most cases, it should be possible to
use a newer version of the Retry-Aspect in combination with an older version of the External-Task-Client. If you encounter
any issue, please feel free to contact me.
| Retry-Aspect | Camunda External-Task-Client | Operaton External-Task-Client | Spring Boot |
|-------------:|-----------------------------:|------------------------------:|--------------------------------:|
| 1.2.x | 7.15.0 | Unsupported | 2.5.x |
| 1.3.x | 7.16.0 | Unsupported | 2.6.x |
| 1.4.x | 7.17.0 | Unsupported | 2.6.x |
| 1.4.2 | 7.17.0 | Unsupported | 2.7.x |
| 1.5.x | 7.18.0 | Unsupported | 2.7.x |
| 1.6.x | 7.19.0 | Unsupported | 2.7.x |
| 1.7.x | 7.19.0 | Unsupported | 2.7.x |
| 1.8.x | 7.20.0 | Unsupported | 3.1.x |
| 1.9.0 | 7.21.0 | Unsupported | 3.3.x |
| 1.9.1+ | 7.22.0 | Unsupported | 3.3.x |
| 1.10.0 | 7.23.0 | Unsupported | 3.4.x |
| 1.11.0+ | 7.24.0 | Unsupported | 3.5.x |
| 1.12.0+ | 7.24.0 | 1.0.3 | 3.5.x |
## 🤹 Collaboration
This tool was build by viadee Unternehmensberatung AG. If you are interested to find out what
else we are doing, check out our website [viadee.de](https://www.viadee.de/en).
If you have any feedback, ideas or extensions feel free to contact or create a GitHub issue.
## 🏆 Thanks
* Many thanks to [@ChrisSchoe][u_chrisschoe] for making the external-task-retry-aspect spring-boot-3-ready ([#107][i_107])
* Many thanks to [@jschneider97][u_jschneider97] for making the external-task-retry-aspect ready for Operaton and Springboot 4 ([#147][i_147])
## 🔑 License
[](https://github.com/viadee/external-task-retry-aspect/blob/master/LICENSE)
---
[i_107]: https://github.com/viadee/external-task-retry-aspect/issues/107
[i_147]: https://github.com/viadee/external-task-retry-aspect/issues/147
[u_ChrisSchoe]: https://github.com/ChrisSchoe
[u_jschneider97]: https://github.com/jschneider97