Integrating RESTful web services into a business application in IBM Business Process Manager
In an effort to building a simple and efficient web client, many companies are adopting the Representational State Transfer (REST) architecture as an alternative to WSDL-based web services. As a result, the demand for integrating external systems through their REST APIs increases.
In IBM Process Designer, WSDL-based web services can be discovered and easily integrated using the built-in web service integration; however, RESTful web services (REST services) do not have a WSDL, so web service integration cannot be used to consume REST services. There are a number of suggested methods to integrate REST services in Process Designer using the Dojo Toolkit, which requires some level of knowledge to write the scripts.
While IBM Business Process Manager (BPM) Standard is designed to provide rapid time-to-value for typical business process management projects, IBM BPM Advanced offers a complete set of business process management capabilities including extensive enterprise-wide service integration. Therefore, your overall service-oriented architecture (SOA) solution should implement the system integration logic in the Advanced layer and your business applicationa should focus on delivering the business value.
The aim of this article is to introduce the RESTful web service integration in IBM Business Process Manager V8.0.1 Advanced by separating the system integration layer from the business layer using Service Component Architecture (SCA) HTTP binding.
In an effort to improve the current process, an enterprise decided to build an SOA solution that integrates all of their existing systems using BPM V8.0.1 Advanced. Some of the constraints were:
- Every system must comply with the company-wide data schema, which is very complex and has a hierarchical structure.
- One of the systems can be invoked only through its REST APIs.
- A rapid development cycle with limited resources.
The SOA Reference Architecture (SOA RA) (Figure 1) talks about nine key clusters of considerations and responsibilities in designing an SOA solution for enterprise.
Figure 1. SOA Reference Architecture
An SOA principle is to de-couple the business layer from the technical services layer. In the article Linking business processes and enterprise services together using IBM Business Process Manager Advanced, the author talks about the separation of business and technical services in BPM Advanced.
Based on the SOA principle, the solution in this article implements the business processes as business process definitions (BPDs) in IBM Process Designer. The REST services integration services are exposed to BPDs as Advanced Integration Services (AIS), which are SCA applications.
Figure 2. High-level architecture
IBM Integration Designer provides the development environment to implement the SCA applications that provide the REST integration. Because SCA is a middleware layer, it provides the capability to handle a highly complex XML schema, which may throw an error in Process Designer without custom transformation. The business object that BPD uses can be mapped to the standard schema format in the SCA before invoking the REST API.
The solution can be implemented using the built-in functionality of IBM Integration Designer, which eliminates the need for custom coding.
Overview of the steps to implement the solution
The development of the end-to-end solution involves the following steps:
- Create a toolkit
- Implement an AIS in Integration Designer:
- Import the standard schema and define the interfaces
- Create an SCA Export, which will be exposed as an AIS in Process Designer
- Create an SCA HTTP Import to invoke an external REST API
- Implement a mediation flow component (MFC) and map business objects to company schema
- Unit test the SCA application
- Invoke the REST services through AIS
- Invoke the AIS in a process application
Create a toolkit
The system integration implementation should be available across multiple process applications to enable reusability. Therefore, the AIS should be defined in a toolkit.
- Launch Integration Designer and connect to Process Center by clicking
the Open Perspective icon and then choose
Figure 3. Switch to Process Center perspective
- Enter the Process Center URL, user name and password, and then click
Login to connect.
Figure 4. Process Center log in
- Select the Toolkits tab and click Create New Toolkit.
- Provide the toolkit name and acronym to use and then click
Figure 5. Create a new toolkit
- Select Open in workspace to open the toolkit in the Business Integration perspective.
- Click OK in the Open Process Applications or Toolkits
in Workspace dialog. The tooling automatically creates two new
projects in the
REST_AIS_TK, as shown in Figure 6:
Figure 6. Open in workspace
If there is an existing toolkit that defines common business objects to be used across multiple process applications, you can add the dependency to your toolkit so that you can use them in your implementation.
Figure 7. Common business object toolkit
You must add the dependency in the Process Designer first, and then return to Integration Designer to open the toolkit in workspace. The business objects defined in another toolkit are not modifiable, but you can use them in your implementation.
Business objects that are defined in the
<Toolkit_name>_Library become visible in Process
Designer (in this example,
REST_AIS_TK_Library). If the
industry standard schemas or company schemas contain XML constructs that
are not supported in Process Designer, you must define a separate library
that is not visible to Process Designer.
Note: If there is no pre-defined schema to use, ignore the following steps 1 through 13 and skip to the Define interfaces section.
- Select File => New => Library and then provide
the library name such as
- Click Next. The Select a process application
or toolkit check-box should be selected. Ensure that the
process application or toolkit name is correct (for example,
- Click Finish.
- Right-click the newly created library and select Import from the list.
- Expand Business Integration and select WSDL
Figure 8. Import existing schema files
- Click Next.
- Select Local WSDL or XSD file, or both if you have a local copy of the schemas, then click Next.
- Navigate to the location of the schema files and then click
Finish. This generates business objects based on
the XML schema describing the data types.
Figure 9. Business objects derived from XML Schema
- Some errors may appear in the Problems view. Right-click Schema_Library and select Properties.
- Expand Business Integration and select
Library Mirroring. Ensure that the Mirror
the library as soon as it is associated with Process
Center checkbox is not selected.
Figure 10. Library mirroring property
Note: By not mirroring this library, you can hide any complexity from Process Designer. For more detail, refer to "Best practice: Protect mirrored artifacts in toolkits" in the article, Best practices when using IBM Integration Designer and IBM Process Designer together.
- In the Business Integration view, expand
REST_AIS_TK_Implementation and double-click
Dependencies to open the dependency editor.
Figure 11. SCA module dependency
- Click Add and add Schema_Library.
- Click Ctrl + S to save the change. This allows the
REST_AIS_TK_Implementationmodule to use the business objects that were generated from the schemas.
The design uses an SCA HTTP Import to invoke the target REST services. The first step is to define an interface for SCA Import and SCA Export components. Unlike WSDL-based web services, REST services do not have an interface. The interface that you are going to define in this section is for the SCA components.
The SCA Export becomes the AIS service in Process Designer. In order to set the service contract between BPD and AIS, the export component must have an interface to define the input and output messages to be used by BPD.
Figure 12. SCA assembly diagram example
Similarly, the SCA Import with HTTP binding is an SCA artifact that it must have an interface although the target REST service does not define a WSDL associated with it. This interface is used as a contract between SCA components. Therefore, you should set the name of the interface and its operation that are meaningful. Be aware that the input and output message types must match the exact type that the target REST service is expecting. If you have an existing XML schema defining the input and output types, the input and output types of your operation must be the schema type that you imported in the Schema_Library step.
- In the Business Integration view, under
Interfaces and select New =>
Figure 13. Create a new interface
- Enter the name for the new interface and then click Finish.
- Click the Add Request Response Operation icon to add the definition
for the REST service you are going to invoke.
Figure 14. Adding request-response operation
Note: This example uses business objects derived from importing the existing XML schema:
- Specify the data type for inputs and outputs based on the company schema.
- Select Change binding style to document literal
non-wrapped to change the binding style.
Figure 15. Change WSDL binding style
- Click Yes in the Change Binding Style dialog to proceed with the change. The binding style should have changed from document literal wrapped to document literal non-wrapped.
- Click Ctrl + S to save.
When you invoke REST services, the request has to be constructed exactly as the target service expects. Therefore, you do not want to use the document literal wrapped option, which wraps elements with the corresponding operation name. Instead, use the document literal non-wrapped binding so that the resulting XML will not have excess tags, which results in a runtime error.
- In the Business Integration view, right-click Interfaces under REST_AIS_TK_Library to create an interface for AIS.
- Add a request-response operation. Remember that this interface is visible in Process Designer; therefore, the name of the operation should be straightforward.
- If you are dealing with complex schemas, which are not supported by
Process Designer, you must define a simplified business object.
Right-click string under Type, then
select New to define a new business object.
Figure 16. Add a new business object
If there is a toolkit that holds common business objects to be used across the process applications and toolkits, you can add the toolkit as a dependency to your AIS toolkit. This allows you to use the business objects defined in the Process Designer.
For example, the standard schema may have a complex structure as shown in Figure 17.
Figure 17. XML schema generated business object example
You may want to simplify the business object with simple types which can be
used by the BPDs in Process Designer so that the Coach can easily display
the data. For example, an XML schema with
xs:choice cannot be parsed properly in Process Designer.
Instead, you may want to add input checking in the Coach and keep the
business object simple as shown in Figure 18.
Figure 18. Business object example
Note: If you have common business objects added to your project through dependencies, as shown in Figure 7, you can click Browse to select an existing business object instead of creating a new one.
The interface defined under
invisible in Process Designer; therefore, you can use unsupported data
types and schemas. However, the interfaces and business objects defined
REST_AIS_TK_Library are visible in Process Designer.
Therefore, you should design the interfaces and business objects in such a
way that their usage is clear to the business process developers.
Figure 19. Business Integration view
- Click Ctrl + S to save.
Create an SCA Export
In the previous section, you defined an interface to explain your AIS service. In this section, you create an Export component with an SCA binding using the interface, which becomes the AIS service in Process Designer.
- Under REST_AIS_TK_Implementation, double-click Assembly Diagram to open the assembly diagram editor.
- Select the interface under REST_AIS_TK_Library => Interfaces and drag and drop it onto the assembly diagram.
- Select Export with no Binding and click
Figure 20. Create an SCA export
- In the assembly diagram, right-click the newly created export component and select Generate Binding => SCA Binding.
- With the export component selected, click the Binding tab in the Properties view. Ensure that the Make operations visible to IBM Process Designer checkbox is checked.
- Click Ctrl + S to save.
Note: This SCA export component will be exposed as an AIS service in Process Designer when you publish the completed SCA implementation as shown in Figure 21.
Figure 21. SCA Export as an AIS in Process Designer
Create an SCA HTTP Import
In order to invoke an external REST service, you need to implement an SCA import with HTTP binding.
- Under REST_AIS_TK_Implementation, double-click Assembly Diagram to open the assembly diagram editor.
- Select the newly created interface under REST_AIS_TK_Implementation => Interfaces, then drag and drop it anywhere on the assembly diagram canvas.
- In the Component Creation dialog, select Import with no Binding and then click OK.
- Right-click the generated import component and select Generate Binding => HTTP Binding.
- Enter the end-point URL of the REST service that you are integrating and then click OK. The icon on the SCA import should change.
- In the assembly editor, select the SCA import and then select the
Properties view in order to further modify the
HTTP binding detail.
Figure 22. SCA Import with HTTP binding
- If the HTTP method is not
GET, select the appropriate verb from its drop-down list.
- Click the Method Bindings tab in the Properties view.
- Select the method name for the REST service, and ensure that the
method binding properties are set correctly as well.
(Note: If the HTTP method is set to
POSTin the Method Binding tab but the method is set to
GETin the Binding tab, the HTTP method that will be used at runtime is
POST. The property values set on the specific method overwrite the binding level property value.)
Figure 23. Set HTTP method binding
- Click Ctrl + S to save.
If the target REST service is running on a secured server, the SSL security certificate needs to be configured on the process server.
- In the administrative console, select Security => SSL
certificate and key management.
Figure 24. SSL certificate and key management
- If you are working with a standalone server, you should have a
NodeDefaultSSLSettings. In a clustered environment, you should have a
CellDefaultSSLSettingsas well. For a standalone server, select NodeDefaultSSLSettings; otherwise, select CellDefaultSSLSettings to configure the SSL certificate at the cell level.
- Select Key stores and certificates.
- Select NodeDefaultTrustStore for a standalone server, and select CellDefaultTrustStore for a clustered environment.
- Select Signer certificates to add the certificate if
it has not been done already.
Figure 25. Configure a signer certificate
- Return to the assembly diagram, select the HTTP Import and set the
SSL configuration name to the appropriate key
store name in the Properties view.
Figure 26. HTTP binding properties
Note: For a standalone server, this should be
NodeDefaultTrustStoreand for a clustered environment it should be
- Click Ctrl + S to save.
Implement a mediation flow component (MFC)
In this scenario the target REST service uses data types that are not supported by the Process Designer; therefore, you need to transform the incoming data and map it into the schema-generated business object. MFC provides a built-in mapping component to easily accomplish the task.
- In the REST_AIS_TK_Implementation assembly diagram,
select Mediation Flow under
Components in the palette and drag and drop it
onto the assembly diagram.
Figure 27. Add a mediation flow
- Rename the mediation flow component as desired.
- Wire CompanyInfoAISExport1 to the newly created mediation flow component (in this example, REST_Mediation). In the pop-up dialog, click OK to add the matching interface to the mediation flow.
- Wire REST_Mediation to REST_CompanyInfoImport1. In the pop-up dialog, click OK to add a matching reference to be created on the mediation flow component.
- Click Ctrl + S to save.
REST_Mediationand click Yes to implement.
- Click OK to generate the implementation in the default folder (Note: If you want the mediation flow implementation to be created in a certain folder, click New Folder to define a specific target folder.)
- In the mediation flow editor, select the operation and click
Blank Mediation Flow.
Figure 28. Implement the mediation flow
- Under Transformation, select HTTP Header Setter and drag and drop it onto the editor.
- Wire the operation input to HTTP Header Setter.
Figure 29. HTTP Header Setter mediation primitive
- With the HTTP Header Setter primitive selected, click the Details tab in Properties view.
- Click Add to set the HTTP header values, then select
Media Type from Header Name and
application/xmlin the Value field.
Figure 30. Set HTTP header value
- Click Finish.
- Similarly, set the header values for Accept and
Figure 31. HTTP Header Setter details
- In the right pane, expand References and select the target REST service operation and drag and drop it onto the editor.
- Wire the HTTP Header Setter primitive to the newly added Service Invoke primitive, and select Transform the message using a Mapping primitive.
- Double-click the newly created Mapping primitive and accept the default in the New XML Map wizard, and click Finish. Implement the map as necessary to properly construct the input for the target REST service.
- Similarly, wire the out terminal of the Service Invoke primitive to Input Response. In the pop-up dialog, select Transform the message using a Mapping primitive.
- Double-click the newly created Mapping primitive and
accept the default in the New XML Map wizard and
Figure 32. Mapping example
- Implement the primitive to properly map the service response to the
simplified output of the AIS interface.
Figure 33. Mediation flow example
- Click Ctrl + S to save.
- Return to the REST_AIS_TK_Implementation assembly diagram, and select the mediation flow component.
- In the Properties view, select the
Details tab and set the Preferred
interaction style of the mediation interface to
Synchronous. (Note: By default,
the preferred interaction style of the mediation is
Figure 34. Preferred interaction style
- Select the export CompanyInfoAISExport1 and ensure
that the preferred interaction style is set to
Synchronous. Also, ensure that Make
operations visible to IBM Process Designer in the
Binding tab is checked.
In order to make your SCA service available as an AIS in Process Designer so that BPDs can consume it, the preferred interaction style must be Synchronous (not Any or Asynchronous), so that the control can be returned to the calling BPD. Otherwise, the Can be used with service? status of the AIS component show as No instead of Yes in Process Designer.
Figure 35. AIS definition in Process Designer
Test the SCA implementation
Before publishing your SCA implementation to the Process Center, be sure to unit test the service on your local server.
Figure 36. Servers view
- In the assembly diagram, right-click
ComponentInfoAISExport1and select Test Component.
- Enter the test data under Initial request parameter section
- Click Continue to run the test.
Figure 37. Integrated Test Client
- In the Deployment Location wizard, select your local
test server and click Finish.
Figure 38. Select a deployment location
- In the User Login – Default Module Test dialog, enter the appropriate user ID and password to connect and then click OK. This automatically deploys the application to the server before starting the test execution.
If the test completes successfully, you are ready to connect the process application to the advanced integration in Process Designer. Otherwise, make necessary fixes and then right-click Invoke and select Rerun to test again.
Figure 39. Re-executing the test
Once the SCA implementation is thoroughly tested, ensure that the status of
the toolkit is not
[changed]. If it is, right-click and
select Refresh and Publish from the menu to synchronize
the code to Process Center.
Figure 40. Refresh and publish the toolkit
Invoke the REST services through AIS
The SCA export defined in the
module becomes an AIS in Process Designer. The input and output for the
AIS align with the types you defined in the interface for the Export
- Launch Process Designer and open the toolkit in the designer.
- Under Implementation, double-click
CompanyInfoAIS to open the AIS. Ensure that there
is no error or warning.
Figure 41. Advanced Integration Service
- In order to ensure that the AIS works, create a test harness. Click the + sign next to User Interface and select Human service.
- Click the Variables tab and add variables that hold
AIS input and output.
Figure 42. Setting variables
- Return to the Diagram tab and drag and drop the AIS onto the diagram.
- With the AIS selected, click the Data Mapping tab.
- For Input Mapping, click the Select a Variable icon to select the input variable.
- Similarly, click the Select a Variable icon to select the variable to
hold the output value for Output Mapping.
Figure 43. Test harness
- Add a Coach task to enter the input data as well as a
Coach task to display the output from the invoking AIS.
Figure 44. Human service diagram
- Save the changes
- Click Run Service to execute the test harness and run
through the test to ensure that it completes successfully.
Figure 45. Run service
If you encountered a problem, run the test harness in debug mode by clicking Debug service. You can step through the service to find the point of failure.
You should see that the
SCAConnector item type before the AIS
is getting invoked as shown in Figure 46.
Figure 46. Debug service
In the next step, if you see a default Coach instead of the Coach you built, it is likely that the SCA application did not get deployed correctly.
Figure 47. Status bar
Invoke the AIS from the process application
In order to separate the integration layer from business logic, the AIS was implemented in a toolkit so that multiple process applications can utilize its services. This section demonstrates how to invoke the AIS defined in a toolkit from a process application.
- In order to make this toolkit available to other toolkits and process
applications, you need to create a snapshot. Click the Snapshot icon
to create a new snapshot of the toolkit.
Tip: Integration Designer uses a three-digit-numeric version system (<major>.<minor>.<service>) to version SCA applications. Therefore, it is recommended that you use three-digit-numeric versions for your snapshots as well.
- After creating a snapshot, click the Process Center icon to return to the main page.
- Click the Process Apps tab and either select an existing process application or create a new process application by clicking Create New Process App and then selecting Open in Designer.
- Under TOOLKITS, add the dependency to the AIS
Figure 48. Toolkit dependency
- If you are working with a new process application, create a new process by clicking on the + next to Processes and selectingBusiness Process Definition; otherwise, open the existing process.
- In the Variables tab, add the appropriate input and output variables for the AIS.
- Return to the Diagram tab. From the right-hand pane, select the Activity task and drag and drop it onto the Participant swim lane.
- Add a second activity ask in the Participant lane.
- Rename the tasks in such a way that they describes the purpose of the tasks.
- Under TOOLKITS, expand REST_AIS_TK,
then select CompanyInfoAIS under
Implementation and drag and drop it onto the
Figure 49. Adding the AIS as a task
- Wire all the tasks to complete the business flow.
Figure 50. Adding human tasks
- Right-click the activity task in the Participant lane and select Activity Wizard.
- Select User Task and then click Next.
- Verify the variables and click Finish.
- Double-click the user tasks to implement the Coach to enter the input and to display the output.
- Select the AIS task CompanyInfoAIS in the diagram.
- Select Data Mapping in the
Properties view and set the input and output.
Figure 51. Business process definition
- Save the changes.
Note: This is the simplest example of a BPD. In typical practice, you may create a wrapper Integration service, which invokes the AIS service, and then add the wrapper service to the BPD. If you want to create a test harness or wrapper service, which is similar to the test harness you created in the
REST_AIS_TK, you can copy the test harness from the toolkit to the process application.
Figure 52. Copying a service from toolkit
- Switch to Process Inspector by clicking Inspector.
- Click the Run Process icon to test the process.
Figure 53. Process Inspector
- Run through the process instance and verify the end-to-end process
Refer to the Information Center for more information on how to run and debug a process instance with the Inspector.
Hints and tips
Process Inspector cannot step through the SCA application that implements the AIS. To do this, in the Integration Designer, right-click the toolkit and select Test => Attach to Toolkit.
Figure 54. Attach to toolkit
Click the Continue icon to open a dialog that prompts you for which server to attach the test client to.
Figure 55. Starting the test client trace
In this case, select the Process Center instead of the local process server because the process application runs on the playback server on Process Center.
Figure 56. Select a server
Once the data gets passed to the SCA implementation, you can trace the event in the test client.
The SCA applications associated with the AIS implementation are deployed as WebSphere enterprise applications and you can manage them directly from the WebSphere Integrated Solutions Console, or administrative console.
When you click Run Services or Run
Process in the Process Designer, the necessary SCA artifacts
are automatically installed onto the playback server on Process Center. In
the administrative console, select Applications => SCA
modules. The SCA module names are
<toolkit name>_Implementation as they were in
Figure 57. WebSphere Integrated Solutions Console
The application name is
for the current working process application or toolkit. If you deploy a
specific version of a snapshot,
Tip is replaced by the
Figure 57 shows three instances of REST_AIS_TK_Implementation modules:
REST-Tip_REST_AIS_TK_ImplementationAppis installed during the execution of the test harness in the REST_AIS_TK toolkit.
TEST-Tip_REST_AIS_TK_ImplementationAppis installed during the execution of the REST Test App process application.
TEST-1.0.0_REST_AIS_TK_ImplementationAppis installed during the deployment of a REST Test App process application snapshot.
This article took you through a step-by-step example of integrating a REST service in IBM Business Process Manager V8.0.1 Advanced. Since REST services do not have a WSDL, the built-in web service integration in Process Designer cannot be used to consume REST services without custom coding. In addition, working with highly complex XML schema may result in parsing errors without server scripts. An SOA principle is to decouple the business layer from technical services layer. Therefore, the business processes should be separated from the lower-level services to integrate external REST services, and consume the services through AIS. This separates the business logic from middleware functionality and makes the solution more robust and reusable.
- Best practices when using IBM Integration Designer and IBM Process Designer together
- Linking business processes and enterprise services together using IBM Business Process Manager Advanced
- IBM Cloud Professional Services: Find out how IBM expertise in cutting-edge and proven technologies can help you achieve your business and IT goals.
- developerWorks Middleware: Get the latest technical resources on middleware solutions, including downloads, demos, articles, tutorials, events, webcasts, and more.