Skip to content

Commit b9ea65e

Browse files
martinweilerrgdoliveira
martinweiler
authored and
rgdoliveira
committed
[incubator-kie-issues#1220] Quarkus example to showcase PIM functionality (apache#1979)
* [incubator-kie-issues#1220] Quarkus example to showcase PIM functionality * Align example with compact architecture setup
1 parent d4e99d8 commit b9ea65e

File tree

17 files changed

+1335
-0
lines changed

17 files changed

+1335
-0
lines changed

‎kogito-quarkus-examples/process-instance-migration-quarkus/README.md

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
# Process Instance Migration (PIM) example
2+
3+
## Description
4+
5+
This example showcases the Process Instance Migration (PIM) functionality. This feature can be used to migrate
6+
active process instances from one process definition (v1) to another (v2).
7+
8+
This example is using the *Compact Architecture* that is based on simplified communication among the different
9+
*Kogito* services without the need of events (Kafka/HTTP) between them. Note that this design choice is unrelated
10+
to the Process Instance Migration functionality.
11+
12+
## The test processes
13+
14+
### The original BPMN Process
15+
16+
<div style="text-align:center">
17+
<figure>
18+
<img width=75% src="docs/images/simple.png" alt="Simple Process Diagram">
19+
<figcaption>Simple Process Diagram</figcaption>
20+
</figure>
21+
</div>
22+
23+
The process follows a very basic design with two script tasks and a catching signal event in between to act as a wait state.
24+
25+
<div style="text-align:center">
26+
<figure>
27+
<img width=75% src="docs/images/modified.png" alt="Modified Process Diagram">
28+
<figcaption>Modified Process Diagram</figcaption>
29+
</figure>
30+
</div>
31+
32+
The modified version of this simple process has own additional script task **after** the wait state.
33+
34+
35+
## Running the example
36+
### Prerequisites
37+
38+
* Java 17+ installed
39+
* Environment variable JAVA_HOME set accordingly
40+
* Maven 3.9.3+ installed
41+
* Docker and Docker Compose to run the required example infrastructure.
42+
43+
And when using native image compilation, you will also need:
44+
- GraalVM 20.3+ installed
45+
- Environment variable GRAALVM_HOME set accordingly
46+
- GraalVM native image needs as well native-image extension: https://www.graalvm.org/reference-manual/native-image/
47+
- Note that GraalVM native image compilation typically requires other packages (glibc-devel, zlib-devel and gcc) to be installed too, please refer to GraalVM installation documentation for more details.
48+
49+
### Infrastructure Services
50+
51+
This quickstart provides a docker compose template that starts all the required services. This setup ensures that all services are connected with a default configuration.
52+
53+
- PostgreSQL: 5432
54+
- PgAdmin: 8055
55+
- Kogito Process Instance Migration Service: 8080
56+
57+
To help bootstraping the Infrastructure Services, the example provides the `startServices.sh` script inside the *docker-compose*
58+
folder.
59+
60+
> **_NOTE_**: the docker compose template requires using _extra_hosts_ to allow the services use the host network, this may
61+
> carry some issues if you are using a **podman** version older than **4.7**.
62+
63+
### Building & Running the example
64+
65+
To build the example, on a Terminal, run the following command:
66+
```shell
67+
mvn clean package -Pcontainer
68+
```
69+
This will build the example quarkus application and create a Docker image that will be started in the `docker-compose` template.
70+
71+
To execute the full example (including consoles), open a Terminal and run the following command inside the `docker-compose` folder:
72+
73+
```shell
74+
sh startServices.sh
75+
```
76+
77+
Additionally, if you want to start only the example and the minimal Infrastructure Services (PostgreSQL, Data-Index and Jobs Service),
78+
you can run the same `startServices.sh` script but passing the `example` argument
79+
80+
```shell
81+
sh startServices.sh example
82+
```
83+
84+
> **_NOTE:_** starting the Infrastructure Services, please consider running a ```mvn clean package -Pcontainer```
85+
> command on the project root before running the ```startServices.sh``` script for the first time or any time you modify the project.
86+
87+
### Running the example in Development mode
88+
89+
To run the example in Development mode, just run the following command in a Terminal:
90+
91+
```shell
92+
mvn clean package quarkus:dev -Pdevelopment
93+
```
94+
95+
The Development Mode will embed all the needed Infrastructure Services (PostgreSQL, Data-Index & Jobs Service) and won't
96+
require any extra step.
97+
98+
The `development` profile includes the **Runtime Tools Quarkus Extension** that exposes a new section in the **Quarkus Dev-UI**
99+
unifying the **Management Console** & **Task Console** functionalities. **Quarkus Dev-UI** is available at http://localhost:8080/q/dev
100+
101+
> **_NOTE:_** For more information about how to work with Kogito Runtime Tools Quarkus Extension, please refer to the [Kogito Documentation](https://docs.kogito.kie.org/latest/html_single/#con-runtime-tools-dev-ui_kogito-developing-process-services) page.
102+
103+
### Executing an instance of the Simple Process
104+
105+
Once the service is up and running you can start an instance of the **Simple** process by a sending request to `http://localhost:8080/simple`.
106+
107+
108+
In a Terminal you can execute this curl command to start a **Simple** process:
109+
```bash
110+
curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/simple -d '{}'
111+
```
112+
113+
If everything went well you may get a response like:
114+
```json
115+
{
116+
"id": "b97efe7d-dc9b-4da8-8b3e-6100f8d8b045"
117+
}
118+
```
119+
120+
In the console of the example container you should see the following log message:
121+
```
122+
Started process e4bf4948-1f56-4ee3-9f2c-5010aaf50701 [simple, v1.0]
123+
```
124+
125+
To finish this process instance, execute the following command, using the process instance id previously returned, to send a signal:
126+
```bash
127+
curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/simple/e4bf4948-1f56-4ee3-9f2c-5010aaf50701/continue -d '{}'
128+
```
129+
130+
In the console of the example container you should see the following log message:
131+
```
132+
Ending process e4bf4948-1f56-4ee3-9f2c-5010aaf50701 [simple, v1.0]
133+
```
134+
135+
### Using PIM to migrate a process instance from the Simple Process to the Modified Process
136+
137+
In a Terminal, start another instance of the **Simple** process:
138+
```bash
139+
curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/simple -d '{}'
140+
```
141+
142+
Note the new process instance id that is returned by the engine:
143+
```json
144+
{
145+
"id": "2a507f63-9db1-4d15-b64c-9e14f922d470"
146+
}
147+
```
148+
149+
Using the Management API, the following two endpoints can be used to migrate active process instances:
150+
* `/management/processes/{processId}/migrate`: Use this endpoint to migrate **all** active process instances of a given `processId` to a new target process definition
151+
* `/management/processes/{processId}/instances/{processInstanceId}/migrate`: Use this endpoint to migrate a specific process instance of a given `processId` to a new target process definition
152+
153+
In a Terminal, invoke the Management API to migrate the newly created process instance:
154+
```bash
155+
curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/management/processes/simple/migrate -d '{
156+
"targetProcessId": "modified",
157+
"targetProcessVersion": "1.0"
158+
}'
159+
```
160+
161+
The response will contain information about the migration:
162+
```json
163+
{
164+
"message":"All intances migrated",
165+
"numberOfProcessInstanceMigrated":1
166+
}
167+
```
168+
169+
Alternatively, use the following endpoint to migrate just a single process instance:
170+
```bash
171+
curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/management/processes/simple/instances/2a507f63-9db1-4d15-b64c-9e14f922d470/migrate -d '{
172+
"targetProcessId": "modified",
173+
"targetProcessVersion": "1.0"
174+
}'
175+
```
176+
177+
178+
Note that the invocation of the `migrate` endpoint is the first step of the PIM functionality. It flags the selected process instance(s) as migrated to the defined target process definition. The second step of the migration will happen the next time the process instance is unmarshalled. This would be the case when the process instance is triggered to continue its execution. If you want to test whether this unmarshalling step is successful after the migration, the following PUT call can be used without triggering the execution of the process instance:
179+
```bash
180+
curl -H "Content-Type: application/json" -H "Accept: application/json" -X PUT http://localhost:8080/modified/2a507f63-9db1-4d15-b64c-9e14f922d470 -d '{}'
181+
```
182+
183+
If successful, this call will just return the processInstanceId of the process instance.
184+
185+
186+
To finish this process instance, execute the following command, using the process instance id previously returned, to send a signal against the endpoint of the **Modified** process:
187+
```bash
188+
curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/modified/2a507f63-9db1-4d15-b64c-9e14f922d470/continue -d '{}'
189+
```
190+
191+
In the console of the example container you should see the following log messages:
192+
```
193+
Executing added node
194+
Ending process 2a507f63-9db1-4d15-b64c-9e14f922d470 [modified, v1.0]
195+
```
196+
197+
### Using PIM to migrate a process instance from the Simple Process to the Addedtask Process with a migration plan
198+
199+
In the first migration example, the **Modified** process contained an added node after the current wait state. The wait state itself was unchanged in both process definitions, using the same internal node id. Therefore, no additional information had to be provided for the migration to be successful.
200+
201+
Consider another modification of the original **Simple** process, this time adding a Human Task node **before** the Catching Signal Event:
202+
203+
<div style="text-align:center">
204+
<figure>
205+
<img width=75% src="docs/images/addedtask.png" alt="Addedtask Process Diagram">
206+
<figcaption>Addedtask Process Diagram</figcaption>
207+
</figure>
208+
</div>
209+
210+
With this change, the BPMN representation has changed in a way that the Catching Signal Event now has a different nodeId:
211+
212+
**[src/main/resources/simple.bpmn](src/main/resources/simple.bpmn)**
213+
```xml
214+
<bpmn2:intermediateCatchEvent id="_8430CA7E-8CC6-4C2C-9664-6B5BBD5E36CB">
215+
```
216+
217+
**[src/main/resources/addedtask.bpmn](src/main/resources/addedtask.bpmn)**
218+
```xml
219+
<bpmn2:intermediateCatchEvent id="_1D65864A-96AF-44FC-92CE-2073B9FBA7D0">
220+
```
221+
222+
In order to migrate process instances between process definitions with such changes, we need to provide a Migration Plan File (extension *.mpf). This file defines the migration plan with all required node mappings:
223+
224+
**[src/main/resources/META-INF/migration-plan/addedtask_migration.mpf](src/main/resources/META-INF/migration-plan/addedtask_migration.mpf)**
225+
```json
226+
{
227+
"name" : "simple to addedtask migration",
228+
"processMigrationPlan" : {
229+
"sourceProcessDefinition" : {
230+
"processId" : "simple",
231+
"processVersion" : "1.0"
232+
},
233+
"targetProcessDefinition" : {
234+
"processId" : "addedtask",
235+
"processVersion" : "1.0"
236+
},
237+
"nodeInstanceMigrationPlan" : [
238+
{
239+
"sourceNodeId" : "_8430CA7E-8CC6-4C2C-9664-6B5BBD5E36CB",
240+
"targetNodeId" : "_1D65864A-96AF-44FC-92CE-2073B9FBA7D0"
241+
}
242+
]
243+
}
244+
}
245+
```
246+
247+
Now that we have this migration plan deployed with our new process, we can test the Process Instance Migration with the same steps as before.
248+
249+
In a Terminal, start another instance of the **Simple** process:
250+
```bash
251+
curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/simple -d '{}'
252+
```
253+
254+
Note the new process instance id that is returned by the engine:
255+
```json
256+
{
257+
"id": "29ec3980-9f0f-4b92-8a2d-394ffdb477e3"
258+
}
259+
```
260+
261+
In a Terminal, invoke the Management API to migrate the newly created process instance:
262+
```bash
263+
curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/management/processes/simple/migrate -d '{
264+
"targetProcessId": "addedtask",
265+
"targetProcessVersion": "1.0"
266+
}'
267+
```
268+
269+
The response will contain information about the migration:
270+
```json
271+
{
272+
"message":"All intances migrated",
273+
"numberOfProcessInstanceMigrated":1
274+
}
275+
```
276+
277+
To finish this process instance, execute the following command, using the process instance id previously returned, to send a signal against the endpoint of the **Addedtask** process:
278+
```bash
279+
curl -H "Content-Type: application/json" -H "Accept: application/json" -X POST http://localhost:8080/addedtask/29ec3980-9f0f-4b92-8a2d-394ffdb477e3/continue -d '{}'
280+
```
281+
282+
In the console of the example container you should see the following log messages:
283+
```
284+
Ending process 29ec3980-9f0f-4b92-8a2d-394ffdb477e3 [addedtask, v1.0]
285+
```
286+

‎kogito-quarkus-examples/process-instance-migration-quarkus/docker-compose/.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.env
2+
svg/
3+
persistence/

‎kogito-quarkus-examples/process-instance-migration-quarkus/docker-compose/README.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Kogito and Infrastructure services
2+
3+
To allow a quick setup of all services required to run this demo, we provide a docker compose template that starts the following services:
4+
- Postgresql
5+
- PgAdmin
6+
- Kogito Process Instance Migration Service (Only available if the example has been compiled using the `container` mvn profile eg: ```mvn clean package -Pcontainer```)
7+
8+
The docker compose template provides three profiles to enable starting only the set of services you want to use. The profiles are:
9+
- **infra**: Starts only the minimal infrastructure to run the example (Postgresql, pgadmin)
10+
- **example**: Starts the services in *infra* profile and the Kogito Example Service. Requires the example to be compiled using the `container` mvn profile eg: ```mvn clean package -Pcontainer```.
11+
12+
> NOTE: In order to use it, please ensure you have Docker Compose installed on your machine, otherwise follow the instructions available
13+
in [here](https://docs.docker.com/compose/install/).
14+
15+
## Starting the services
16+
17+
Use the `startServices.sh` passing the docker profile you want to use as an argument. If no profile is provided the script will default to **full**.
18+
19+
Eg:
20+
```shell
21+
sh startServices.sh example
22+
```
23+
24+
Once the services are started (depending on the profile), the following ports will be assigned on your local machine:
25+
- Postgresql: 5432
26+
- PgAdmin: 8055
27+
- Kogito Process Instance Migration Service: 8080
28+
29+
## Stopping and removing volume data
30+
31+
To stop all services, simply run:
32+
33+
```shell
34+
docker compose stop
35+
```
36+
or
37+
38+
```shell
39+
docker compose down
40+
```
41+
to stop the services and remove the containers.
42+
43+
For more details please check the Docker Compose documentation.
44+
45+
```shell
46+
docker-compose --help
47+
```

0 commit comments

Comments
 (0)