https://github.com/holunda-io/camunda-bpm-data
Beautiful process data handling for Camunda 7 Platform.
https://github.com/holunda-io/camunda-bpm-data
api bpm camunda-7 data process
Last synced: 5 months ago
JSON representation
Beautiful process data handling for Camunda 7 Platform.
- Host: GitHub
- URL: https://github.com/holunda-io/camunda-bpm-data
- Owner: holunda-io
- License: apache-2.0
- Archived: true
- Created: 2019-10-09T09:59:51.000Z (over 6 years ago)
- Default Branch: develop
- Last Pushed: 2025-06-11T01:23:39.000Z (12 months ago)
- Last Synced: 2025-07-11T18:18:13.245Z (11 months ago)
- Topics: api, bpm, camunda-7, data, process
- Language: Kotlin
- Homepage: https://github.com/holunda-io/c7
- Size: 5.99 MB
- Stars: 34
- Watchers: 8
- Forks: 9
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Camunda BPM Data
> Beautiful process data handling for Camunda Platform 7.
[](https://github.com/holisticon#open-source-lifecycle)
[](https://github.com/holunda-io/camunda-bpm-data/actions/workflows/default.yml)
[](https://maven-badges.herokuapp.com/maven-central/io.holunda.data/camunda-bpm-data)
[](https://codecov.io/gh/holunda-io/camunda-bpm-data)
[](https://www.codacy.com/gh/holunda-io/camunda-bpm-data/dashboard?utm_source=github.com&utm_medium=referral&utm_content=holunda-io/camunda-bpm-data&utm_campaign=Badge_Grade)
# Relocation
This project is **relocated** to https://github.com/holunda-io/c7 and **will be developed** further there.
Last release produced from this location was **2025.05.1**
This repository will be archived.
## 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](https://www.holunda.io/camunda-bpm-data/snapshot/user-guide/features.html).
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](https://podcasts.apple.com/us/podcast/managing-data-in-processes-with-simon-zambrovski/id1478382505?i=1000547023972)
* [Data in Process (Part 1)](https://medium.com/holisticon-consultants/data-in-process-part-1-2620bf9abd76)
* [Data in Process (Part 2)](https://medium.com/holisticon-consultants/data-in-process-part-2-7c6a109e6ee2)
## Quick Introduction
### Setup
If you just want to start using the library, put the following dependency into your project `pom.xml`:
``` xml
io.holunda.data
camunda-bpm-data
1.5.0
```
If you are using Gradle Kotlin DSL add to your `build.gradle.kts`:
``` kotlin
implementation("io.holunda.data:camunda-bpm-data:1.5.0")
```
For Gradle Groovy DSL add to your `build.gradle`:
``` groovy
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:
``` java
import io.holunda.camunda.bpm.data.factory.VariableFactory;
import static io.holunda.camunda.bpm.data.CamundaBpmData.*;
public class OrderApproval {
public static final VariableFactory ORDER_ID = stringVariable("orderId");
public static final VariableFactory ORDER = customVariable("order", Order.class);
public static final VariableFactory ORDER_APPROVED = booleanVariable("orderApproved");
public static final VariableFactory ORDER_TOTAL = customVariable("orderTotal", BigDecimal.class);
public static final VariableFactory 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:
``` java
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:
``` java
@RestController
@RequestMapping("/task/approve-order")
public class ApproveOrderTaskController {
private final TaskService taskService;
public ApproveOrderTaskController(TaskService taskService) {
this.taskService = taskService;
}
@GetMapping("/{taskId}")
public ResponseEntity 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 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`.
``` java
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 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 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](https://www.holunda.io/camunda-bpm-data/snapshot/user-guide/examples-kotlin.html)
### Further documentation
For further details, please consult our [Quick Start](https://www.holunda.io/camunda-bpm-data/snapshot/quick-start)
guide or have a look to our primary documentation: [User Guide](https://www.holunda.io/camunda-bpm-data/snapshot/user-guide/motivation.html)
## Working Example
We prepared some typical usage scenarios and implemented two example projects in Java and Kotlin.
See our [Examples](https://www.holunda.io/camunda-bpm-data/snapshot/user-guide/examples.html) section for usage and configuration.
## License
[](LICENSE)
This library is developed under Apache 2.0 License.