In a short series of articles, I will discussed some challenges you may face when upgrading Oracle Integration Gen2 (OIC 2) Process (PCS) to Gen3 (OIC 3) Oracle Process Automation (OPA) applications. In this episode 3 I discuss the tasks API challenges. The previous article can be found here.
Disclaimer: The below provides a snapshot at the time of writing. Things may have changed by the time you read it. It is also important to mention that this does not necessarily represent the view of Oracle.
Note: this article has changed on 2024-07-15 by adding the below references.
Specifically for PCS to OPA migration you are also referred to the following:
If you are using any of the Oracle Integration Process Gen2 (called PCS from here on) API’s in your application, than you need to refactor this when going from PCS to OPA.
Firstly, none of OPA API's have the same endpoint as the PCS’s have. The PCS API's start with /ic/api/process/v1 whereas the OPA API's start with /process/api/v1.
To be honest, I have not checked it in detail, but I suspect that only for Dynamic Process the interface (method and request/response) might still be the same if the functionality is still supported. For Structured Process also the interface has changed, so any call to a design or runtime API you may be using in the application must be refactored.
When you have some home-grown CI/CD solution that relies on OIC API's you are in for quite some work to refactor. The same for any custom utility. For example, I have built a utility integration to deactivate a set of activated process application versions in a certain range. Will no longer work for OPA. This article is not covering any of this type of non-runtime related topics, as this series is restricted to PCS to OPA process application upgrade / migration challenges.
Finally, another important change is that (in contrast to PCS), OPA only supports OAuth 2.0 token based authentication (see also OPA Security, Authorization and Authentication).
Normally there are just a few API's used to run a process application and only in a few places, if any. But if you do the typical API’s are:
- The tasks API
- The process instances API
In this article I discuss the tasks API. Next time I will handle the process instances API.
Process Task API
The most common use cases are:
- Get and filter tasks for a user
- Perform action on a task:
- Submit
- Claim
- Reassign
Get User Tasks
Most common PCS usage to get all tasks for a user
GET /ic/api/process/v1/tasks?assignment=MY_AND_GROUP
For OPA this will become
GET /process/api/v1/tasks?assignment=MY_AND_GROUP
Regarding the request, only the endpoint is different, but the response is significantly different. The next table points out a few differences to consider.
As you can see the assignment filter MY or GROUP is the same for PCS and OPA. However, in case of OPA the assignment filters ALL, ADMIN, OWNER (and a few others) are no longer available. Instead, you probably want to use PERSONA (fetches tasks where logged-in user has access to this task due to application permissions).
The typical use case for a user to filter tasks is by title containing some string. For PCS to filter all tasks with "Jack" in the title you would use:
GET on /ic/api/process/v1/tasks?assignment=MY_AND_GROUP&keyword=Jack
This would find tasks with "Jack" in the "title", "shortSummary" or "identificationKey".
For OPA there is no "keyword" query parameter that searches over multiple elements. Instead, you now search on a specific element, typically (but not restricted to) "title", "titleLike", "summary", "summaryLike", "businessKey", "businessKeyLike".
So, in case of OPA you would use:
GET on /process/api/v1/tasks?assignment=MY_AND_GROUP&titleLike=Jack
Note that, when using more than one of these query parameters, it uses AND (and not OR). So, for a PCS custom task list where people are used to be able to search on a substring being present in any of "title", "shortSummary" or "identificationKey", than that is no longer supported.
See also OPA List Tasks API.
Perform Action on Task
For PCS to perform any action on a task you use
PUT on /ic/api/process/v1/tasks/:id
This includes submit, claim, reassign and withdraw.
In case of PCS the :id to use is actually the “number” as is returned by task list response, for example 206294.
In contrast, for OPA you use the “id” (also already present in PCS) which is a string and much longer, for example "7a056b84-3df2-11ef-9e7b-12bc3458bb6a".
For use cases where you pass back the task id as a reference for some front-end application or store it in a database, this probably implies you must make a change to be able to persist it.
To submit a PCS task you can use a payload like this:
{
"action": {
"id": "APPROVE"
}
}
To reassign you would use the same API and a payload like this:
{
"identities": [ {
"id":"john.doe@oracle.com","type":"user"
} ],
"action": {
"id":"REASSIGN", "type":"USER"
}
}
To claim you would use "ACQUIRE" as action id, to withdraw "WITHDRAW" etc.
In case of OPA the action is not in the payload, but a verb in the URI (which previously on restfulapi.net was called a “resource controller” but funny enough appears to have been replaced by a pattern that puts the verb as an "action" element in the request instead, just like PCS had 😂).
For example to submit an OPA task you use:
POST on /process/api/v1/tasks/:id/complete
With the outcome in the payload, like:
{
"outcome": "APPROVE"
}
Likewise, to claim a task:
POST on /process/api/v1/tasks/:id/claim
With optional comment in the payload.
To reassign a task:
POST on /process/api/v1/tasks/:id/reassign
With the user to assign to in the payload, like:
{
"identities": [
{
"id": "b4d83a44319a4edf97be9fc4a242c107",
"type": "USER"
}
]
}
To withdraw a task:
POST on /process/api/v1/tasks/:id/withdraw
With optional “comment” and “isWithdrawChild” flag in the payload.
Previous articles on the subject:
- Part 1 Starting a Process Instance as a Webservice & Consuming SOAP Integrations
- Part 2 Multiple Start Events & Synchronous Process Start
