Friday, May 29, 2020

OIC: How to Find Human Task by Correlation and How to Abort a Parallel Task

This article explains how you can find an instance of a Human Task of process instance in the Oracle Integration Cloud (OIC) without knowing its task number, and how you can use that for example to withdraw a parallel task. You can use the same mechanism for other use cases as well, like to get a specific task instance for a specific process instance in a custom Workspace, etc.

When a Human Task is scheduled in a process there is no out-of-the-box way for the process instance to “know” its task number, because scheduling a task concerns an asynchronous call (so you don’t get an immediate response with the task number). So, although the task number is visible in the process flow trace (as shown below), the process instance itself does not know it.

The sample process below has two parallel tasks. The outcome of Parallel Task 2 is either CONTINUE or DONE. When DONE, Parallel Task 1 must be withdrawn. I will use this as a use case to illustrate how setting some “correlation id” on a task can be used to achieve that. 

For those of you who remember the on-premise BPM Suite may be aware of the Update Task activity you could use to do just that, but such an activity does not exist in OIC. Instead you will have to use the PUT operation of the /ic/api/process/v1/tasks/{id} API. But as you can see this requires an id, which is the task number that you don’t have. To get that you can use the GET operation on /ic/api/process/v1/tasks first. However, there can be many instances of the same process, implying many instances of the Parallel Task 1, so how to find that one you are looking for?

The clue is that you must map some unique key to the task when scheduling Parallel Task 1 so that you can use the GET tasks operation to query tasks on that key. The GET supports a keyword query parameter to do this. You can include the unique key in the task title (which is indexed and used in the search by keyword), but that clutters the task title with some technical id.

Fortunately, Human Tasks have a specific request element you can use to do just that, which is the identificationKey. In the example below I a have mapped some idPrefix that is unique for the process instance, and post-fixed that with “-1” to make the identificationKey unique over all Human Tasks instances.

Now in the Get Task activity I use the GET operation to search tasks by keyword equal to my unique key:

The response is a list of tasks with an “items” element that will contain the (one) task instance I’m interested in. I created the Tasks Business Type for the response of the API. To get the instance of the task I will have to map the “items” of that response to an array of items first, for which I created the TaskItems Business Type, and then map the first item in the array to a Task Business Type I created. So, Tasks -> Task Items -> Task as shown below:

The mapping from the response of the API to my TaskItems is done using a Transformation. As I’m only interested in the task number I have left all other elements out of the TaskItems, except for the state:

To map first element of the TaskItems to a variable of my Task Business Types I also use a Transformation:

Now I have a hold on the task number so I can call the PUT operation to withdraw the task in the Withdraw Task activity:

When I start an instance of this process, and go the Workspace I will see both tasks:

I can then submit the instance of Parallel Task 2 by choosing DONE.

And as a result, the instance of Parallel Task 1 is withdrawn and the process ends:

In a real process application, I would have made this a bit more robust and would check if the Get Tasks returns a task instance and that the state of that task is ASSIGNED. I probably would even create a (reusable) Integration to withdraw any task from any process by identificationKey. But you get the draft.