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:

1. 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.
2. 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

1. Open a process app in your Web Process Designer (https://<server>:<port>/ProcessCenter)
2. Click the plus sign next to Services and click on External Service.
   
3. Leave Java, REST or Web service selected and click Next.
4. Select your Swagger file and click Next.
   
5. Verify that you see the GetWeather operation and click Next.
   
6. Leave the default settings to create a new server definition and click Finish. Your external service should look like this:
   

Create a Service Flow

1. Click the plus sign next to Services and click on Service Flow.
2. Name your service "Get Weather by City" and click Finish.
3. Drag an Activity onto your diagram and connect it to the Start and End events of your service.
4. On the Implementation property sheet, change the Type of your activity to Service Task.
5. Next to Implementation, click the Select button and choose your external service (OpenWeatherAPI).
6. Next to Operation, choose GetWeather from the drop-down list.
   
7. On the Data Mapping property sheet, click on the automap button next to Input Mapping.
   
8. 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.
   
9. Repeat the previous steps for Output Mapping, but make that variable an output variable.
   
10. 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.

1. Click the debug button (which looks like a scope) at the top-right of your screen and expand the Data panel of the debugger.
   
2. Update the values for q and units. Click the Update All button next to Data to save the values.
   
3. 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.