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:
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:
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
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?
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!
