Blog Header: OPA Alter Flow

OCI Process Automation (OCIPA) 23.04 introduces API support for Alter Flow with UI support planned for a future release. Alter Flow allows process owners and administrators to change the course of a running process instance that has encountered a problem and needs manual intervention. Here we provide the ability to:

  • Move the process instance to another activity in the flow OR
  • Retry the current activity by modifying some of its existing data attributes.

We will investigate each of the above scenarios in more detail, but before we do let’s cover the capabilities of Alter Flow in a bit more detail.

Prerequisites:

  • Alter flow is supported for Structured Processes ONLY
  • Related process instances must NOT be in a terminal state (e.g., Completed/Terminated)
  • To be able to perform the Alter Flow operation you must have MANAGE permission on the process application  

Supported Actions:

  • Change the course of a process instance by moving its execution(token) to another activity*. Here we allow you to:
    • Move the process instance forward to any eligible activity 
    • Move the process instance back to any eligible activity            
  • If a process instance is failing because of a data value or instance attribute, you can change these values and retry running the failed activity.

* Before you can take the above actions the instance must be in Suspended mode.

Now that we have a clear definition of what alter flow is and its capabilities, let’s see how it can be applied by exploring the following use cases:

 

Use Case 1: Move process execution to another activity:

Let’s start by explaining why as a process owner you may need to alter the flow of a specific process instance. Imagine that we have a purchase requisition process where employees get to browse through a catalogue of IT equipment and order item(s). These items form a purchase requisition which is sent to a line manager for approval. Once the manager approves, the Purchase Ordering process is triggered that will order the requested equipment from suppliers. This flow is depicted below:

OPA Alter Flow Process

This process runs fine for some time until one day the line manager gets in contact with the process owner and tells them that they have approved the below request in error:

OPA Approve PO Form

The process instance is now on the createPO subprocess step and is awaiting on confirmation/acceptance from the supplier:

OPA Tracking Audit for Alter Flow

With the scenario set, let’s see what we can do to resolve this issue.

 

Step 1: Suspend the current process instance

First you need to identify the instance id of the process. The easiest way to do this is via the UI:

OPA Get Instance Id

 

Next you will need to suspend the running process, effectively pausing its execution. You can do this via the UI:

OPA Suspend Instance

You can also perform this action by calling the following OPA API with an action of SUSPEND: Perform an Action on Process Instance

 

Step 2: Identify the CURRENT activity of the process instance

We cannot do this step via the UI so here you will need to call the new activities resource under the instance API. This API request will return the current activity id that the process is on. You can see an example request below:

OPA Alter Flow - Get Current Activity

Note: Copy/save the activity id as you will need it subsequently

Step 3: Get the list of TARGET activities that we can move the process to

Here we will query the new target-activities resource under the instance API to see a list of eligible activities that we can move the process to. Notice that here I am using the fetchCompleted=true query parameter. This parameter allows me to see process activities that were already completed. Without this parameter setting, you will only see activities that have not yet taken place.

OPA - Alter Flow select target activity

 Note: Copy/save the target activity id that you want to jump to as you will need it subsequently

Step 4: Perform Alter flow

With the current and target activity id acquired and the process in a SUSPENDED state, we are now ready to perform alter flow. To do this we are going to call the Perform an Action on Process Instance API passing in:

  • The current activity that the process is on (sourceActivityId)
  • The target activity that we want to move the process flow too (destinationActivityId)
  • Reason for performing Alter flow for audit purposes
  • Action (ALTER_FLOW)

OPA - Alter Flow API

The net-result of the above action is that I have now returned the flow back to the manager approval step, where they can now re-take their approval action:

OPA - Result of Alter Flow Action

In the above example I showed how you can go back to a previously completed step because of a scenario where an end-user made a mistake. The same sequence of steps can also be used to meet a variety of other use cases.  For instance, if you have a POST service task that has timeout in OPA but updated the record correctly in the target system, you can use Alter Flow to jump that step to the next action in your process flow.

 

Use Case 2: Correct Payload and Re-submit:

Imagine that an end-user has entered incorrect information in a process form or has selected an option that in turn has led to the failure of a subsequent service task. For example, in our procurement scenario an end-user has selected a supplier who happens not to have any stock for the goods ordered. As such the downstream service call to order the product from that supplier is now failing.

To illustrate this here is an example of a form submitted by an end-user:

OPA - UC2 Form

This form has gone through the approval and is now failing at the Create Purchase Order Service Task Step:

OPA Faulted Service Task

In this scenario the failure is data related and a change of supplier would resolve this issue. Rather than asking the end-user to submit another request, a process owner can alter the payload and resubmit the process instance from the failed step.

We will do this by interacting with the following OPA APIs:

  1. List Process Instance Data Objects
  2. Get a Process Instance Data Object’s Value
  3. Update Data Object of Instance

Let’s go through the end-to-end steps in a bit more detail.

Step 1: Copy the process instance Id of the failed instance

 You can easily do this via our tracking UI:

OPA - Copy instance ID

Step 2: Identify which data object holds the data you want to change.

In this step you will need to identify the object that holds the data that you want to change. You can do this by calling the List Process Instance Data Objects API and locating the data object from the list associated with the process instance.

In my scenario however, the easiest way to do this is to navigate to the input data associations of my failed service task and locate the input object that I need to update (e.g., purchaseItem):

OPA Mapping View

Step 3: Get the current value of the selected data object

Here you will need to make a GET call to the specific data object to extract the current data structure and its values. You can do this by calling the Get a Process Instance Data Object’s Value API. Below is an example of my request:

OPA Get Data Object Current Value

Doing a GET on this endpoint will return the current payload of the data object. This is exactly what we need for the next step, so copy this response.

Step 4: Update the Data Object

The first thing you want to do is stringify the response from the previous step. Once you do this, then you will need to call the same data object API (/data-objects/purchaseItem in my case) but this time with a PUT operation so you can update the value(s) you are interested in changing. You can see an example of this below where I have updated my supplier manually to the correct value:

OPA Update Data Object Value

Step 5: Validate that the object has been updated

Re-run your GET query from step 3 and make sure that the value(s) you changed are reflected against the process instance. In my case you can see that the value has now changed to reflect my intended update of supplier:

OPA Validate Data Object Update

You can now re-try the failed service task either via the UI or the below APIs:

  1. List Process Instance Jobs
  2. Resubmit a Process Instance Job

OPA Re-Try

Doing so should ensure that the process flow proceeds and successfully resolves the data related issue. You can see that in my case the service call now succeeded and so did my overall process instance:

OPA UC2 Resolution after re-try

In this example I demonstrated how you can resolve a service task that failed due to a data related issue; however, it is important to mention that you can use this approach to resolve data related issues with other process activities as well.

 

Summary

As process owners and administrators, it is important to know that we have the OCIPA Alter Flow capabilities at our disposal to change the course of a process instance when something goes wrong. Although today, alter flow is supported only via APIs, it still provides all the functionality we need to manually resolve errored instances.