BPD Integrations

IBM BPM has the ability to call out from a process to invoke the services of an external service provider running outside of BPM. Unless the processes being built (and even then) are solely composed of Human Services, it is extremely likely that interaction with external applications and systems will be needed. There are a number of technologies that can be used to interact with back-end systems. The following describe some of the more commonly used.

Outbound Web Services

One of the more common ways that a service is exposed is through the technology known as Web Services. Web Services is an encoding of an XML document sent over an HTTP transport. Web Services is an open an industry standard composed of a number of key specifications including SOAP and WSDL.

In the IBPM PD, we can create an IBPM service that encapsulates the invocation of a Web Service. When this IBPM Service is called, the result is a call to the Web Service provider that the IBPM service is configured to call.

To achieve this, select the Implementation category in the Library and in the Create New menu, select Integration Service.

Once selected, a new dialog will appear asking for a name for the new integration service component.

Once completed, an empty service diagram is shown. From the palette, a Web Service Integration primitive can be dragged and dropped onto the canvas and wired into the flow. It is this component that will perform the call to the external Web Service. Notice the icon representing an external integration on the component. Learn this icon so that when you see it again you will know that this service component represents an external call.

Simply placing a Web Service component on the canvas isn't the end of the story. The component doesn't yet know which external service to call. The next step on our journey is to select the Web Service calling component on the canvas and examine its Implementation properties.

Now we need to pause for a moment. Prior to v8.5 of IBM BPM, the mechanism for defining how we call a Web Service was performed one way but from v8.5 onwards, it is performed a very different way. Both styles are fully supported. The two styles are called "From process application settings" and "Provide in-line configuration". The selection is made from the "Discovery Scheme" selection at the top of the implementation section.

The primary difference between the two styles is that in one, the definition of the Web Service is made globally and then any integration service can call it by an alias name while in the other style, the target web service is defined there and then. The new style was introduced to allow a single place to define a Web Service that can then be leveraged throughout the solution. If the web service definition needs to be changed, it can be changed in one place rather than having to hunt through all the project artifacts.

Let us first look at the process application settings style.

From the Process App Settings of our Process Application, we can define a new server definition of type Web Service:

In this section, we can define an external Web Service by supplying the URL to its WSDL. This web service then becomes a "named" entity.

In the Integration Service, when we wish to invoke the Web Service, we can now select it from a pull-down list:

Here is the inline configuration style.

The description of an external Web Service is commonly described in a Web Services Definition Language (WSDL) file. In order for IBPM to know how and where to call a Web Service, we need to make the WSDL document that describes that service known. A common convention is that when a Web Service is published a URL can be supplied which will return the WSDL for that Web Service. This is usually the URL of the web service with the suffix ?WSDL added.

For example, if a service is available at

http://localhost:9080/MyProject/MyWebService

then sending a request to

http://localhost:9080/MyProject/MyWebService?WSDL

will return the WSDL description for that service. In the WSDL URI: entry field in the editor, the URL pointer to the WSDL can be entered. One entered, the Discover button can be pressed to dynamically retrieve the WSDL from the remote server and have IBPM parse the content to determine what operations are available and what data types are expected for those operations.

Note: If the service is provided by IBPM Advanced SCA Exports, you can not use this mechanism to properly discover the artifacts. Fortunately, there is a solution. Open a web browser and enter the URL of the service description as the page to load. You will find that the WSDL returned has a new URL in the address bar of the browser.

For example:

Entering:

http://localhost:9080/SampleWebServiceProviderWeb/sca/MyWebService

resulted in a redirect to:

http://localhost:9080/SampleWebServiceProviderWeb/sca/MyWebService/WEB-INF/wsdl/SampleWebServiceProvider_MyWebService.wsdl

Using this URL will work with IBPM|

When the Discover button is pressed, a new dialog is presented. This allows you to enter a username/password combination if the access to the target URL is restricted.

A button called View can be used to open a browser at the defined URL so that the WSDL file can be viewed in its source form.

Once this step has been completed, the development tooling is now aware of all the operations that are available at the target service. From the Operations: pull-down, select the operation you wish to call. Also notice that the endpoint information for the service has now been determined.

The next step is to generate the data types (if any) that are expected for the operations you wish to call. Click on the Generate Types button to create data type definitions for the data types used as inputs and outputs from the service. A dialog is presented to allow you to create some or all of the data types. Typically you would only need to select the operations that you plan to use and only data types associated with those operations are created.

A list of the data types to be created or mapped is shown.

A second dialog is produced before completion.

Once done, all that is left is to map variables to the data to be passed in and returned from the service call.

The names of the formal parameters are shown. If one hovers a mouse over these names, the associated data types can also be seen:

If the operation has multiple input and output parameters, each of the input and output parameters can be individually mapped:

If the service being called throws an exception, this can be caught by adding a Catch handler to the service:

The target of the Web Service request is defined in the Endpoint Address URL box. By default, it has the value defined in the WSDL file. By checking the Override Endpoint Address check box, a new URL value can be entered and that will be the target of the request. The URL string can be retrieved from a variable's value with the <#=variable name #> technique.

A good service for testing Web Service interactions can be found here. This public web service returns weather forecast data for US cities.

It is important to note that 7.5 and prior releases of the product only support SOAP 1.1 as the transport protocol. Putting this another way, SOAP 1.2 is not yet supported. If SOAP 1.2 is required, consider using the IBM BPM Advanced edition.

There are times when the Web Service target is defined over an HTTPS protocol as opposed to an HTTP protocol. This means that SSL certificate exchanges need to also occur. Fortunately, if a problem is encountered, IBM BPM generates this extremely useful guidance message:

[10/23/12 15:04:07:411 CDT] 00000007 SystemOut O CWPKI0428I:

The signer might need to be added to the local trust store. You can use the Retrieve from port option in the administrative console to retrieve the certificate and resolve the problem. If you determine that the request is trusted, complete the following steps:

If the instructions contained within this message are followed, the problems with SSL will be resolved.

See also:

Setting up security for outbound Web Services

It is often the case that a Web Service that is being called needs to know the identity of the caller in order to authorize the request to be performed. Settings in the Web Service integration component can be used to provide such information:

There may be a potential "bug" in this area. Setting security parameters here appeared to be ignored unless security was also set in the Implementation screen for accessing the raw wsdl.

Inbound Web Services

An inbound Web Service is the notion that a IBPM solution can "advertise" or "expose" itself as a Web Service allowing it to be called from an external Web Service caller or client. In a typical Web Service, there can be multiple "operations" defined on a single service. IBPM's mapping to the concept of Web Services is that when a web service definition is made, one or more operations may be defined. For each operation defined on that Web Service, an IBPM Service definition is mapped to it.

This is illustrated in the following diagram. There we see a IBPM Web Service definition with three operations defined upon it. For each operation, there is a reference to a corresponding IBPM Service definition.

To construct an inbound Web Service definition, the selection can be made from the Implementation category and selecting Web Service.

2017 11 30 12 24 13

A dialog will appear allowing us to name the Web Service definition:

2017 11 30 12 32 41

Once completed, the properties of the Web Service definition can be completed.

2017 11 30 12 35 08

In the Operations section, press Add for each operation that is desired to be exposed on the Web Service. For each operation added, an IBPM Service needs to be associated with it. This implies that the service must be created before adding the operation. When deployed, a call to a named operation will result in the invocation of the corresponding IBPM Service.

Any parameters defined as input on the IBPM Service will be exposed as parameters on the Web Service call. Any parameters defined as output on the IBPM Service will be returned as parameters on the Web Service call.

Take special note of the WSDL URI in the behavior section. This is the Web URL that can be used to retrieve the WSDL file that describes the exposed Web Service.

Testing an Inbound Web Service with soapUI

One of the most popular Web Service testing tools on the Internet is called soapUI. It can be found at the following web address:

http://www.soapui.org/

This tool/package can be used to exercise calls to IBPM that are exposed as Web Services. The following is the recipe used to achieve this task.

Launch the soapUI tool and select File > New soapUI Project

Give the new project a name and click OK to complete

Right click the new project and select Add WSDL

In the WSDL location text box, enter the URL for the WSDL describing the Web Service. This can be obtained from the IBPM PD Web Service definition in the "Behavior" section.

Clicking on this URL opens a Web Page to the WSDL content. The URL can then be copied from the address bar of the newly opened browser.

Once entered, soapUI will retrieve the WSDL description and parse it. From the WSDL, a sample request message will be built. This request message is a SOAP message that, if sent to IBPM, will cause the service to execute. Drilling down into the request will show the details of the SOAP message which can be modified.

Pressing the submit button (green arrow) will send the SOAP message to IBPM for processing. Multiple soap Request messages can be created representing different tests. The project can be saved for later replay of these requests.

If the service associated with the Web Service definition is changed, the soapUI WSDL will have to be reloaded before testing continues otherwise an out-of-date WSDL will be used with unpredictable results.

The Update Definition menu option will re-load the WSDL:

Invoking a BPD exposed as a Web Service

It is not uncommon to want to expose a BPD to be invoked as a Web Service. To achieve this, a few steps are involved. Working backwards from the BPD, it must first be defined as being started by Start Message Event node. Here is an example BPD:

Associated with a Message Start Event node is a UCA. A UCA acts as the "trigger" to the Start Message Event. Before we can define a UCA, we need a General Service that is to be associated with the UCA. The result (output) of the General Service is the "value" passed by the UCA to its associated partner which in this case will be the Start Message Event Node in the BPD.

A suitable General Service may just pass the input to the output. For example:

Finally, a Web Service definition is also associated with a second General Service. It is this General Service that will be called when the Web Service is invoked. This General Service should cause the invocation of the UCA. A suitable General Service may be:

So, putting it all together we have:

This looks pretty scary so it won't do us any harm to speak about it some more. From the bottom left, we have a Web Service definition which refers to a General Service. This General Service includes an invocation of a UCA. The UCA has to have an associated General Service (because that is the rules) that knows how to build the data to be passed onwards by the UCA. The UCA is used as the trigger to the Start Message Event in the BPD.

Invoking an IBPM Web Service from a Java POJO

The following is a recipe for building a Java application that calls an exposed IBPM Web Service. Although not strictly related just to IBPM, it is useful to see the steps here to see how simple it is and for future reference. The sample here utilizes IBM's RAD/WID for the Java and Web Service client development.

Create a new Java Project to host the Java code that will call the Web Service.

Using the File > New, start a wizard for creating a new Web Service Client:

At the conclusion of this step, a series of Java classes will have been created conforming to the JAX-WS specification. In these classes will be one named for the service.

Create an instance of that class and then use the getter to retrieve the SOAP object. That object has methods on it corresponding to the operations on the service.

A test caller can then be written:

import win7\_x64.\_19086.teamworks.webservices.tests.myinboundwebservice.MyInboundWebService;
 public class Main {
 public static void main(String[] args) {
 MyInboundWebService miws = new MyInboundWebService();
 miws.getMyInboundWebServiceSoap().op1("Hello");
 }
 }

Web Services and data types

When we talk about passing data to and from a Web Service, we are implicitly talking about converting data types from one format to another. In IBPM, we have simple data types and complex data types. In Web Services, we have similar concepts but the data types are described by XML Schema Definitions (XSDs). The question now raised is just how compatible are these two environments? Are there data types in IBPM that don't map to XSDs and/or visa versa. In the following section we work through the different permutations of data of interest to us and execute tests against Web Services that expose those types and see how IBPM handles them.

In these tests, we have a variety of back-end Web Service that we wish to call from IBPM. Each Web Service differs from the other by the data types it returns.

Simple Data Type

Interface: ISimple

Endpoint: http://localhost:9080/WLEDataTypeTestsWeb/sca/ISimpleExport

Generated data types:

Results

Conclusion

No issues at all with a simple data type. Surprised to see "String" being offered as a data type mapping as it seems to say that will create a new data type … but it appears that the table shows mappings as well as new types to be created.

Complex Data Type

Interface: IComplex

Endpoint: http://localhost:9080/WLEDataTypeTestsWeb/sca/IComplexExport

Generated data types:

Results:

Conclusion:

No issues. Complex data type created as expected.

Nested Complex Data Type

Interface: INestedComplex

Endpoint: http://localhost:9080/WLEDataTypeTestsWeb/sca/INestedComplexExport