In this tutorial you will learn how to use the External Task client for Java.
In a nutshell you will be guided through the following steps:
- Starting the Camunda Platform Runtime
- Modeling and Deploying a process with the Camunda Modeler
- Bootstrapping the External Task client
- Monitor the process in Camunda Cockpit
- Java JDK 11+
- Apache Maven
- Camunda Modeler
- Camunda Platform Runtime
- Camunda External Task Client
First, make sure you have downloaded and installed all the necessary prerequisites, and the running platform is compatible with the client version.
- Microsoft Windows users need to run the
start.bat
file - Users of Unix based operating systems need to run the
start.sh
file
Next, we want to deploy a model to the Camunda Platform Runtime with the following steps:
- Download the BPMN 2.0 XML of that model here.
- Open the model in the Camunda Modeler.
- Click on the "Deploy" icon
.
- Select "Deploy Current Diagram".
- Select a deployment name of your choice.
To complete the deployment, click on the "Deploy" button. Your model is now ready to be executed by the Camunda Platform Process Engine. Start an instance of it in Camunda Tasklist.
Open Camunda Cockpit click in the top navigation on "Processes" and then on the process "Order Process". You should see the process with the activity instances.
In this step we will set up the External Task client.
You can create a new Maven project using your IDE, or run the following command:
mvn archetype:generate \
-DgroupId=org.camunda.bpm \
-DartifactId=order-handling \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DinteractiveMode=false
Add the camunda-external-task-client
dependency to the project's pom.xml
:
<dependency>
<groupId>org.camunda.bpm</groupId>
<artifactId>camunda-external-task-client</artifactId>
<version>${version}</version>
</dependency>
Create a main class and add the following lines:
// bootstrap the client
ExternalTaskClient client = ExternalTaskClient.create()
.baseUrl("http://localhost:8080/engine-rest")
.asyncResponseTimeout(1000)
.customizeHttpClient(httpClientBuilder -> {
httpClientBuilder.setDefaultRequestConfig(RequestConfig.custom()
.setResponseTimeout(Timeout.ofSeconds(15))
.build());
})
.build();
// subscribe to the topic
client.subscribe("invoiceCreator")
.handler((externalTask, externalTaskService) -> {
// instantiate an invoice object
Invoice invoice = new Invoice("A123");
// create an object typed variable with the serialization format XML
ObjectValue invoiceValue = ClientValues
.objectValue(invoice)
.serializationDataFormat("application/xml")
.create();
// add the invoice object and its id to a map
Map<String, Object> variables = new HashMap<>();
variables.put("invoiceId", invoice.id);
variables.put("invoice", invoiceValue);
// select the scope of the variables
boolean isRandomSample = Math.random() <= 0.5;
if (isRandomSample) {
externalTaskService.complete(externalTask, variables);
} else {
externalTaskService.complete(externalTask, null, variables);
}
System.out.println("The External Task " + externalTask.getId() +
" has been completed!");
}).open();
client.subscribe("invoiceArchiver")
.handler((externalTask, externalTaskService) -> {
TypedValue typedInvoice = externalTask.getVariableTyped("invoice");
Invoice invoice = (Invoice) typedInvoice.getValue();
System.out.println("Invoice on process scope archived: " + invoice);
externalTaskService.complete(externalTask);
}).open();
Create an Invoice
class and add the following lines:
public class Invoice {
public String id;
public Invoice(String id) {
this.id = id;
}
public Invoice() {
}
@Override
public String toString() {
return "Invoice [id=" + id + "]";
}
}
Now, just run your application. The client starts to continuously fetch and lock for External Task instances.
You should see a similar result in your console window:
The External Task 5baf2670-1bad-11ec-9048-04d3b0c25ec0 has been completed!
Invoice on process scope archived: Invoice [id=A123]
...