IBM API Management and IBM Business Process Manager
IBM Business Process Manager provides a very comprehensive selection of REST interfaces which can be exposed outside of the enterprise boundary using IBM API Management. These REST interfaces can be used to query, start, participate in and modify processes, tasks and other BPM information. In this article I will look at how to take the most basic requirement - starting a business process - and creating an API.
Why Expose BPM as APIs?
IBM API Management provides a facility to expose existing business function within your enterprise to exploit opportunities and grow your business in new markets, channels and developer communities that you might not have previously had access to. It also allows you to manage and monitor that community of developers and the applications that they create.
It may be that some of your business processes are ideal candidates for these developers to use within their applications but where they are not forced to explicitly log into and use the backend BPM servers. In this instance we are showing how an existing business process can be easily turned into an API which would allow a developer a simple way to start a process using their own preferred tools and technologies.
It would also be useful in cases where you might wish to expose the progress of long running business processes to partners, customers and so on so that they can do self service monitoring.
Assumptions
This post assumines that you're familiar with IBM BPM and how to use it, that you've registered for IBM API Management and that you have a BPM server that is accessible from the cloud based API Management servers.
Find a Process and Its Input Message
We need to start by finding the details of the process that we wish to invoke. In particular we need to know the structure of the input message as we will use the BPM REST Tester to find the IDs for the BPD and Process later.
Open your Process Designer and open the business process that you wish to use and find the input variable. You'll need to be able to provide a JSON representation of the message to use with the API.
Discover the REST Interface to a Process
To be able to invoke the BPM process we need to find the BPD and Process ID's. IBM BPM provides a highly useful REST API Tester which can be accessed at:
http://<hostname>:<port>/bpmrest-ui/BPMRestAPITester/index.jsp
This is an invaluable resource for using REST to interact with IBM BPM and all standard interfaces are provided here. In our case we are simply going to find the exposed processes and then the interface to start our process.
Open the "Process API" folder and select "Exposed Processes" and then click the "Execute" button.
This brings back a list of all BPM processes that have been exposed so that they can be invoked externally. You need the "itemID" and "processAppID".
Now select the "Start Process" API in the REST API Tester.
Copy the "itemID" into "BPD ID" and "processAppID" into "Process Application ID". Finally add a JSON representation of the process input message to "Parameters" and click "Execute".
When the call returns you will see detailed information about the call to start the process and the current state of the process. For the next step however you need to copy the request URI into a text editor.
Define Your API
We now have all the information that we need to create our API using IBM API Management. Log into the IBM API Management WebAPI Builder at:
https://webapi.castiron.com/webapibuilder
Create a new API definition. A single API can have multiple resources, at this point we are simply creating the top level of the API. Add a name of the API, a context path and a description and click "Add".
Click on the newly created API definition to edit the API.
Each API requires at least one Entitlement. This specifies a policy for the number of times that a consumer can invoke a given API per minute. It also can use used to require approval before an API can be used and whether an application secret code is required to invoke the API.
Click on the "Entitlements" tab and create a sample entitlement.
Return to the "Resource Definition" tab.
The "Start Process" REST API uses a POST method. The URI for the resource needs to match the parameters for the BPM REST call.
process?action=start&bpdId=bid&processAppId=pid¶ms=prms&parts=all
This means you can simplify or change the path of the API from the original URI up until you hit the first parameter. After that you need to keep your URI path the same as in the original service.
Click "Add" to create the new resource.
Click on the link for the new resource to edit it.
We can create a simple proxy to invoke the BPM process. Select the "Proxy" checkbox.
Enter the address of the BPM REST URL but only to the point of the first parameter. IBM API Management appends the parameters to this URL when invoking the API resource.
http://<hostname>:<port>/rest/bpm/wle/v1/process
Add descriptions for the 5 parameters.
In the "Request Headers" section add an "Authorization" header as we will need to be able to pass user credentials into BPM to invoke the process.
Return to the main API page and click the "Activate" icon.
Move to the "Test" tab and select the POST resource from the pulldown and the "Test Application".
- action: start
- bpdId: paste in the BPD ID from earlier
- processAppId: paste in the Process Application ID from earlier.
- params: paste in the text of the parameters from the output of the REST API tester
- parts: all
Paste a basic authorisation header into the "Authorisation" header (if you don't know how to create a basic authorisation header there are instructions for one way of doing it at the bottom of this page).
Finally click "Test".
You will see that the process has been successfully invoked.
In the Response Body you can see detailed information about the process invocation and its current state.
Congratulations! You've created an API to invoke an IBM BPM process using IBM API Management!
Generating a Basic Authorisation Header
If you don't already have a to to create a basic authorisation header you can use a tool like "REST Console" in Chrome to create one for you.
Open REST Console, find the "Authorisation" section and click "Basic Auth".
Enter your username and password and click "Set Header".
This then creates a basic authorisation header. This can be copied and pasted (including the word "Basic" at the start) into the IBM API Management tester.
