Are there Java classes for Camunda Rest responses?

Question

Im currently trying to set up REST calls from Spring to my local camunda instance using the camunda rest api.

Here's how i've set it up:

1. Started a local camunda docker container on my localhost:8080 like this: https://hub.docker.com/r/camunda/camunda-bpm-platform (i've tested calls with postman and they are working)

2. Built a maven project using a couple of camunda and rest dependencies in my pom.xml:

        <dependency>
            <groupId>org.camunda.bpm.springboot</groupId>
            <artifactId>camunda-bpm-spring-boot-starter</artifactId>
            <version>3.3.1</version>
        </dependency>

        <dependency>
            <groupId>org.camunda.bpm</groupId>
            <artifactId>camunda-engine-rest-core</artifactId>
            <version>7.11.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>

        <dependency>
            <groupId>org.projectreactor</groupId>
            <artifactId>reactor-spring</artifactId>
            <version>1.0.1.RELEASE</version>
        </dependency>

3. Wrote a simple service to make rest calls from Spring (taken from https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-webclient):

import org.camunda.bpm.engine.impl.persistence.entity.ProcessDefinitionEntity;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;

@Service
public class MyExampleService {

    private final WebClient webClient;

    public MyExampleService (WebClient.Builder webClientBuilder) {
        this.webClient = webClientBuilder.baseUrl("http://localhost:8080").build();
    }

    @Override
    public ProcessDefinitionEntity[] getCamundaProcesses() {

        ProcessDefinitionEntity[] myResponse = this.webClient.get().uri("/engine-rest/process-definition/")
                .retrieve()
                .onStatus(HttpStatus::is4xxClientError, response -> {
                    System.out.println("4xx eror");
                    return Mono.error(new RuntimeException("4xx"));
                })
                .onStatus(HttpStatus::is5xxServerError, response -> {
                    System.out.println("5xx eror");
                    return Mono.error(new RuntimeException("5xx"));
                })
                .bodyToMono(ProcessDefinitionEntity[].class)
                .block();

        return myResponse;
}

So I basically used Spring WebClient to make a rest call to localhost:8080/engine-rest/deployment/ which should give me a list of all processes as JSON (according to https://docs.camunda.org/manual/latest/reference/rest/deployment/get-query/).

Now when I convert the response directly into a ProcessDefinitionEntity[] it won't cast the JSON into it. I also tried other classes from the camunda Java API (https://docs.camunda.org/javadoc/camunda-bpm-platform/7.11/) like ProcessDefinitionDto.

None of the classes seem to properly fit the response I get from camunda. The response looks like this:

[
    {
        "id": "invoice:1:cdbc3f02-e6a1-11e9-8de8-0242ac110002",
        "key": "invoice",
        "category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
        "description": null,
        "name": "Invoice Receipt",
        "version": 1,
        "resource": "invoice.v1.bpmn",
        "deploymentId": "cda115de-e6a1-11e9-8de8-0242ac110002",
        "diagram": null,
        "suspended": false,
        "tenantId": null,
        "versionTag": "V1.0",
        "historyTimeToLive": 30,
        "startableInTasklist": true
    },
    {
        "id": "invoice:2:ce03f66c-e6a1-11e9-8de8-0242ac110002",
        "key": "invoice",
        "category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
        "description": null,
        "name": "Invoice Receipt",
        "version": 2,
        "resource": "invoice.v2.bpmn",
        "deploymentId": "cdfbb908-e6a1-11e9-8de8-0242ac110002",
        "diagram": null,
        "suspended": false,
        "tenantId": null,
        "versionTag": "V2.0",
        "historyTimeToLive": 45,
        "startableInTasklist": true
    }
]

(which are just the two standard processes that are in the docker container)

Are there classes in the camunda java api that properly match the responses from the camunda rest api?

PS: The ProcessDefinitionDto that i got from the maven dependency (which lies in package org.camunda.bpm.engine.rest.dto.repository.ProcessDefinitionDto) looks like this:

public class ProcessDefinitionDto {
    protected String id;
    protected String key;
    protected String category;
    protected String description;
    protected String name;
    protected int version;
    protected String resource;
    protected String deploymentId;
    protected String diagram;
    protected boolean suspended;
    protected String tenantId;
    protected String versionTag;
    protected Integer historyTimeToLive;
    protected boolean isStartableInTasklist;
...

And the Response that I get from my postman call to http://localhost:8080/engine-rest/process-definition looks like this:

[
    {
        "id": "b506eb34-e6b1-11e9-8de8-0242ac110002",
        "key": "example_workflow",
        "category": "http://bpmn.io/schema/bpmn",
        "description": null,
        "name": "Just an Example",
        "version": 1,
        "resource": "example_workflow.bpmn",
        "deploymentId": "b503b6e2-e6b1-11e9-8de8-0242ac110002",
        "diagram": null,
        "suspended": false,
        "tenantId": null,
        "versionTag": null,
        "historyTimeToLive": null,
        "startableInTasklist": true
    },
    {
        "id": "invoice:1:cdbc3f02-e6a1-11e9-8de8-0242ac110002",
        "key": "invoice",
        "category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
        "description": null,
        "name": "Invoice Receipt",
        "version": 1,
        "resource": "invoice.v1.bpmn",
        "deploymentId": "cda115de-e6a1-11e9-8de8-0242ac110002",
        "diagram": null,
        "suspended": false,
        "tenantId": null,
        "versionTag": "V1.0",
        "historyTimeToLive": 30,
        "startableInTasklist": true
    },
    {
        "id": "invoice:2:ce03f66c-e6a1-11e9-8de8-0242ac110002",
        "key": "invoice",
        "category": "http://www.omg.org/spec/BPMN/20100524/MODEL",
        "description": null,
        "name": "Invoice Receipt",
        "version": 2,
        "resource": "invoice.v2.bpmn",
        "deploymentId": "cdfbb908-e6a1-11e9-8de8-0242ac110002",
        "diagram": null,
        "suspended": false,
        "tenantId": null,
        "versionTag": "V2.0",
        "historyTimeToLive": 45,
        "startableInTasklist": true
    }
]

Answer 1

The classes in

org.camunda.bpm.engine.rest.dto.runtime

are suitable. (https://github.com/camunda/camunda-bpm-platform/tree/master/engine-rest/engine-rest/src/main/java/org/camunda/bpm/engine/rest/dto)

<dependency>
  <groupId>org.camunda.bpm</groupId>
  <artifactId>camunda-engine-rest-core</artifactId>
</dependency>

In your case it would be ProcessDefinitionDto Usage Example with Spring REST template:

@Service
@Slf4j
public class RuntimeServiceImpl implements RuntimeService {

    private final RestTemplate rest;
    @Value("${camunda.server.rest.url}")
    private String restURL;

    public RuntimeServiceImpl(RestTemplateBuilder builder) {
        this.rest = builder.build();
    }

    public ProcessDefinitionDto[] getProcessDefinitions() {

        ResponseEntity<ProcessDefinitionDto[]> response = rest.getForEntity(restURL + "process-definition/",
                ProcessDefinitionDto[].class);
        ProcessDefinitionDto[] processes = response.getBody();

        Arrays.stream(processes).forEach(pd -> log.info("Found process definition {} with id {} and key {}", pd.getName(), pd.getId(), pd.getKey()));

        return processes;
    }
}

Complete client project: https://github.com/rob2universe/camunda-rest-client

The external class client contains further interfaces and DTOs which you could reuse, such as

org.camunda.bpm.client.topic.impl.dto.FetchAndLockRequestDto; org.camunda.bpm.client.topic.impl.dto.TopicRequestDto;

Or just use / fork the complete client project. A lot work was already done for you there.

P.s. following comment: The response includes an array of process definitions with these fields:

[
    {
        "id": "AccountOpening:1:a6f88770-0ae7-11ea-9ef3-00155d00d800",
        "key": "AccountOpening",
        "category": "http://bpmn.io/schema/bpmn",
        "description": null,
        "name": "Account Opening",
        "version": 1,
        "resource": "C:\\account-opening\\target\\classes\\bpmn\\AccountOpening.bpmn",
        "deploymentId": "a6cc4747-0ae7-11ea-9ef3-00155d00d800",
        "diagram": null,
        "suspended": false,
        "tenantId": null,
        "versionTag": null,
        "historyTimeToLive": null,
        "startableInTasklist": true
    }

The target data structure in package org.camunda.bpm.engine.rest.dto.repository contains the same fields:

public class ProcessDefinitionDto {
    protected String id;
    protected String key;
    protected String category;
    protected String description;
    protected String name;
    protected int version;
    protected String resource;
    protected String deploymentId;
    protected String diagram;
    protected boolean suspended;
    protected String tenantId;
    protected String versionTag;
    protected Integer historyTimeToLive;
    protected boolean isStartableInTasklist;
   ...}

If the deserialization fails then ensure you are using the correct package (not for instance org.camunda.bpm.cockpit.impl.plugin.base.dto)

Answer 2

Are you looking at the correct package? There are multiple ProcessDefinitionDto classes in Camunda codebase. The one you're looking for is in the package org.camunda.bpm.engine.rest.dto.repository in camunda-engine-rest-core.jar

The class looks like this, which exactly matches your output:

package org.camunda.bpm.engine.rest.dto.repository;

import org.camunda.bpm.engine.repository.ProcessDefinition;

public class ProcessDefinitionDto {

  protected String id;
  protected String key;
  protected String category;
  protected String description;
  protected String name;
  protected int version;
  protected String resource;
  protected String deploymentId;
  protected String diagram;
  protected boolean suspended;
  protected String tenantId;
  protected String versionTag;
  protected Integer historyTimeToLive;
  protected boolean isStartableInTasklist;

  ...