Chapter 28. Process instance management

To view process instances, in Business Central click MenuManageProcess Instances.

+ NOTE: Each row in the Manage Process Instances list represents a process instance from a particular process definition. Each instance has its own internal state of the information that the process is manipulating. Click a process instance to view the corresponding tabs with runtime information related to the process.

Figure 28.1. Process instance tab view

Process instance tab view
  • Instance Details: Provides an overview about what is going on inside the process. It displays the current state of the instance and the current activity that is being executed.
  • Process Variables: Displays all of the process variables that are being manipulated by the instance, with the exception of the variables that contain documents. You can edit the process variable value and view its history.
  • Documents: Displays process documents if the process contains a variable of the type org.jbpm.Document. This enables access, download, and manipulation of the attached documents.
  • Logs: Displays process instance logs for the end users. For more information, see Interacting with processes and tasks.
  • Diagram: Tracks the progress of the process instance through the BPMN2 diagram. The node or nodes of the process flow that are in progress are highlighted in red. Reusable sub-processes appear collapsed within the parent process. Double-click on the reusable sub-process node to open its diagram from the parent process diagram.

For information on user credentials and conditions to be met to access KIE Server runtime data, see Planning a Red Hat Process Automation Manager installation.

28.1. Process instance filtering

For process instances in MenuManageProcess Instances, you can use the Filters and Advanced Filters panels to sort process instances as needed.

Procedure

  1. In Business Central, go to MenuManageProcess Instances.
  2. On the Manage Process Instances page, click the Filters icon on the left of the page to select the filters that you want to use:

    • State: Filter process instances based on their state (Active, Aborted, Completed, Pending, and Suspended).
    • Errors: Filter process instances that contain at least one or no errors.
    • Filter By: Filter process instances based on the following attributes:

      • Id: Filter by process instance ID.

        Input: Numeric

      • Initiator: Filter by the user ID of the process instance initiator.

        The user ID is a unique value, and depends on the ID management system.

        Input: String

      • Correlation key: Filter by correlation key.

        Input: String

      • Description: Filter by process instance description.

        Input: String

    • Name: Filter process instances based on process definition name.
    • Definition ID: The ID of the instance definition.
    • Deployment ID: The ID of the instance deployment.
    • SLA Compliance: SLA compliance status (Aborted, Met, N/A, Pending, and Violated).
    • Parent Process ID: The ID of the parent process.
    • Start Date: Filter process instances based on their creation date.
    • Last update: Filter process instances based on their last modified date.

You can also use the Advanced Filters option to create custom filters in Business Central.

28.2. Creating a custom process instance list

You can view the list of all the running process instances in MenuManageProcess Instances in Business Central. From this page, you can manage the instances during run time and monitor their execution. You can customize which columns are displayed, the number of rows displayed per page, and filter the results. You can also create a custom process instance list.

Prerequisites

  • A project with a process definition has been deployed in Business Central.

Procedure

  1. In Business Central, go to MenuManageProcess Instances.
  2. In the Manage Process Instances page, click the advanced filters icon on the left to open the list of process instance Advanced Filters options.
  3. In the Advanced Filters panel, enter the name and description of the filter that you want to use for your custom process instance list, and click Add New.
  4. From the list of filter values, select the parameters and values to configure the custom process instance list, and click Save.

    A new filter is created and immediately applied to the process instances list. The filter is also saved in the Saved Filters list. You can access saved filters by clicking the star icon on the left side of the Manage Process Instances page.

28.3. Managing process instances using a default filter

You can set a process instance filter as a default filter using the Saved Filter option in Business Central. A default filter will be executed every time when the page is open by the user.

Procedure

  1. In Business Central, go to MenuManageProcess Instances.
  2. On the Manage Process Instances page, click the star icon on the left of the page to expand the Saved Filters panel.

    In the Saved Filters panel, you can view the saved advanced filters.

    Default filter selection for Process Instances

    Default filter selection for Process Instances

  3. In the Saved Filters panel, set a saved process instance filter as the default filter.

28.4. Viewing process instance variables using basic filters

Business Central provides basic filters to view process instance variables. You can view the process instance variables of the process as columns using Show/hide columns.

Procedure

  1. In Business Central, go to MenuManageProcess Instances.
  2. On the Manage Process Instances page, click the filter icon on the left of the page to expand the Filters panel.
  3. In the Filters panel, select the Definition Id and select a definition ID from the list.

    The filter is applied to the current process instance list.

  4. Click columns icon (to the right of Bulk Actions) in the upper-right of the screen to display or hide columns in the process instances table.
  5. Click the star icon to open the Saved Filters panel.

    In the Saved Filters panel, you can view all the saved advanced filters.

28.5. Viewing process instance variables using advanced filters

You can use the Advanced Filters option in Business Central to view process instance variables. When you create a filter over the column processId, you can view the process instance variables of the process as columns using Show/hide columns.

Procedure

  1. In Business Central, go to MenuManageProcess Instances.
  2. On the Manage Process Instances page, click the advanced filters icon to expand the Advanced Filters panel.
  3. In the Advanced Filters panel, enter the name and description of the filter, and click Add New.
  4. From the Select column list, select the processId attribute. The value will change to processId != value1.
  5. From the Select column list, select equals to for the query.
  6. In the text field, enter the name of the process id.
  7. Click Save and the filter is applied on the current process instance list.
  8. Click the columns icon (to the right of Bulk Actions) in the upper-right of the process instances list and the process instance variables of the specified process ID will be displayed.
  9. Click the star icon to open the Saved Filters panel.

    In the Saved Filters panel, you can view all the saved advanced filters.

28.6. Aborting a process instance using Business Central

If a process instance becomes obsolete, you can abort the process instance in Business Central.

Procedure

  1. In Business Central, go to MenuManageProcess Instances to view the list of available process instances.
  2. Select the process instance you want to abort from the list.
  3. In the process details page, click the Abort button in the upper-right corner.

28.7. Signaling process instances from Business Central

You can signal a process instance from Business Central.

Prerequisites

  • A project with a process definition has been deployed in Business Central.

Procedure

  1. In Business Central, go to MenuManageProcess Instances.
  2. Locate the required process instance, click the Actions button and select Signal from the drop-down menu.
  3. Fill the following fields:

    • Signal Name: Corresponds to the SignalRef or MessageRef attributes of the signal. This field is required.

      Note

      You can also send a Message event to the process by adding the Message- prefix in front of the MessageRef value.

    • Signal Data: Corresponds to data accompanying the signal. This field is optional.
Note

When using the Business Central user interface, you can only signal Signal intermediate catch events.

28.8. Asynchronous signal events

When several process instances from different process definitions are waiting for the same signal, they are executed sequentially in the same thread. But, if one of those process instances throws a runtime exception, all the other process instances are affected and usually result in a rolled back transaction. To avoid this situation, Red Hat Process Automation Manager supports using asynchronous signals events for:

  • Throwing intermediate signal events
  • End events

28.8.1. Configuring asynchronous signals for intermediate events

Intermediate events drive the flow of a business process. Intermediate events are used to either catch or throw an event during the execution of the business process. An intermediate event handles a particular situation that occurs during process execution. A throwing signal intermediate event produces a signal object based on the defined properties.

You can configure an asynchronous signal for intermediate events in Business Central.

Prerequisites

  • You have created a project in Business Central and it contains at least one business process asset.
  • A project with a process definition has been deployed in Business Central.

Procedure

  1. Open a business process asset.
  2. In the process designer canvas, drag and drop the Intermediate Signal from the left toolbar.
  3. In the upper-right corner, click diagram properties to open the Properties panel.
  4. Expand Data Assignments.
  5. Click the box under the Assignments sub-section. The Task Data I/O dialog box opens.
  6. Click Add next to Data Inputs and Assignments.
  7. Enter a name of the throw event as async in the Name field.
  8. Leave the Data Type and Source fields blank.
  9. Click OK.

It will automatically set the executor service on each session. This ensures that each process instance is signaled in a different transaction.

28.8.2. Configuring asynchronous signals for end events

End events indicate the completion of a business process. All end events, with the exception of the none and terminate end events, are throw events. A throwing signal end event is used to finish a process or sub-process flow. When the execution flow enters the element, the execution flow finishes and produces a signal identified by its SignalRef property.

You can configure an asynchronous signal for end events in Business Central.

Prerequisites

  • You have created a project in Business Central and it contains at least one business process asset.
  • A project with a process definition has been deployed in Business Central.

Procedure

  1. Open a business process asset.
  2. In the process designer canvas, drag and drop the End Signal from the left toolbar.
  3. In the upper-right corner, click diagram properties to open the Properties panel.
  4. Expand Data Assignments.
  5. Click the box under the Assignments sub-section. The Task Data I/O dialog box opens.
  6. Click Add next to Data Inputs and Assignments.
  7. Enter a name of the throw event as async in the Name field.
  8. Leave the Data Type and Source fields blank.
  9. Click OK.

It will automatically set the executor service on each session. This ensures that each process instance is signaled in a different transaction.

28.9. Process instance operations

Process instance administration API exposes the following operations for the process engine and the individual process instance.

  • get process nodes - by process instance id: Returns all nodes, including all embedded sub-processes that exist in the process instance. You must retrieve the nodes from the specified process instance to ensure that the node exists and includes a valid ID so that it can be used by other administration operations.
  • cancel node instance - by process instance id and node instance id: Cancels a node instance within a process instance using the process and node instance IDs.
  • retrigger node instance - by process instance id and node instance id: Re-triggers a node instance by canceling the active node instance and creates a new node instance of the same type using the process and node instance IDs.
  • update timer - by process instance id and timer id: Updates the timer expiration of an active timer based on the time elapsed since the timer was scheduled. For example, if a timer was initially created with delay of one hour and after thirty minutes you set it to update in two hours, it expires in one and a half hours from the time it was updated.

    • delay: The duration after the timer expires.
    • period: The interval between the timer expiration for cycle timers.
    • repeat limit: Limits the expiration for a specified number for cycle timers.
  • update timer relative to current time - by process instance id and timer id: Updates the timer expiration of an active timer based on the current time. For example, if a timer was initially created with delay of one hour and after thirty minutes you set it to update in two hours, it expires in two hours from the time it was updated.
  • list timer instances - by process instance id: Returns all active timers for a specified process instance.
  • trigger node - by process instance id and node id: Triggers any node in a process instance at any time.