Repository files navigation

License:

AnExternal Worker Task in BPMN or CMMN is a task where the custom logic of that task is executed externally to Flowable, i.e. on another server.When the process or case engine arrives at such a task, it will create anexternal job, which is exposed over the REST API.Through this REST API, the job can be acquired and locked. Once locked, the custom logic is responsible for signalling over REST that the work is done and the process or case can continue.

This project makes implementing such custom logic in Java easy by not having the worry about the low-level details of the REST API and focus on the actual custom business logic. Integrations for other languages are available, too.

The following dependency needs to be added to start using Flowable workers.

<dependency>    <groupId>org.flowable.client.spring</groupId>    <artifactId>flowable-external-worker-spring-boot-starter</artifactId>    <version>${flowable-worker-client.version}</version></dependency>

The following is an example Flowable Worker that is retrieving jobs from themyTopic topic

importorg.springframework.stereotype.Component;importorg.flowable.external.client.AcquiredExternalWorkerJob;importorg.flowable.external.worker.annotation.FlowableWorker;@ComponentpublicclassExampleWorker {@FlowableWorker(topic ="myTopic")publicvoidprocessJob(AcquiredExternalWorkerJobjob) {System.out.println("Executed job: " +job.getId());    }}

Using the example above the job will be completed if the method completes successfully, and it will fail if the method throws an exception.

In order to pass additional data for a failure or a completion the following example can be used:

importorg.springframework.stereotype.Component;importorg.flowable.external.client.AcquiredExternalWorkerJob;importorg.flowable.external.worker.annotation.FlowableWorker;importorg.flowable.external.worker.WorkerResult;importorg.flowable.external.worker.WorkerResultBuilder;@ComponentpublicclassExampleWorker {@FlowableWorker(topic ="myTopic")publicWorkerResultprocessJob(AcquiredExternalWorkerJobjob,WorkerResultBuilderresultBuilder) {System.out.println("Executed job: " +job.getId());ObjecterrorMessage =job.getVariables().get("errorMessage");if (errorMessage !=null) {returnresultBuilder.failure()                    .message(errorMessage.toString())                    .details("Error message details");        }returnresultBuilder.success()                .variable("message","Job has been executed");    }}

The following properties show how you can connect to a Flowable instance running athttp://host.docker.internal:8090 using basic authentication:

flowable.external.worker.rest.base-url=http://host.docker.internal:8090flowable.external.worker.rest.authentication.basic.username=adminflowable.external.worker.rest.authentication.basic.password=test

The context path can also be changed, if necessary:

flowable.external.worker.rest.context-path=/external-job-api

There are two ways that the application can be authenticated with a Flowable installation:

• Using HTTP Basic authentication with a provided username and password, as shown in the example above.
• Using HTTP Bearer authentication with a provided access token. In that case the.basic properties are replaced by theflowable.external.worker.rest.authentication.bearer.token=myTokenValue property.

Connecting an external worker to the Flowable Trial is simpler, since everything is pre-configured.It's required to either use the user credentials or to pre-configure a personal access token, for example:

flowable.external.worker.rest.authentication.bearer.token=<personal-access-token>

The following properties are for advanced usage. Only change these if you understand the consequences and the concept of the external worker properly.

• flowable.external.worker.workerId : gives the external worker a custom identifier, which is used to identify which external worker has locked an external worker job.
• flowable.external.worker.concurrency : The amount of threads available to poll and execute external worker jobs. By default1.
• flowable.external.worker.lock-duration : The amount of time an external job will be locked when acquired. If this time limit is reached, other external workers will be able to acquire the same job. By default 5 minutes.
• flowable.external.worker.number-of-retries : The number of times to retry acquiring new jobs on the Flowable server-side before giving up. By default, 5.
• flowable.external.worker.number-of-tasks : The amount of external worker tasks to acquire and lock in one go. The default is1.
• flowable.external.worker.polling-interval : The amount of time between polling for new external worker jobs. By default, 30 seconds.

The following dependency needs to be added to start in a plain Java project without Spring Boot:

<dependency>    <groupId>org.flowable.client</groupId>    <artifactId>flowable-external-worker-client-java</artifactId>    <version>${flowable-worker-client.version}</version></dependency>

The following is an example Flowable Worker that is retrieving jobs from themyTopic topic

ExternalWorkerClientexternalWorkerClient =RestExternalWorkerClient.create("my-worker",JavaHttpClientRestInvoker.withBasicAuth("http://localhost:8090/external-job-api","admin","test"),newObjectMapper());List<AcquiredExternalWorkerJob>jobs =externalWorkerClient.createJobAcquireBuilder()        .topic("myTopic")        .lockDuration(Duration.ofMinutes(1L))        .acquireAndLock();for (AcquiredExternalWorkerJobjob :jobs) {System.out.println("Executed job: " +job.getId());externalWorkerClient.createCompletionBuilder(job)            .complete();}

There are two ways that the application can be authenticated with a Flowable installation:

• Using HTTP Basic authentication with a provided username and password, as shown in the example above.
• Using HTTP Bearer authentication with a provided access token. In this case theRestInvoker can be created like this:JavaHttpClientRestInvoker.withAccessToken("http://localhost:8090/external-job-api", "<your-access-token>")