Camunda TaskList Client

This project was intially designed to simplify communication between a java backend and the Camunda 8 task list GraphQL APIs. Since GraphQL APIs are now deprecared, this client is now targetting REST endpoints. Contributions through PR are welcome!

ℹ️ 8.3+ Relesases of this client are generated against Rest endpoints.

ℹ️ 8.3.3.3 changes the way to build authentication and client. Please check the following documentation

How to build the client

Spring Boot

Add the dependency to your project:

<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>spring-boot-starter-camunda-tasklist</artifactId>
  <version>${version.tasklist-client}</version>
</dependency>

Configure a Camunda Tasklist client with simple authentication:

tasklist:
  client:
    profile: simple

To adjust the (meaningful) default properties, you can also override them:

tasklist:
  client:
    profile: simple
    enabled: true
    base-url: http://localhost:8082
    session-timeout: PT10M
    username: demo
    password: demo

Configure a Camunda Tasklist client with identity authentication:

tasklist:
  client:
    profile: oidc
    client-id:
    client-secret:
    scope: # optional

To adjust the (meaningful) default properties, you can also override them:

tasklist:
  client:
    profile: oidc
    enabled: true
    base-url: http://localhost:8082
    auth-url: http://localhost:18080/auth/realms/camunda-platform/protocol/openid-connect/token
    audience: operate-api
    client-id:
    client-secret:
    scope: # optional

Configure a Camunda Tasklist client for Saas:

tasklist:
  client:
    profile: saas
    region:
    cluster-id:
    client-id:
    client-secret:

tasklist:
  client:
    profile: saas
    enabled: true
    base-url: https://${tasklist.client.region}.tasklist.camunda.io/${tasklist.client.cluster-id}
    auth-url: https://login.cloud.camunda.io/oauth/token
    audience: tasklist.camunda.io
    region:
    cluster-id:
    client-id:
    client-secret:

Configure defaults that influence the client behaviour:

tasklist:
  client:
    defaults:
      load-truncated-variables: true
      return-variables: true
      use-zeebe-user-tasks: true

Plain Java

Depending on your setup, you may want to use different authentication mechanisms. In case you're using a Camunda Platform without identity enabled, you should use the SimpleAuthentication

SimpleConfig simpleConf = new SimpleConfig();
simpleConf.addProduct(Product.TASKLIST, new SimpleCredential("user", "pwd", "http://tasklistUrl[:port]"));
Authentication auth = SimpleAuthentication.builder().withSimpleConfig(simpleConf).build();

CamundaTaskListClient client = CamundaTaskListClient.builder()
  .taskListUrl("http://tasklistUrl[:port]")
  .authentication(auth)
  .cookieExpiration(Duration.ofSeconds(5))
  .build();

In case you're using a Self Managed Camunda Platform with identity enabled (and Keycloak), you should use the SelfManagedAuthentication

CamundaTaskListClient client = CamundaTaskListClient.builder()
  .taskListUrl("https://reg-x.tasklist.camunda.io/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/")
  .selfManagedAuthentication("clientId", "clientSecret", "keycloakUrl")
  .build();

And finally, if you're using a SaaS environment, just use the SaaSAuthentication

CamundaTaskListClient client = CamundaTaskListClient.builder()
  .taskListUrl("https://reg-x.tasklist.camunda.io/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/")
  .saaSAuthentication("clientId", "clientSecret")
  .build();

Simply build a CamundaTaskListClient that takes an authentication and the tasklist url as parameters.

ℹ️ Since the SelfManagedAuthentication and the SaaSAuthentication are a bit complex, two helpers have been added to the builder saaSAuthentication(clientId, clientSecret) and selfManagedAuthentication(clientId, clientSecret, keycloakUrl) as shown in previous examples. You can also build these SaaSAuthentication and SelfManagedAuthentication yourself, following the code provided in the helpers.

CamundaTaskListClient client = CamundaTaskListClient.builder().taskListUrl("http://localhost:8081").shouldReturnVariables().shouldLoadTruncatedVariables().authentication(auth).build();

ℹ️ shouldReturnVariables() will read variables along with tasks. This is not the recommended approach but rather a commodity. In real project implementation, we would recommend to load task variables only when required.

ℹ️ shouldLoadTruncatedVariables() will execute a second call to read the variable if its value was truncated in the initial search.

Make some queries

//get tasks from a process instance (TaskSearch can take many more parameters)
TaskSearch ts = new TaskSearch().setProcessInstanceId("2251799818839086");
TaskList tasksFromInstance = client.getTasks(ts);

//get tasks from process variables
ts = new TaskSearch().addVariableFilter("riskLevels", List.of("yellow", "yellow")).addVariableFilter("age", 30);
TaskList tasksFromVariableSearch = client.getTasks(ts);

//get tasks assigned to demo
TaskList tasks = client.getAssigneeTasks("demo", TaskState.CREATED, null);
for(Task task : tasks) {
    client.unclaim(task.getId());
}
//get tasks associated with group "toto"
tasks = client.getGroupTasks("toto", null, null);

//get 10 completed tasks without their variables (last parameter) associated with group "toto", assigned (second parameter) to paul (thrid parameter)
tasks = client.getTasks("toto", true, "paul", TaskState.COMPLETED, 10, false);

//navigate after, before, afterOrEqual to previous result.
tasks = client.after(tasks);
tasks = client.before(tasks);
tasks = client.afterOrEqual(tasks);

//get unassigned tasks
tasks = client.getTasks(false, null, null);
for(Task task : tasks) {
  //assign task to paul
  client.claim(task.getId(), "paul");
}
for(Task task : tasks) {
  //complete task with variables
  client.completeTask(task.getId(), Map.of("key", "value"));
}

//get a single task
task = client.getTask("1");

//get form schema
String formKey = task.getFormKey();
String formId = formKey.substring(formKey.lastIndexOf(":")+1);
String processDefinitionId = task.getProcessDefinitionId();

Form form = client.getForm(formId, processDefinitionId);
String schema = form.getSchema();

use it in your project

You can import it to your maven or gradle project as a dependency

<dependency>
  <groupId>io.camunda</groupId>
  <artifactId>camunda-tasklist-client-java</artifactId>
  <version>8.5.3.6</version>
</dependency>

Note

A similar library is available for the Operate API of Camunda Platform here: camunda-operate-client-java