|
|
|
|
|
|
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 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 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:
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.0.2</version>
</dependency>If you are using Gradle Kotlin DSL add to your build.gradle.kts:
implementation("io.holunda.data:camunda-bpm-data:1.0.2")For Gradle Groovy DSL add to your build.gradle:
implementation 'io.holunda.data:camunda-bpm-data:1.0.2'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);
}And 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()));
}
}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) {
Order order = ORDER.from(taskService, taskId).get();
return ResponseEntity.ok(new ApproveTaskDto(order));
}
@PostMapping("/{taskId}")
public ResponseEntity<Void> completeTask(@PathVariable("taskId") String taskId, @RequestBody ApproveTaskCompleteDto userInput) {
VariableMap vars = builder()
.set(ORDER_APPROVED, userInput.getApproved())
.build();
taskService.complete(taskId, vars);
return ResponseEntity.noContent().build();
}
}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 created an additional library module camunda-bpm-data-test.
Please put the following dependency into your pom.xml:
<dependency>
<groupId>io.holunda.data</groupId>
<artifactId>camunda-bpm-data-test</artifactId>
<version>1.0.1</version>
<scope>test</scope>
</dependency>Now you can use TaskServiceVariableMockBuilder to stub correct behavior of Camunda Task Service
and TaskServiceVerifier to verify the correct access to variables easily. Here is the JUnit
test of the REST controller above, making use of camunda-bpm-data-test.
public class ApproveOrderTaskControllerTest {
private static Order order = new Order("ORDER-ID-1", new Date(), new ArrayList<>());
private TaskService taskService = mock(TaskService.class);
private TaskServiceMockVerifier verifier = taskServiceMockVerifier(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
taskServiceVariableMockBuilder(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();
}
}For further details, please consult our Quick Start guide or have a look to our primary documentation - the User Guide.
We prepared some typical usage scenarios and implemented two example projects in Java and Kotlin. See our Examples section for usage and configuration.
This library is developed under Apache License 2.
If you want to contribute to this project, feel free to do so. Start with Contributing guide.