Camunda BPM Data

Beautiful process data handling for Camunda Platform 7.

Why to use this library in every Camunda project

If you are a software engineer and run process automation projects in your company or on behalf of the customer based on Camunda Process Engine, you probably are familiar with process variables. Camunda offers an API to access them and thereby manipulate the state of the process execution - one of the core features during process automation.

Unfortunately, as a user of the Camunda Platform 7 API, you have to exactly know the variable type (so the Java class behind it). For example, if you store a String in a variable "orderId" you must extract it as a String in every piece of code. Since there is no code connection between the different code parts, but the BPMN process model orchestrates these snippets to a single process execution, it makes refactoring and testing of process automation projects error-prone and challenging.

This library helps you to overcome these difficulties and make access, manipulation and testing process variables really easy and convenient. We leverage the Camunda Platform 7 API and offer you not only a better API but also some additional features.

If you want to read more about data in Camunda processes, have a look on those articles:

• Camunda Nation Podcast - Managing Data in Processes, with Simon Zambrovski
• Data in Process (Part 1)
• Data in Process (Part 2)

Quick Introduction

Setup

If you just want to start using the library, put the following dependency into your project pom.xml:

<dependency>
  <groupId>io.holunda.data</groupId>
  <artifactId>camunda-bpm-data</artifactId>
  <version>1.5.0</version>
</dependency>

If you are using Gradle Kotlin DSL add to your build.gradle.kts:

implementation("io.holunda.data:camunda-bpm-data:1.5.0")

For Gradle Groovy DSL add to your build.gradle:

implementation 'io.holunda.data:camunda-bpm-data:1.5.0'

Variable declaration

Now your setup is completed, and you can declare your variables like this:

import io.holunda.camunda.bpm.data.factory.VariableFactory;
import static io.holunda.camunda.bpm.data.CamundaBpmData.*;

public class OrderApproval {
  public static final VariableFactory<String> ORDER_ID = stringVariable("orderId");
  public static final VariableFactory<Order> ORDER = customVariable("order", Order.class);
  public static final VariableFactory<Boolean> ORDER_APPROVED = booleanVariable("orderApproved");
  public static final VariableFactory<BigDecimal> ORDER_TOTAL = customVariable("orderTotal", BigDecimal.class);
  public static final VariableFactory<OrderPosition> ORDER_POSITION = customVariable("orderPosition", OrderPosition.class);
}

Variable access from Java Delegate

Finally, you want to access them from your Java delegates, Execution or Task Listeners or simple Java components:

public class MyDelegate implements JavaDelegate {
  @Override
  public void execute(DelegateExecution execution) {
    VariableReader reader = CamundaBpmData.reader(execution);
    OrderPosition orderPosition = reader.get(ORDER_POSITION);
    BigDecimal oldTotal = reader.getOptional(ORDER_TOTAL).orElse(BigDecimal.ZERO);

    BigDecimal newTotal = oldTotal.add(calculatePrice(orderPosition));
    ORDER_TOTAL.on(execution).setLocal(newTotal);
  }

  private BigDecimal calculatePrice(OrderPosition orderPosition) {
     return orderPosition.getNetCost().multiply(BigDecimal.valueOf(orderPosition.getAmount()));
  }
}

Variable access from REST Controller

Now imagine you are implementing a REST controller for a user task form which loads data from the process application, displays it, captures some input and sends that back to the process application to complete the user task. By doing so, you will usually need to access process variables. Here is an example:

@RestController
@RequestMapping("/task/approve-order")
public class ApproveOrderTaskController {

    private final TaskService taskService;

    public ApproveOrderTaskController(TaskService taskService) {
        this.taskService = taskService;
    }

    @GetMapping("/{taskId}")
    public ResponseEntity<ApproveTaskDto> loadTask(@PathVariable("taskId") String taskId) {
        VariableReader reader = CamundaBpmData.reader(taskService, taskId);
        Order order = reader.get(ORDER);
        return ResponseEntity.ok(new ApproveTaskDto(order));
    }

    @PostMapping("/{taskId}")
    public ResponseEntity<Void> completeTask(@PathVariable("taskId") String taskId, @RequestBody ApproveTaskCompleteDto userInput) {
        VariableMap vars = CamundaBpmData.builder()
            .set(ORDER_APPROVED, userInput.getApproved())
            .build();
        taskService.complete(taskId, vars);
        return ResponseEntity.noContent().build();
    }
}

Testing correct variable access

If you want to write the test for the REST controller, you will need to stub the task service and verify that the correct variables has been set. To simplify these tests, we added some helper code to the famous library camunda-platform-7-mockito.

Now you can use TaskServiceVariableStubBuilder to stub correct behavior of Camunda Task Service and TaskServiceVerification to verify the correct access to variables easily. Here is the JUnit test of the REST controller above, making use of camunda-platform-7-mockito.

public class ApproveOrderTaskControllerTest {

    private static Order order = new Order("ORDER-ID-1", new Date(), new ArrayList<>());
    private TaskService taskService = mock(TaskService.class);
    private TaskServiceVerification verifier = new TaskServiceVerification(taskService);
    private ApproveOrderTaskController controller = new ApproveOrderTaskController(taskService);
    private String taskId;

    @Before
    public void prepareTest() {
        reset(taskService);
        taskId = UUID.randomUUID().toString();
    }

    @Test
    public void testLoadTask() {
        // given
        new TaskServiceVariableStubBuilder(taskService).initial(ORDER, order).build();
        // when
        ResponseEntity<ApproveTaskDto> responseEntity = controller.loadTask(taskId);
        // then
        assertThat(responseEntity.getStatusCode()).isEqualTo(HttpStatus.OK);
        assertThat(responseEntity.getBody()).isEqualTo(new ApproveTaskDto(order));
        verifier.verifyGet(ORDER, taskId);
        verifier.verifyNoMoreInteractions();
    }

    @Test
    public void testCompleteTask() {
        // when
        ApproveTaskCompleteDto response = new ApproveTaskCompleteDto(true);
        ResponseEntity<Void> responseEntity = controller.completeTask(taskId, response);
        // then
        assertThat(responseEntity.getStatusCode()).isEqualTo(HttpStatus.NO_CONTENT);
        verifier.verifyComplete(builder().set(ORDER_APPROVED, response.getApproved()).build(), taskId);
        verifier.verifyNoMoreInteractions();
    }
}

Kotlin

If you use kotlin, there is an own collection of factory methods by simple using CamundaBpmDataKotlin instead of CamundaBpmData. For usage examples, see here: Examples Kotlin

Further documentation

For further details, please consult our Quick Start guide or have a look to our primary documentation: User Guide

Working Example

We prepared some typical usage scenarios and implemented two example projects in Java and Kotlin. See our Examples section for usage and configuration.

License

This library is developed under Apache 2.0 License.

Contribution

If you want to contribute to this project, feel free to do so. Start with Contributing guide.

Maintainer

zambrovski	jangalinski	christian-maschmann	stefanzilske	nernsting	pschalk	srsp