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
Process instance Administration
- 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.
User task administration
- 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
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.