Starting in Oracle BPM 11.1.1.7 Bundle Patch 3 (Patch id 18072286), Oracle has released the very first version of its BPM REST APIs. A complete list of the available services can be obtained through its WADL file. It can be found via a call to http://yourserver:port/bpm/services/rest/application.wadl. In this example, I used SOAP UI to introspect the definition file and get the list of the operations.
As shown in the picture above, there are four different group of services with several operations. The most interesting services here are tasks and identities. The remaining services, runtime and processes, don’t work yet. If you execute getProcess operation you always get the text “Processes” as result. Something similar happens with getRuntime operation, the response always is an empty JSON object.
In this post I am going to review the authentication method and Tasks service.
Authentication
The REST APIs use basic HTTP authentication, this means that in every request you must include the Authorization header with the credentials.
The Authorization header is constructed as follows:
- Username and password are combined into a string “username:password”
- The resulting string literal is then encoded using the RFC2045-MIME variant of Base64.
- The authorization method and a space i.e. “Basic ” is then put before the encoded string.
Authorization: Basic d2VibG9naWM6b3JhY2xlMTIzNA==
For more information about HTTP Basic Authentication, see RFC1945 section 11.
Tasks service
This service contains various operations that enable to retrieve task data, perform actions and update some parts of the task. I chose a subset of the operations to analyze: getTask, getTaskAttachments, getTaskAttachmentStream, addTaskComment and getTaskForm.
getTask
One of the most useful operation is getTask. In order to call this operation you have to previously know the task id (for testing purposes, you can call getTasks operation to get a task id), that is a numeric value. This operation returns the “skeleton” of the task, including the title, creation date, owner role and available actions as well as the URLs to get the comments, attachments and the history. Here is a sample response of getTask operation:
In the response there is the URL to get the payload: http://soa7.avioconsulting.com:7001/bpm/services/rest/tasks/200461/payload. If you call that URL you will get a “404 Not Found” message. This clearly means that with the current version of the APIs it is not possible to get the task payload. That makes sense since there is not any operation to get or update task payload in the service WADL.
getTaskAttachments and getTaskAttachmentStream
I found an issue in getTaskAttachments operation. If the filename of an attachment contains a blank space, the service fails with the following message: “Illegal character in path at index 84: http:// soa7.avioconsulting.com:7001/bpm/services/rest/tasks/200459/attachments/james cooper.jpg/stream”. In addition, if you want to download the attachment using getTaskAttachmentStream operation, the only thing you get is a file with the text “You do not have permission to view the attachment.”
addTaskComment
I was able to successfully add a comment to a task by using addTaskComment operation. This is an example of the payload that you have to include in the body of the message:
{“commentStr”: “a REST comment”}
This is the only operation to add a comment. There appears no way to add a comment at the process level.
getTaskFrom
Last, I also tried getTaskForm operation with the surprise that the response is a kind of snapshot of the real form, something similar to the body of a BPM notification email.
The bottom line
It is a good step that Oracle has started to consider the importance and the necessity of a REST API because this is the beginning of a path to easily create a custom workspace and to build user task screens using a different technology than ADF. Unfortunately, we will have to wait for another release of these APIs, since it seems there is a limited set of functionality in this version.