Pluggable container locator and policy support in KIE Server

In this article, a container locator support was introduced. Commonly known as aliases. At that time it was by default using latest available version of the project configured with same alias. This idea was really well received and thus further enhanced.

Pluggable container locator

First of all, not always latest available container is the way to go. There might be a need to have time bound container selection for given alias, for example:

• there are two containers for given alias
• even though there is a new version already deployed it should not be used until predefined date

so users might implement their own container locator interface and register it by including that implementation bundled into a jar file on KIE Server class path. As usual, the discovery mechanism is based on ServiceLoader so the jar must include:

• implementation of ContainerLocator interface
• file named org.kie.server.services.api.ContainerLocator must be placed in META-INF/services directory
• include fully qualified class name of the ContainerLocator implementation in META-INF/services/org.kie.server.services.api.ContainerLocator file

Since there might be multiple implementation present on class path, container locator to be used needs to be given via system property:

• org.kie.server.container.locator where the value should be class name of the implementation of ContainerLocator interface - simple name not FQCN

that will be then used instead of default latest container locator.

so far so good, but what should happen with containers that are now idle or should not be used anymore? Since the container locator will make sure that selected (by default latest) container is going to be used in most of the cases, there might be containers that do no need to be on runtime any longer. Especially important in environments where new versions of containers are frequently deployed which might lead to increased use of memory. Thus efficient cleanup of not used containers is a must. 

Pluggable policy support

For this a policy support was added, but not only for this as policies are general purpose tool within KIE Server. So what's that?

Policy is a set of rules that are applied by KIE Server periodically. Each policy can be registered at different time to be applied. Policies are discovered when KIE Server starts and are registered but are not started by default. 

The reason for this is that the discovery mechanism (ServiceLoader) is based on class path scanning and thus are always performed regardless if they should be used or not. So there is another step required to make the policy to be activated. 

Policy activation is done by system property when booking KIE Server:

• org.kie.server.policy.activate - where value is a comma separated list of policies (their names) to be activated

When policy manager activates given policy it will respect its life cycle:

• will invoke start method of the policy
• will retrieve interval from the policy (invoke getInterval method)
• schedule periodic execution of that policy based on given interval - if interval is less than 1 it will ignore that policy

NOTE: scheduling is done based on interval for both first execution and then repeatable executions - meaning first execution will take place after interval. Interval must be given in milliseconds.

Similar, when KIE Server stops it will call stop method of every activated policy to properly shut it down.

Policy support can be used for various use cases, one that comes out of the box is to complement container locator (with its default latest only). So there is a policy available in KIE Server that will undeploy other container than latest. This police by default is applied once a day, but can be reconfigured via system properties. KeepLatestContainerOnlyPolicy will attempt to dispose containers that have lower versions, though it might fail on such attempt. Reasons of the failure might vary but most common will be when there are active process instances for container that is being disposed. In that case the container is left as started and the next day (or after another reconfigured period of time) the attempt will be retried. 

NOTE: KeepLatestContainerOnlyPolicy is aware of controller so it will notify controller that the policy was applied and stop container in controller only, but only stop it and not remove it. Same as any policy this one must be activated via system property as well.

This opens the door for tremendous amount of policy implementations, starting with cleanup, through blue-green deployments and finishing at reconfiguring runtimes. All performed periodically and automatically by KIE Server itself.

As always, comments and further ideas are more than welcome.

Administration interfaces in jBPM 7

In many cases, when working with business processes, users end up in situations that were not foreseen before, e.g. task was assigned to a user that left the company, timer was scheduled with wrong expiration time and so on.

jBPM from it's early days had the capabilities to deal with these though it required substantial knowledge on how to use low level apis of jBPM. These days are now over, jBPM version 7 comes with administration api that cover:

• process instance operations
• user task operations
• process instance migration

These administration interfaces are supported in jBPM services and in KIE Server so users have full power of performing quite advanced operations when utilizing jBPM as process engine regardless if that is embedded (jbpm services api) or as a service (KIE Server).

Let's start quickly by looking what sort of capabilities each of the service provide.

Process instance Administration

Process instance administration service provides operations around the process engine and individual process instance, following is complete list of operations supported and their short description:

• get process nodes - by process instance id - this returns all nodes (including embedded subprocesses) that exists in given process instance. Even though the nodes come from process definition it's important to get them via process instance to make sure that given node exists and have valid node id so it can be used with other admin operations successfully
• cancel node instance - by process instance id and node instance id - does exactly what the name suggests - cancels given nodes instance within process instance
• retrigger node instance - by process instance id and node instance id - retrigger by first canceling the active node instance and create new instance of the same type - sort of recreates the node instance
• update timer - by process instance id and timer id - updates timer expiration of active timer. It updates the timer taking into consideration time elapsed since the timer was scheduled. For example: In case timer was initially created with delay of 1 hour and after 30 min it's decided to update it to 2 hours it will then expire in 1,5 hour from the time it was updated. Allows to update
• delay - duration after timer expires
• period - interval between timer expiration - applicable only for cycle timers
• repeat limit - limit the expiration to given number - applicable only for cycle timers
• update timer relative to current time - by process instance id and timer id - similar to regular update time but the update is relative to the current time - for example: In case timer was initially created with delay of 1 hour and after 30 min it's decided to update it to 2 hours it will then expire in 2 hours from the time it was updated.
• list timer instances - by process instance id - returns all active timers found for given process instance
• trigger node - by process instance id and node id - allows to trigger (instantiate) any node in process instance at any time.

Complete ProcessInstanceAdminService can be found here.

KIE Server client version of it can be found here.

User task administration

User task administration mainly provides useful methods to manipulate task assignments (users and groups), data handling and automatic (time based) notifications and reassignments. Following is complete list of operations supported for user task administration service:

• add/remove potential owners - by task id - supports both users and groups with option to remove existing assignment
• add/remove excluded owners - by task id - supports both users and groups with option to remove existing assignment
• add/remove business administrators  - by task id - supports both users and groups with option to remove existing assignment
• add task inputs - by task id - modify task input content after task has been created
• remove task inputs - by task id - completely remove task input variable(s)
• remove task output - by task id - completely remove task output variable(s)
• schedules new reassignment to given users/groups after given time elapses - by task id - schedules automatic reassignment based on time expression and state of the task:
• reassign if not started (meaning when task was not moved to InProgress state)
• reassign if not completed (meaning when task was not moved to Completed state)
• schedules new email notification to given users/groups after given time elapses - by task id - schedules automatic notification based on time expression and state of the task:
• notify if not started (meaning when task was not moved to InProgress state)
• notify if not completed (meaning when task was not moved to Completed state)
• list scheduled task notifications - by task id - returns all active task notifications
• list scheduled task reassignments - by task id - returns all active tasks reassignments
• cancel task notification - by task id and notification id - cancels (and unschedules) task notification
• cancel task reassignment - by task id and reassignment id - cancels (and unschedules) task reassignment

NOTE: all user task admin operations must be performed as business administrator of given task - that means every single call to user task admin service will be checked in terms of authorization and only business administrators of given task will be allowed to perform the operation.

Complete UserTaskAdminService can be found here.

KIE Server client version of it can be found here.

Process instance migration

ProcessInstanceMigrationService provides administrative utility to move given process instance(s) from one deployment to another or one process definition to another. It’s main responsibility is to allow basic upgrade of process definition behind given process instance. That might include mapping of currently active nodes to other nodes in new definition.

Migration does not deal with process or task variables, they are not affected by migration. Essentially process instance migration means a change of underlying process definition process engine uses to move on with process instance.

Even though process instance migration is available it’s recommended to let active process instances finish and then start new instances with new version whenever possible. In case that approach can’t be used, migration of active process instance needs to be carefully planned before its execution as it might lead to unexpected issues.Most important to take into account is:

• is new process definition backward compatible?
• are there any data changes (variables that could affect process instance decisions after migration)?
• is there need for node mapping?

Answers to these questions might save a lot of headache and production problems after migration. Best is to always stick with backward compatible processes - like extending process definition rather than removing nodes. Though that’s not always possible and in some cases there is a need to remove certain nodes from process definition. In that situation, migration needs to be instructed how to map nodes that were removed in new definition in case active process instance is at the moment in such a node.

Complete ProcessInstanceMigrationService can be found here.

KIE Server version of it can be found here.

With this, I'd like to emphasize that administrators of jBPM should be well equipped with enough tools for the most common operations they might face. Obviously that won't cover al possible cases so we're are more than interested in users feedback on what else might be there as admin function. So share it!