Integrate external services with IBM Business Process Manager Standard or Express applications
IBM Business Process Manager is a comprehensive BPM platform offering the visibility and insight to manage business processes. It scales smoothly and easily from an initial project to a full enterprise-wide program. Business Process Manager harnesses in a simple environment to break down silos and better meet customer needs. It has three editions that provide different levels of business management capability:
- IBM Business Process Manager Advanced, which provides visibility and management of business processes with support for high-volume automation and extensive system integration.
- IBM Business Process Manager Standard, which is ideal for multi-project improvement programs with high business involvement and a focus on workflow and productivity.
- IBM Business Process Manager Express, which is ideal for that initial process improvement project that requires business involvement and a quick turnaround.
There are two ways for Business Process Manager products to integrate with external services, one is the component bindings way, the other is the out-of-box connectors way. The component bindings method enables the system to invoke external systems with various bindings such as SCA bindings, EJB bindings, HTTP bindings, JMS bindings, and so on. This is the most powerful method, but it is only possible with Business Process Manager Advanced. The out-of-box connectors method provides basic integration capabilities with external systems. It's simpler than the bindings way and can be used for all Business Process Manager editions. This article will focus on how to use the out-of-box connectors method to integrate with external systems.
The IBM Process Designer is the authoring tool used to enable integration with out-of-box connectors. It provides capabilities for lifecycle management of business processes, and also provides a set of out-of-box connectors to integrate with external systems. There are four different ways to integrate with external systems using Process Designer:
- Java integration
- Web service integration
- ILOG integration
- Enterprise Content Management (ECM) integration
Integration services are reusable across processes because they are defined as services. These integration services have well-defined inputs, outputs and advertised behavior. They can be reused via toolkits shared across process applications. This article introduces these integration capabilities and how they integrates with external systems, along with some best practices for invoking external services.
Java integration calls methods from a Java class and interfaces with most third-party Java APIs, thus supporting a variety of integration scenarios and giving you access to Java features, including published Java libraries and APIs. You should build a Java integration service when you want to integrate with an external system to retrieve, update, or insert data in order to complete a task.
In this section, we'll use a sample to illustrate how to use Java integration to call a method from a Java class. For the purposes of our sample, let's assume we have a JAR file containing a Java method that can output “Hello World.” We'll import that file into Process Designer, then use the Java Integration component to invoke the Java method, as described in detail in this section.
Import external files
External files are images, style sheets, JAR files, or other assets that are part of Business Process Manager implementation, but developed outside of Business Process Manager. You can add these external files to your process application or toolkit in the Designer view so that all project assets are included in the Process Center repository. Adding these files to your process application ensures that all required assets are available and installed when your project is ready for testing or production.
Before adding managed files, be aware of the following requirements:
- You must have write access to the current process application or toolkit to add external files as assets.
- The files that you add cannot be larger than 100MB.
You can add Hello World.jar to the process application by doing the following:
- From the project tree, select the + icon next to Files and
select Server File, as shown in Figure 1.
Figure 1. Create new server file
- In the Server File window, click Browse and select HelloWorld.jar in your file system. HelloWorld.jar is now part of your process application. When you deploy this process application, this server file will be deployed as part of the application.
- Save the server file.
Figure 2. Add new server file in Process Designer
Create an integration service and add a Java Integration component
To create an integration service, do the following:
- From the project tree, select Implementation, click the + icon, then click Integration Service.
- Specify the name as
Hello World - java integration comp, as shown in Figure 3, and click Finish.
Figure 3. Create integration service
- To diagram the integration, click the Diagram tab and drag the Java
Integration component onto the canvas, then change its name to
Hello World – JICand wire the components together, as shown in Figure 4.
Figure 4. Add Java Integration component
- To configure the Java Integration component to invoke a Java method, click Hello World - JIC.
- Under Properties, click the Definition tab, and under
Discovery, set the Java Class by doing the
following, as shown in Figure 5:
- Click Select and select the class.
- Select HelloWorld(helloworld.HelloWorld).
- Select the method String helloWorldWithName(String) from the list.
Figure 5. Configure Java method
- To set up the service variables, click the Variables tab, and add an
nameof type string, and set the default value to
John Doe, as shown in Figure 6. Add an output variable
resultof type string.
Figure 6. Set up variables
- Define the data mapping for HelloWorld – JIC. Click
HelloWorld - JIC. Under
Properties, click the Data Mapping tab. To set
the Input Mapping, for parameter 1, click to select the variable
tw.local.name, as shown in Figure 7. Do the same
to set the Return Value.
Figure 7. Define data mapping
- To test the integration, click the debug icon in Process Designer,
click Step, as shown in Figure 8, several times until you see a
message saying "The service has finished."
Figure 8. Debug integration service
Web service integration
To invoke a remote web service, you can use the outbound web service integration. First you need to create an integration service in Process Designer and use the Web Service Integration component in the service. The Web Service Integration component is able to discover the web service. It hides the complexity of the underlying WSDL, SOAP request, and SOAP response, and can also convert inputs into the appropriate XML and outputs into the appropriate Business Process Manager variables.
There are two different ways to call a web service using the Web Service Integration component in integration service: using WebSphere Service Registry and Repository UDDI or by specifying the WSDL URI directly.
Specify the WSDL URI directly
In this section, we'll use a sample to illustrate how to directly specify the URI to implement web service integration. In this example, we have a text message sending service exposed at http://ws.cdyne.com/smsWS/SMS.asmx?wsdl. We'll use the Web Service Integration component to invoke it to send a text message to a receiver by directly specifying the WSDL URI by doing the following:
- Create an integration service and set the name to
Send Text Message.
- Drag a Server Script and a Web Service Integration onto the canvas,
and then wire the components together, as shown in Figure 9.
Figure 9. Create an integration service with the Web Service Integration component
- Configure the web service as follows:
- Click on the Web Service Integration component, and name the
send text message.
- Click the Implementation tab. Under
Discovery, enter the WSDL URI as
http://ws.cdyne.com/smsWS/SMS.asmx?wsdl, as shown in Figure 10.
Figure 10. Specify the WSDL URI for the web service integration
- Click Discover next to View, In the Discover wizard, leave the defaults, and click Discover.
- For Operations, select
SendSMSBasic(string, string, string), as
shown in Figure 11.
Figure 11. Select web service operation
- Click Generate Types next to
Discover, then click Next, as shown in
Figure 12. This generates Business Process Manager
representations of the data types. Once the data types are
generated, they can be used like any other Business Process
Manager data types.
Figure 12. Generate types
- Click the Header tab. Note the input and output parameters of
the web service. In the Parameter Details
section, you could set default values for the parameter, but
it is a best practice to use a Server Script component to set
these values and make them easily visible for purposes of of
documentation and debugging.
Figure 13. Header of web service integration
- Click the Data Mapping tab, and click the auto-map icon to set the input mapping. Check all the input
variables and click OK, as shown in Figure 14. Do the
same to auto-map the output variables.
Figure 14. Auto-map the input variables
- Click on the Web Service Integration component, and name the component
- Next , set the default values for all your variables. On the
Variables tab, click each private variable and check Has
Default for Default Value, as shown in Figure 15. This
isn't important for the simple types, but it is very important for the
complex types because it saves a lot of initialization code.
Figure 15. Set default value for parameters
- To set the values for the server script, go to the Diagram tab and
click the Server Script component. Call it
set variables. On the Implementation tab, set values for the phone number, a short message to send, and the license key, as shown in Figure 16.
Figure 16. Define server script values
- Save the integration service.
- Test the integration service by clicking Debug, the Step repeatedly until you see a message saying: “The service has finished.” Within 30 seconds or so, you should get the text message.
Call the web service using WebSphere Service Registry and Repository UDDI
- To use the WebSphere Service Registry and Repository UDDI explorer,
click Browse in the implementation properties for a Web Service
Integration component as shown in Figure 17:
Figure 17. Browse to WSDL in repository
- When the wizard starts, type in the WebSphere Service Registry and Repository UDDI URL. The wizard stores the registry URLs that you type in, enabling you to select previously used URLs from the list.
- Click Next.
- In the Name field, type a partial or complete Web service name. You can use the % symbol as a wildcard to return a list of all services in the UDDI registry.
- Click Search Services to generate a list of available web services for the selected registry, then select a web service, and click Next. The wizard displays the web service details, including the service key and the WSDL URI.
- If you're satisfied with the WSDL URI, the service key, and the implementation, click Finish. Process Designer populates the WSDL URI field in the implementation properties for the Web Service Integration component.
- Click Discover to discover the WSDL.
- Repeat the steps from 3d-7 in the Specify the WSDL URI directly.
How to call a secured web service
Business Process Manager supports the following runtime authentication mechanisms that do not require client certificates:
- Protected WSDL: For protected WSDL authentication, you can
simply check the Protected WSDL check box in the implementation
properties for the Web Service Integration component, then provide the
user name and password, as shown in Figure 18.
Figure 18. Protected WSDL authentication
- HTTP basic authentication: HTTP basic authentication requires a
user name and password, as shown in Figure 19. Business Process
Manager never stores the password in plain text in its database or
export files, and no plain text passwords are required in
Figure 19. HTTP authentication
- UsernameToken authentication: UsernameToken authentication is
an alternative to using a certificate on the client. If you select
either of the UsernameToken options, the Sign
request option is disabled. If you select Sign
request, the UsernameToken option is
disabled. The Business Process Manager implementation of this standard
wsu:Created. This is compatible with the behavior of the Microsoft® .NET® Web Services Enhancements (WSE) 2.0 Toolkit when using UsernameToken digest authentication.
Best practices for web service integration
Following are some best practices for using the Web Service Integration component in Process Designer:
- If you're using WebSphere Service Registry and Repository to access
the web service, the WebSphere Application Server certificate of the
WebSphere Service Registry and Repository server needs to be imported
to the Business Process Manager server as follows, so that Process
Designer can access the WebSphere Service Registry and Repository
- Log in to the Process Center WebSphere Application Server administrative console with administrative permission.
- Navigate to the security signer certificates, as shown in
Figure 20. Signer certificates
- Click Retrieve from port, and specify the WebSphere
Service Registry and Repository Server information in the
General Properties dialog, as shown in Figure 21.
Figure 21. Retrieve signer information in administrative console
- Click Retrieve signer information to get the WebSphere Service Registry and Repository server information.
- Click Apply to save the information to the master configuration.
- For the Web Service Integration component, in the Endpoint Address URL field in the Implementation properties, specify a URL that points to a different instance of the Web service.
In order to manage business rules more effectively, Process Designer has a service called JRules Decision Service to invoke the rule applications deployed on an ILOG JRules Rule Execution Server. Process Designer accesses a hosted transparent decision service of the rule set like a web service. In this section, we'll describe how to use the JRules Decision Service to connect to a Rule Execution Server and invoke the rule applications and rule sets on that server, and describe some best practices.
Establish the connection and build the service
Before using the JRules Decision Service to invoke a JRules ruleset, the connection between Process Center server and JRules server must be able to be established successfully. If the Rule Execution Server is on WebSphere Application Server, you must do the same security configuration as the first best practice of web service integration.
The following steps describe how to build a decision service that includes a JRules Decision Service component in Process Designer:
- Create ILOG specific environment variables as follows:
- click the Setup category and double-click Environment Variables
- In the Environment Variable editor, click Add to add a new variable.
- Click the newly added row in the table, enter a Key,
select ILOG Rules Server for Type, and
http://188.8.131.52:9081for Default Value, as shown in the Figure 22.
Figure 22. Set the environment variables
- Create a decision service, and then drag a JRules Decision Service
component from the palette to the service diagram. Use sequence lines
to connect the JRules Decision Service component to the Start and End
events, as shown in Figure 23.
Figure 23. Create Decision Service
- Connect to the Rule Execution Server. When connecting to different
Rule Execution Servers, Process Designer will show different
- For a secure connection, a Rule Execution Server running on WebSphere Application Server, the host name and port of the server, as well as the SOAP port must be provided. The secure connection enables you to browse the rule applications and rulesets available on that Rule Execution Server and choose the rule applications and sets that you want.
- If you connect to a Rule Execution Server running on WebSphere Application Server, and you are not able to provide a SOAP port, you cannot browse the rule applications and rulesets. In this case, you can enter the names of rule applications and rulesets manually.
- If you connect to a Rule Execution Server that is running on an application server other that WebSphere, you cannot browse the rule applications and rulesets available on that Rule Execution Server. You must manually enter the names.
Select the JRules Decision Service component and click Implementation in the properties. In the Discovery section, select the server whose options originate from the environment variables of the current process application and dependent toolkits, specify the SOAP port, and then click Connect, as shown in Figure 24. Rule apps and rulesets will be displayed in the Rule section. In this example, it is unnecessary to enter a user name and password because the signer certificate has been imported from the Rule Execution Server.
Figure 24. Connect to the Rule Execution Server
Select rule application and its version, and then select the ruleset and its version from the dropdown list.
- Click Generate Types. In the Generate Types wizard,
click Next, then Finish, as shown in Figure 25.
Figure 25. Generate types
- Click Data Mapping in the properties, then click the auto-map
icon in upper right corner of the Input Mapping section. The
Create variables for auto-mapping dialog opens, as shown in
Figure 26, showing the private variables needed for input parameters
from the selected Rule App. Check each variable that you want to
create in your decision service and then click OK.
Figure 26. Auto-map variables
- Repeat the same steps for output parameters.
- To debug, go to the Variables tab and set the default value for the
created input variables. In our example, we'll set 50 as the credit
score, as shown in Figure 27, and then click the debug icon to debug
the decision service.
Figure 27. Debug decision service
Figure 27 shows that creditCheckResponse is returned from the Rule Execution Server. Listing 1 shows the detailed content of creditCheckResponse. You can see that the risk is considered to be high when the credit score is 50.
Listing 1. Content of web service response
<object type=“creditCheckResponse”> <property name=”CreditRiskResponse” type=”CreditRiskResponse”> <property name=”risk” type=”String”>high</property> </property> </object>
Best practices for ILOG integration
Following are some best practices for using a JRules decision service in Process Designer.
- When the Rule Execution Server address changes or you want to invoke the same rule app that is deployed on another Rule Execution Server, you must repeat the steps in the previous section to make sure that Process Designer establishes a new connection with the correct Rule Execution Server. The decision service won't work if you only change the value of the environment variables.
- You can invoke rulesets using the Web Service Integration component
- Get the WSDL URI of the ruleset you want to invoke.
- Create an integration service with the Web Service Integration component, and use the WSDL URI of the ruleset as the web service's WSDL URI.
Enterprise Content Management integration
Process Designer supports multiple ECM integrations along with its existing internal document repository. It can support content managers that ship with IBM Content Integrator (ICI), such as FileNet P8 and CM8. Process Designer gets document information using an SOA web service of IBM Content Integrator.
Document Attachment and Document Viewer widgets are used to view documents from Content Manager within a Coach. The Document Viewer widget can be configured against a specific document or associated with a Document Attachment widget. The Document Attachment and Document Viewer widgets support filtering of listed documents using simple SQL-like conditions. In this section, we'll look at an example of how to manage documents from Content Manager in a Coach.
Create a Coach to manage documents from Content Manager
The following steps describe how to establish a Coach that includes Document Attachment and Document Viewer widgets to manage documents from Content Manager.
- Create ECM specific environment variables as follows:
- Select Environment Variables.
- In the Environment Variable editor, click Add to add a new variable,
- Click the newly added row in the table, and specify a
Key, select ICI web service URL as the
Type, and specify
http://auckland.lombardiqa.com:9080/vbr_soafor the Default Value, as shown in Figure 28.
Figure 28. Create ECM-specific environment variables
- Repeat the previous steps to add an environment variable of
ICI Connector Name. The ICI web service URL is the
SOA SPI address in the form:
http://<host>:<port>/vbr_soa”and the ICI Connector Name is the name of the configured ICI Repository Connector.
- Create a human service, then drag a Coach from the palette to the
service diagram. Use sequence lines to connect the Coach to the Start
and End events, as shown in Figure 29.
Figure 29. Create a human service
- To add a document attachment to the Coach, click the Coaches tab and
drag a Document Attachment control from the palette onto the design
area. While the Document Attachment control is selected, click
Document Attachment in the properties if not
already selected. In the Behavior section, select IBM
Content Integrator as the Connection Type, as shown in
Figure 30. Create ECM-specific environment variables
- Click Connection in the properties, and select ICI, which is the environment variable you just created, as the ICI Web Service URL.
- Select Repo1 as the Repository ID and enter a user name
and password for the ICI Connector, as shown in Figure 31.
Figure 31. Set connection information for Document Attachment
- Click Presentation in the properties. In the Item Class Name field, enter the name of the document type that you want to retrieve from the ECM repository and click Add.
- The dialog displays all properties that exist for the document type
that you specify, as shown in Figure 32. To remove the unwanted
properties, click the property name in the Display Columns
table, then click Remove. You can enter the value you want the
Coach interface to use as the label for each property.
You can also establish a filter for particular properties. Refer to Create content integration server queries in the IBM Content Integrator Information Center for more information.
Figure 32. Set filters for ECM documents
- To add a document viewer to the Coach and associate it with the
document attachment, click the Coaches tab and drag a Document Viewer
control from the palette onto the design area. While the Document
Viewer control is selected, click Document Viewer in
the properties if it's not already selected. As shown in Figure 33, in
the Behavior section, select Document Attachment for
Association, then select a document attachment control for
Figure 33. Create a document viewer
- To run and test the human service, save the Coach in Process
Designer, and click the run icon. A web page is opened displaying the
Coach, as shown in Figure 34. If you click a row in the document list,
the content of the corresponding document is shown in the document
Figure 34. Test the human service
In this example, we showed a very simple scenario that didn't cover all features. For example, the document viewer can also be used alone and the document attachment control also has function of uploading documents to Content Manager. For more information, refer to the Business Process Manager Information Center.
Best practices for ECM integration
Following are some best practices for using the Document Attachment and Document Viewer controls in Process Designer:
- When defining filters, you must use long integers as conditions for
Date/Time properties, as shown in Figure 35. Date/Time data will be
returned in milliseconds since midnight Jan
Figure 35. Set filter for Date/Time data
- When choosing the properties you want to display in a Coach, make sure the properties that are to be displayed are included in the filter table even if there is no associated filter condition. Otherwise, you will not be able to get the document list when running the human service.
- The File title field is redundant when uploading documents to Content Manager. Any entered value is not recorded and there is also no a column in the document list to show the value.
In this article, you've learned about four different approaches for integrating with external systems in Process Designer. You learned some best practices for using the integration components to communicate with external systems. These integration components exist as services, so they can be reused in toolkits shared across process applications, making Business Process Manager systems easier and more efficient for business process designers.
- IBM Business Process Manager 7.5 Information Center
- IBM WebSphere ILOG JRules 7.1 Information Center
- IBM WebSphere Service Registry and Repository V6.2 Information Center
- IBM Content Integrator Information Center
- developerWorks BPM zone: Get the latest technical resources on IBM BPM solutions, including downloads, demos, articles, tutorials, events, webcasts, and more.
- IBM BPM Journal: Get the latest articles and columns on BPM solutions in this quarterly journal, also available in both Kindle and PDF versions.