Integrate external services with IBM Business Process Manager Standard or Express applications

This article walks you through the steps to integrate external services into IBM® Business Process Manager applications using Process Designer. It covers integration with Java™, web services, ILOG®, and Enterprise Content Management services, and describes best practices for achieving the integration. This content is part of the IBM Business Process Management Journal.

Share:

Hua (Ted) Cheng (chenghua@cn.ibm.com), Staff Software Engineer, IBM Australia

Hua Cheng photoHua (Ted) Cheng is currently the Team Lead for Business Process Management Test at the IBM Development Lab in Beijing, China. He has rich experience in BPM products including WebSphere Lombardi, WebSphere Process Server, and WebSphere Integration Developer. He also has a deep knowledge of Java and J2EE development and product testing. Prior to his current role, Ted led the BPM Integration Quality Assurance Team in China, and has also worked on several WebSphere Process Server development and test projects.



Lan Lan Cheng (lanlanc@cn.ibm.com), Software Engineer

Lan Lan Cheng photoLan Lan Cheng is currently on the System Verification Test team for Business Process Manager at the IBM China Lab in Beijing, China. She has experience in both development and functional and system verification testing of IBM products. Prior to her current role, Lan Lan helped develop the Websphere BPM Hypervisor Edition and the WebSphere InterChange Server to WebSphere Process Server migration.



Hua Qiang Zhang (hqzzhang@cn.ibm.com), Software Engineer, IBM Australia

Hua Zhang photoHua Qiang Zhang is a member of the Business Process Manager Team at the IBM Development Lab in Beijing, China. He has rich experience in IBM BPM products, including WebSphere Lombardi Edition and WebSphere Integration Developer. He also has experience with high-availability and stress testing for IBM BPM products.



29 September 2011

Overview

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:

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

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:

  1. 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
    Create new server file
  2. 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.
  3. Save the server file.
    Figure 2. Add new server file in Process Designer
    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:

  1. From the project tree, select Implementation, click the + icon, then click Integration Service.
  2. Specify the name as Hello World - java integration comp, as shown in Figure 3, and click Finish.
    Figure 3. Create integration service
    Create integration service
  3. To diagram the integration, click the Diagram tab and drag the Java Integration component onto the canvas, then change its name to Hello World – JIC and wire the components together, as shown in Figure 4.
    Figure 4. Add Java Integration component
    Add Java Integration component
  4. To configure the Java Integration component to invoke a Java method, click Hello World - JIC.
  5. Under Properties, click the Definition tab, and under Discovery, set the Java Class by doing the following, as shown in Figure 5:
    1. Click Select and select the class.
    2. Select HelloWorld(helloworld.HelloWorld).
    3. Select the method String helloWorldWithName(String) from the list.
    Figure 5. Configure Java method
    Configure Java method
  6. To set up the service variables, click the Variables tab, and add an input variable name of type string, and set the default value to John Doe, as shown in Figure 6. Add an output variable result of type string.
    Figure 6. Set up variables
    Set up variables

    (See a larger version of Figure 6.)

  7. 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 icon 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
    Define data mapping
  8. 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
    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:

  1. Create an integration service and set the name to Send Text Message.
  2. 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
    Create an integration service with the Web Service Integration component
  3. Configure the web service as follows:
    1. Click on the Web Service Integration component, and name the component send text message.
    2. 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
      Specify the WSDL URI for the web service integration

      (See a larger version of Figure 10.)

    3. Click Discover next to View, In the Discover wizard, leave the defaults, and click Discover.
    4. For Operations, select SendSMSBasic(string, string, string), as shown in Figure 11.
      Figure 11. Select web service operation
      Select web service operation

      (See a larger version of Figure 11.)

    5. 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
      Generate types
    6. 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
      Header of web service integration

      (See a larger version of Figure 13.)

    7. Click the Data Mapping tab, and click the auto-map icon 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
      Auto-map the input variables
  4. 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
    Set default value for parameters

    (See a larger version of Figure 15.)

  5. 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
    Define server script values
  6. Save the integration service.
  7. 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

  1. 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
    Browse to WSDL in repository
  2. 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.
  3. Click Next.
  4. 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.
  5. 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.
  6. 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.
  7. Click Discover to discover the WSDL.
  8. 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
    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 configuration files.
    Figure 19. HTTP authentication
    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 always provides wsse:Nonce and 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:

  1. 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 service:
    1. Log in to the Process Center WebSphere Application Server administrative console with administrative permission.
    2. Navigate to the security signer certificates, as shown in Figure 20.
      Figure 20. Signer certificates
      Signer certificates

      (See a larger version of Figure 20.)

    3. 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
      Retrieve signer information in administrative console
    4. Click Retrieve signer information to get the WebSphere Service Registry and Repository server information.
    5. Click Apply to save the information to the master configuration.
  2. 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.

ILOG integration

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:

  1. Create ILOG specific environment variables as follows:
    1. click the Setup category and double-click Environment Variables
    2. In the Environment Variable editor, click Add to add a new variable.
    3. Click the newly added row in the table, enter a Key, select ILOG Rules Server for Type, and enter http://9.119.146.63:9081 for Default Value, as shown in the Figure 22.
      Figure 22. Set the environment variables
      Set the environment variables
  2. 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
    Create Decision Service
  3. Connect to the Rule Execution Server. When connecting to different Rule Execution Servers, Process Designer will show different behaviors:
    • 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
    Connect to Rule Execution Server

    Select rule application and its version, and then select the ruleset and its version from the dropdown list.

  4. Click Generate Types. In the Generate Types wizard, click Next, then Finish, as shown in Figure 25.
    Figure 25. Generate types
    Generate types
  5. 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
    Auto-map variables

    (See a larger version of Figure 26.)

  6. Repeat the same steps for output parameters.
  7. 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
    Debug decision service

    (See a larger version of Figure 27.)

    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 as follows:
    1. Get the WSDL URI of the ruleset you want to invoke.
    2. 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.

  1. Create ECM specific environment variables as follows:
    1. Select Environment Variables.
    2. In the Environment Variable editor, click Add to add a new variable,
    3. 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_soa for the Default Value, as shown in Figure 28.
      Figure 28. Create ECM-specific environment variables
      Create ECM-specific environment variables
    4. 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.
  2. 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
    Create a human service
  3. 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.
    Figure 30. Create ECM-specific environment variables
    Create ECM-specific environment variables
  4. Click Connection in the properties, and select ICI, which is the environment variable you just created, as the ICI Web Service URL.
  5. 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
    Set connection information for Document Attachment
  6. 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.
  7. 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
    Set filters for ECM documents

    (See a larger version of Figure 32.)

  8. 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 Control.
    Figure 33. Create a document viewer
    Create a document viewer
  9. 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 viewer.
    Figure 34. Test the human service
    Test the human service

    (See a larger version of Figure 34.)

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:

  1. 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 1st 1970(Epoch).
    Figure 35. Set filter for Date/Time data
    Set filter for Date/Time data

    (See a larger version of Figure 35.)

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

Summary

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.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=758850
ArticleTitle=Integrate external services with IBM Business Process Manager Standard or Express applications
publish-date=09292011