Miranum-Connect is a library which enables developers to build reusable and technology neutral connectors and integrations between products. More information can be found in the official documentation.
Content of this readme:
- Version Compatibility
- Miranum-Worker
- Miranum-Process
- Miranum-Message
- Contribution
- Code of Conduct
- License
| Miranum Connect Version | JDK | Camunda Platform Versions | Compatible Spring Boot versions |
|---|---|---|---|
| >=0.1.0 | > 11 | >=8.0, >=7.15 | >= 2.7.6, 3.0.x |
To use the Java Miranum-Connect library, declare the following Maven dependency in your project. As artifact ID you need to choose one of the following modules: worker-api, message-api, process-api, json-api, task-api.
<dependency>
<groupId>io.miragon.miranum</groupId>
<artifactId>{worker-api, message-api, process-api, json-api, task-api}</artifactId>
<version>0.2.0</version>
</dependency>This library can be used only in combination with SpringBoot.
For fully executable examples, take a look at our miranum-consulting repository. Below, only small non-executable snippets are shown.
A Miranum-Worker connects to the process engine (e.g. Camunda Platform 7 or 8) and fetches tasks of a certain type. With this functionality, our integration perform various actions on such a task occurring in a process instance. After having worked and completed a task via a worker, the process engine continues to the next step.
To use the worker make sure to add the worker-api dependency to your project and import it to your java-class.
import io.miragon.miranum.connect.worker.api.Worker;A method which should acts as a worker needs to have the @Worker annotation. You are required to set a type which is used
as reference to specify which job worker request the respective service task job.
Your method can be of any return type. Set void if you do not want to store anything back to the scope of the process engine.
If you have an object in return it will be stored in a local-context in the process instance. If you want to use it globally
make sure to define the input/output mappings in your process.
@Worker(type = "my-type")
public void doSomething(DoSomethingCommand doSomethingCommand) {
doSomethingUseCase.doSomething(doSomethingCommand);
}Worker feature an adjustable retry count. In Camunda 8 it can be set through the BPMN model on a specific service task. The Camunda 7 worker have a default retry value of 3. The retry count can be configured as described in the C7 specific README.
Miranum-Process connects to the process engine (e.g. Camunda Platform 7 or 8) and enables users to start a process from code. Once you have started the process, you can use worker to step through it.
To use Miranum-Process make sure to add the process-api dependency to your project and import it to your java-class.
import io.miragon.miranum.connect.process.api.StartProcessCommand;
import io.miragon.miranum.connect.process.impl.StartProcessPort;To implement a method which starts a process instance from our code we use a REST-Controller in this example. You are not
limited to use REST and can also rely on gRPC and other API mechanisms.
For the start of the process instance, we need the StartProcessPort from our Miranum-Process implementation.
In the method triggerProcessStart we call the startProcessPort to start the actual process and submit a StartProcessCommand.
The command contains the key of the process which we want to start as well as possible variables which we want to
initialize on startup of the process instance.
@RestController
@RequestMapping("api/process")
@AllArgsConstructor
public class StartProcessController {
private final StartProcessPort startProcessPort;
@PutMapping("/start")
public ResponseEntity<Void> triggerProcessStart(@RequestBody final StartProcessRequestDto startProcessRequestDto) {
this.startProcessPort.startProcess(new StartProcessCommand(startProcessRequestDto.getProcessKey(), startProcessRequestDto.getVariables()));
return ResponseEntity.ok().build();
}
}Miranum-Message connects to the process engine (e.g. Camunda Platform 7 or 8) and enables users to correlate messages with process instance.
To use Miranum-Message make sure to add the message-api dependency to your project and import it to your java-class.
import io.miragon.miranum.connect.message.api.CorrelateMessageCommand;
import io.miragon.miranum.connect.message.api.MessageApi;To implement a method which handles the message correlation initialise
the Message-API. Having done so, we can create a new method correlateMessage which gets the CorrelateMessageCommand as an input.
Using messageApi.correlateMessage I can correlate the message with my process, by specifying the message name, correlation key
and the variables which should be sent back to the process.
In case a message correlation is not possible, an exception is thrown.
private final MessageApi messageApi;
public void correlateMessage(CorrelateMessageCommand message) {
log.info("Received message: " + message);
messageApi.correlateMessage(new CorrelateMessageCommand(message.getName(), message.getKey(), Map.of(message.getVariables())));
log.info(message + " successfully correlated")
}Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. To collect, prioritise and work on issues in a collaborative fashion we have established some contribution guidelines as well as a GitHub project. Please make sure to read through these guidelines before starting with your contribution.
All changes have to be done in a separate Branch or Fork (if you are an external contributor). As soon as the changes are done please open a PR. A GitHub Action runs with every commit to a Branch and checks if the documentation can be built. If you create a new branch make sure to name it according to what it does (e.g. feat/xyz or fix/xyz). Please use semantic commit messages as described in here.
We are using simple emoji's to help convey intention and added meaning in code review comments. A little bit of emoji can go a long way when it comes to code reviews and make giving and receiving code review a little bit more enjoyable. We are following this guide by erikthedeveloper.
This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to info@miragon.io.
Distributed under the MIT License. See LICENSE file for more information.