Read Blog Post

Read Blog Post

Contributed on May 2, 2021

403

413

Versioning of utility classes in RHPAM

Blog: Drools & jBPM Blog

In this post, we will describe how to perform versioning of utility classes in RHPAM.

After running your first process instances in a fresh RHPAM installation, the next time you will deploy something to the environment, is when your processes and business assets have evolved. Your new business assets will require to integrate their changes with the current client applications, as well as with the running process instances.

Note that the parts of the code that can possibly evolve, can be classified as:

• Utility Classes
• Model classes
• Rules
• Process definitions.

Firstly, let’s define Utility Classes. We often use utility classes in the script tasks and events, mainly for mapping process variables to service models. Thus Utility Classes define common functionality.

When using Utility Classes, keep in mind the following list of best practices:

• Define these methods to be static.
• Avoid System.out logs.
• Do not use thread operations like sleep or start thread.
• Keep away from calling remote services in these utility classes.

The use case: corrective repairs to manufacturing machinery.

Let’s consider an example, where multiple sensors in a manufacturing factory, report the state of the machine’s health, and other performance indicators. These sensors trigger Decision Management Services, that consequently will start a process for parts procurement:

The image above shows the “parts procurement process”. In short, the conversation models for web services are calculated with the help of PartsStorageUtil and PurchaseOrderUtil classes.

Running the utility class in its own version

The growth of the organization requires a change in the InventoryReservationRequest. When in the new version, all requests for inventory, will go through a central, and the parts requests will be dispatched to different branches.

In order to program the delivery of the parts, you are required to provide the Branch Code.
In conclusion, the requirement you get from the business is:

While my branches will be submitting new purchase orders to the central, any request that was previously originated in the original branch can continue to be processed in that branch.

Similarly, this means for my process service that: Any existing process instance running in the version 1.0 of my procurement process instance, can continue to run in its version; likewise, any new procurement order that includes the branch code for the central, will use the new version of the utility class.

The idea then for example, is that:

1. You start a process instance in version 1.0.
2. There are no parts available to fulfill the materials request.
3. The Process instance reaches the Purchase Order, and it is waiting for the “Received Materials” signal.

At this point, we introduce the change for the “Request Assign parts to Repair Request”. Thus, any new requests will need to include the “Branch Code” field. As a result, the existing process instance, will continue to send the “Assign Parts to Repair Request” without “Branch Code”.

Utility class as a dependency

The utility classes can be packaged in a jar file. Consequently, the jar file can be added as a dependency of the kjar where we want to use the utility classes. This allows changing the utility classes in a single place, and then, promote its use throughout the kjars.

By looking to the following image, you can notice that, in my example, I define the parts-storage-service and the purchase-orders-service web services. Notice that, in both web services, I define a domain model that dictates how its client applications can interact with them.

In the image above, you can see the relationship between the kjar (machinery-repair), the utility dependencies (jbpm-purchase-order-utils, and jbpm-parts-storage-utils), and the model jars that define the interaction with the web services.

Steps for the initial version

The initial version is created using the following steps:

1. Download and build the domain model jars from: 
   1. https://github.com/stark-demos/purchase-order-model/tree/1.0 
   2. https://github.com/stark-demos/parts-storage-model/tree/1.0 
2. Download and run the web services from:
   1. https://github.com/stark-demos/parts-storage-service/tree/1.0.0
   2. https://github.com/stark-demos/purchase-order-service/tree/1.0.0 
3. Download and build the test helper library: https://github.com/stark-demos/jbpm-mock/tree/1.0
4. Download and build the utility libraries:
   1. https://github.com/stark-demos/jbpm-purchase-order-utils/tree/1.0
   2. https://github.com/stark-demos/jbpm-parts-storage-utils/tree/1.0 
5. Download and build the kjar project: https://github.com/stark-demos/machinery-repair/tree/1.0.0
6. Deploy the kjar project to a kie-server that has persistence configuration to a relational database.
7. Start 3 process instances for the machinery-repair.parts-procurement_v1_0 process id.

Given that the inventory service does not have any parts, all process instances will request a purchase order, and wait for the “Received Materials” signal.

Steps to produce the change

The following steps create the version 2 of the kjar that connects to the web services version 2, that require the “Branch Code”:

1. Change the domain models to include the Branch Code field. (Inventory Reservation Request Model).
2. Modify the web service to use the branch code when requesting and responding to an inventory reservation.
3. Adapt the utility classes to read a process variable for the Branch Code and include it as part of the payload for the web service requests.
4. Adjust the process definition to receive the “Branch Code” as a process variable.
5. Deploy the kjar with new version (suggested as 2.0) to the kie-server. (The kie-server will have 2 containers now, the 1.0, and the 2.0).
6. Start 3 process instances for the machinery-repair.parts-procurement_v1_0 process id in the latest version.
7. Signal the previously existing process instances

For each change, remember to:

• Increase the component version in the pom.xml.
• Refactor and run the appropriate unit tests.

Note that the new process instances, and the old process instances use their own versions of the utility class. This helps to provide an example on versioning of utility classes RHPAM, by packaging the utility classes as dependencies for the RHPAM kjar.

Install the modified assets

In the following gitHub links you can find the solution to the previous exercise, install accordingly and compare with your results:

1. Download and build the domain model jar, the web service, the utility library and the kjar project from:
   1. https://github.com/stark-demos/parts-storage-model/tree/2.0
   2. https://github.com/stark-demos/parts-storage-service/tree/2.0.0 
   3. https://github.com/stark-demos/jbpm-parts-storage-utils/tree/2.0
   4. https://github.com/stark-demos/machinery-repair/tree/2.0.0 
2. Deploy the kjar project to the same kie-server, using the same alias used in the previous section for version 1.0.0;
3. Start 3 additional process instances for machinery-repair.parts-procurement_v2_0 process id.
4. Send the signal to the first 3 process instances, and note how they continue to interact with the services version 1.0 with no interruption.
5. Send the signal to the latest 3 process instances, and note how they continue to interact with the services version 2.0 with no interruption.

Conclusion

By setting the dependencies and separating the utility classes in their own jars, the process definitions are capable of executing their own version of the utility class in the same kie-server, thus providing an option for versioning of utility classes in RHPAM.

The post Versioning of utility classes in RHPAM appeared first on KIE Community.