Introduction
In IBM BPM 8.5.7, IBM introduced a new feature in the Web-Based Process Designer called an External Service. In addition to calling Java or Web Services like previous versions of IBM BPM, External Services can invoke REST services as well. I was excited to learn about this new feature until I realized that this new feature only worked if your REST service had a Swagger file defined. As it turns out, most API developers do not take the time to create a Swagger file (basically the REST equivalent of a WSDL file), which made me think this new feature was mostly useless. I was wrong.
As it turns out, you can create a Swagger file for any existing REST API. There may be other options out there, but RESTUnited is an excellent resource for building Swagger files.
Example
In this example, we will build an integration service in IBM BPM that calls the OpenWeatherMap API.
Create an OpenWeatherMap API Key
The first thing you'll need to do is create an API key with OpenWeatherMap. Go to https://openweathermap.org/ and create a free account. It takes about 10 minutes for your API key to be activated.
Create Your Swagger File
If you want to skip this step, feel free to use my Swagger file, which I've attached to this article.
As it turns out, someone else seemed to have the same idea when working with K2. I followed this step-by-step walk-through to create my Swagger file. The only changes I had to make were:
- In step 2, I had to set Authentication to Basic, rather than None. Although the REST service doesn't use Basic Authentication, IBM BPM won't accept a Swagger file without any authentication type set.
- I added a third parameter in step 2 for "units". This is an optional parameter in the OpenWeaherMap API, which allows you to set the units to "imperial" or "metric". Without this parameter I was getting some strange values.
Create an External Service
- Open a process app in your Web Process Designer (https://<server>:<port>/ProcessCenter)
- Click the plus sign next to Services and click on External Service.
- Leave Java, REST or Web service selected and click Next.
- Select your Swagger file and click Next.
- Verify that you see the GetWeather operation and click Next.
- Leave the default settings to create a new server definition and click Finish. Your external service should look like this:
Create a Service Flow
- Click the plus sign next to Services and click on Service Flow.
- Name your service "Get Weather by City" and click Finish.
- Drag an Activity onto your diagram and connect it to the Start and End events of your service.
- On the Implementation property sheet, change the Type of your activity to Service Task.
- Next to Implementation, click the Select button and choose your external service (OpenWeatherAPI).
- Next to Operation, choose GetWeather from the drop-down list.
- On the Data Mapping property sheet, click on the automap button next to Input Mapping.
- Choose which variables should be used as input variables on your service. I recommend q (which represents the city) and units. This will allow your service to be called by other BPM services.
- Repeat the previous steps for Output Mapping, but make that variable an output variable.
- Update your AppID variable with your API key from OpenWeatherMap. In the real world, we'd likely make this an Environment Variable, but for this example, I'm hard coding mine.
Test your Service Flow
Now is a perfect time to add a shameless pitch for Brazos Tester. If you have Brazos Tester installed, you can test your new service elegantly and automatically. Click here for more details.
If you don't have access to Brazos Tester, you can test your service using the service debugger.
- Click the debug button (which looks like a scope) at the top-right of your screen and expand the Data panel of the debugger.
- Update the values for q and units. Click the Update All button next to Data to save the values.
- Click the Step Over button and verify that the GetWeather_200 variable updated with the current weather for the city you entered.
Thoughts and Observations
- When I demo this, I usually go on to build a coach that calls the integration.
- This same approach works with web services.
- When you create your External Service, variables are automatically created based on the signature of your REST operation(s). There is no warning about this, but I noticed some nice features. Anything that is generated automatically is marked as Discovered so you can distinguish those variables from your process variables.
On top of that, these discovered variables are read-only and they appear to be inherently linked with the External Service that created them. Look what happens when I try to move my External Service into a toolkit:
Those discovered variables are automatically selected and cannot be deselected.
Comments
4 comments
CWTBG0019E: Unexpected exception during execution. Exception information: 'com.lombardisoftware.component.common.workflow.WorkflowProcessItemException: java.lang.RuntimeException: java.net.UnknownHostException: api.openweathermap.org'.
After updating App ID variable with mu App Key it seems service is giving an above error
Hi Prateek -
I was able to run the service successfully in my environment just now. If you are getting that error, there must be something preventing your IBM BAW server for accessing the URL. Perhaps there is a firewall or proxy issue?
Hello,
Do you have an example of how to generate the Swagger for the BPM Rest APIs?
Hi Ramses,
If you're using the new generation REST API, you actually don't have to generate Swagger files. They're available to download in the product at these two URLs:
https://[server]:[port]/bpm/docs, which can be explored at this URL: https://[server]:[port]/bpm/explorer/
https://[server]:[port]/ops/docs, which can be explored at this URL: https://[server]:[port]/bpm/explorer/?url=/ops/docs
If you're using the previous REST API, you should be able to generate one using the steps I described in the section above called "Create Your Swagger File".
Hope that helps!
Gordon
Please sign in to leave a comment.