Contents


Develop Advanced Integration services for IBM Business Process Manager V8.5.6

Comments

This tutorial explores the new option in IBM® Business Process Manager (BPM) Advanced V8.5.6 to create and deploy Advanced Integration services in a separate module managed outside of IBM Process Center. Learn how to implement Advanced Integration services and how to use them in a process or service created with IBM Process Designer.

An Advanced Integration service is used to call a service that is implemented in IBM Integration Designer from a business process definition (BPD) or from another service in IBM BPM. Using a separate module for Advanced Integration service implementation has multiple advantages. The most important advantage is that it ensures that there is only one Advanced Integration service implementation module – an enterprise archive (EAR) file – no matter how many BPDs include the Advanced Integration service implementation toolkit. See Figure 1.

Figure 1. In IBM BPM V8.5.6 only one EAR file is deployed
Screen                     capture of one EAR file deployed in IBM BPM V8.5.6
Screen capture of one EAR file deployed in IBM BPM V8.5.6

Before IBM BPM V8.5.6, every time a toolkit with the Advanced Integration service implementation was used in a process application, a new Advanced Integration service implementation module (an EAR file) was deployed. See Figure 2.

Figure 2. An EAR file deployed for every Advanced Integration service implementation in versions before IBM BPM V8.5.6
Screen                     capture of multiple EAR files deployed in versions before IBM BPM V8.5.6
Screen capture of multiple EAR files deployed in versions before IBM BPM V8.5.6

Another advantage is that it does not tie the Advanced Integration service implementation lifecycle to the process application lifecycle – it is possible to change the implementation without redeploying the process applications that use the Advanced Integration service toolkit.

IBM BPM projects often require complex integrations with external sources such as web services or back-end systems such as databases or enterprise information systems. These integrations might each require complex choreography and data mapping. This type of work is made easier using IBM Integration Designer. Implementations that were created with Integration Designer can be called from IBM BPM projects through an Advanced Integration service. In Process Designer, the Advanced Integration service implementation type is available only in IBM BPM Advanced. See Figure 3.

Figure 3. An Advanced Integration service implementation
Screen                     capture of an Advanced Integration service implementation
Screen capture of an Advanced Integration service implementation

The Advanced Integration Service implementation can be started from BPDs, human services, or service flows. It runs on the same server as the Process Center or on a Process Server and is deployed as an EAR file.

Creating an Advanced Integration service implementation

An Advanced Integration service definition exists in a process application or toolkit and contains the information that is needed to start a Service Component Architecture (SCA) module. The actual implementation is in an SCA module, which exists in an integration project and is authored in Integration Designer. An SCA module is deployed as a Java Platform, Enterprise Edition (Java EE) application on the same application server that hosts the Process Center or Process Server application.

There are two primary ways to implement an Advanced Integration service (as shown in Figure 4):

  1. In a separate stand-alone module (new in IBM BPM V8.5.6).
  2. In the same process application or toolkit.
Figure 4. Advanced Integration service implementation options
Screen                     capture of Advanced Integration service implementation options
Screen capture of Advanced Integration service implementation options

Implementing an Advanced Integration service in the same toolkit or process application

The simplest way to implement an Advanced Integration service is in the same process application or toolkit that it is defined in. This way, the enterprise application is deployed automatically by selecting a menu item in Integration Designer, when the process application is activated, or when a BPD is run. As the implementation evolves, creating versions of both the process and Advanced Integration service is accomplished simply by taking snapshots of the process application or toolkit. If you look at the Hiring Sample Advanced in Process Designer, you see an example of an Advanced Integration service that is defined and implemented in the process application.

Implementing in the same process application or toolkit is useful in cases such as rapid prototyping, but it comes with a cost, and it is not recommended for production quality applications. As development continues in Process Designer, advanced deployment (which is enterprise application deployment) can occur each time a BPD is run, if an Advanced Integration service interface, or a business object that is used by an Advanced Integration service interface, is changed. The performance costs of advanced deployment can impact users of the process center. These cost can be lessened by implementing the Advanced Integration service in a toolkit because it is separate from the process application. However, there is still some increased processor usage because the process application that contains the Advanced Integration service toolkit needs to go through advanced deployment each time the toolkit version is changed.

Implementing an Advanced Integration service in a separate stand-alone module

The best way to work with an Advanced Integration service in most cases is to define it in a toolkit and then implement it in a stand-alone Integration Designer module. In fact, starting with IBM BPM V8.5.6, if you create an Advanced Integration service in a process application, you receive a message that it is better to implement the Advanced Integration service in a toolkit. When you create an Advanced Integration service in a toolkit, you can share it among other projects, and more importantly, you have a choice of implementing it as a stand-alone module. Because it is the recommended pattern, implementing in a stand-alone module is the default. The integration project that contains the Advanced Integration service still must be deployed as an enterprise application, but deployment to the Process Center server is infrequent and independent of process application updates. The downside is that you must deploy the stand-alone module manually. Even when Advanced Integration services were implemented only in a process application or toolkit, many users found that stand-alone deployment was a preferred option. (The process application or toolkit implementation was a facade for the actual implementation. See Implementing the facade pattern using IBM Business Process Manager Advanced V7.5, previously published on developerWorks).

When an Advanced Integration service is implemented in a stand-alone module, it can evolve independently of any process applications or toolkits that use it. The only time a change is needed in Process Designer is if the signature or the definition has changes (such as a different module name), or if a new version of the module is created. Now with IBM BPM V8.5.6, a change in Process Designer does not result in any advanced deployment of the process application, like it did in previous IBM BPM versions. Before IBM BPM V8.5.6, when an IBM BPM project was imported into Integration Designer, it meant that the project was now advanced, and therefore the project was deployed as an enterprise application. In IBM BPM V8.5.6, advanced deployment no longer occurs unless there is executable content in the default projects, or if extra projects are associated with the process application or toolkit.

Sample code: Creating the Advanced Integration service implementation in a stand-alone module

In the Download section of this tutorial, you can get a completed Advanced Integration service sample with a client-side human service that starts the Translate AIS Advanced Integration service (as shown in Figure 5). Download the code_sample.zip and extract the file. The Advanced Integration service sample consists of three files:

  • AIS - 3.0.twx (a toolkit that includes the client-side human service and the Advanced Integration service definition)
  • AISModule.zip (a project interchange file that includes the Advanced Integration service implementation source)
  • AISModuleApp.ear (an EAR file that contains the Advanced Integration service implementation)
Figure 5. Example client-side human service that starts an Advanced Integration service
Screen                     capture of a client-side human service that                     starts an Advanced Integration service
Screen capture of a client-side human service that starts an Advanced Integration service

The sample application prompts the users to enter inputs, and then passes those inputs to the Advanced Integration service. The process continues after the Advanced Integration service returns a response. If the Advanced Integration service produces an error, then the fault path is taken in the process.

This section provides the basic steps for the following activities to install the sample Advanced Integration service source code:

  • Open the Advanced Integration service definition toolkit in Integration Designer
  • Import the sample Advanced Integration service implementation
  • Examine the sample Advanced Integration service implementation details
  • Examine the implementation in the stand-alone module
  • Deploy the stand-alone module
  • Run the sample Advanced Integration service

The following sections show the steps to implement the Advanced Integration service that is contained in the attached Advanced Integration service sample. An implemented Advanced Integration service has property values that describe the SCA export that is called to start the service. You can use the Advanced Integration service implementation wizard to complete the export description automatically. An SCA export is defined in an integration module by using Integration Designer and is one of the ways of exposing the components that are contained in the module. The actual service business logic is contained in a component that is wired to the export, which in turn might be wired to other components. To the caller of the export, everything inside the module beyond the export is a black box.

Open the Advanced Integration service definition toolkit in Integration Designer

Complete the following steps to open the sample Advanced Integration service definition toolkit in Integration Designer:

  1. Open Integration Designer with a new workspace.
  2. Switch to the Process Center perspective.
  3. Log in to the Process Center.
  4. Import the AIS – 3.0.twx file into the Process Center.
  5. Ensure that the toolkit you imported has Allow users to update toolkit selected.
  6. Open the Advanced Integration service toolkit in Integration Designer. (Click Open in workspace.)
  7. Clear the Responsive Coaches toolkit before you click OK.

Import the sample Advanced Integration service implementation

Complete the following steps to import the sample Advanced Integration service implementation:

  1. Download and save the attached AISModule.zip file.
  2. In Integration Designer, select File > Import > Other > Project Interchange and then click Next.
  3. Browse to AISModule.zip and select only the AISModule project, as shown in Figure 6. (The AIS_Library project is already in the workspace because it was imported from the Process Center in the Advanced Integration service toolkit.) Then, click Finish.
    Figure 6. Importing the Advanced Integration service implementation module
    Screen                     capture of the Import Project Interchange Contents window
    Screen capture of the Import Project Interchange Contents window

Examine the sample Advanced Integration service implementation details

The Advanced Integration service is already implemented in AISModule (See Figure 7).

Examine the implementation details:

  1. In the Business Integration window, expand the AIS toolkit project. Under Advanced Integration Services you see the translate Advanced Integration service.
  2. Right-click translate, and select Edit.
  3. Now you see Implement Advanced Integration Service wizard. See Figure 7 and examine the choices made for the sample implementation for this Advanced Integration service:
    • Module: AISModule – Clicking New creates a module. It is also possible to select an existing module in the workspace, or to type in the name of a module that is deployed.
    • Export name: AISExport – The export name is the name of the SCA export name that was generated by the wizard in AISModule. This SCA export is visible to the BPD. When the client-side human service starts the Advanced Integration service, it implicitly uses this SCA export.
    • Operation name: invoke – The operation name is the operation that is defined in the translate interface for the translate Advanced Integration service.
    Figure 7. Advanced Integration service implementation details
    Screen                     capture of the Select Implementation Location window
    Screen capture of the Select Implementation Location window

Examine the implementation in the stand-alone module

Examine the implementation:

  1. Double-click AISModule and Assembly Diagram. Note the AISExport that was created by the wizard and the AISExport_Process BPEL SCA component. Also, note the translate interface, which is defined in the AIS_Library. This interface was defined in the Advanced Integration service toolkit.
    Figure 8. Advanced Integration service implementation: SSA export and BPEL component
    Screen                     capture of the Advanced Integration service implementation: SSA export and                     BPEL component
    Screen capture of the Advanced Integration service implementation: SSA export and BPEL component
  2. Double-click AISExport_Process. The Advanced Integration service is implemented as a BPEL microflow. The BPEL process checks that the request is valid. If it is valid, the BPEL process converts the message to the requested language (for simplicity, it converts only the word "Hello" to French). If it is not valid, it produces an error, as shown in Figure 9.
    Figure 9. BPEL component implementation example
    Screen                     capture of a BPEL component implementation example

Deploy the stand-alone module

For the Advanced Integration service implementation to be called, the EAR file that contains the module must first be installed on the server. Complete the following steps to install the EAR file:

  1. Log in to the WebSphere Integrated Solution Console for the Process Center server.
  2. Select Applications > Application Type > WebSphere enterprise application.
  3. Click Install.
  4. Click Browse and browse to the AISModuleApp.ear file, as shown in Figure 10. Then, click Next.
    Figure 10. Installing the Advanced Integration service implementation EAR file
    Screen                     capture of Installing the Advanced Integration service implementation                     EAR file
    Screen capture of Installing the Advanced Integration service implementation EAR file
  5. Continue clicking Next and accepting the default values in each of the installation steps.
  6. After the last installation step, click Finish, and then save to the master configuration.
  7. After the EAR file is installed, on the Enterprise Applications page, select AISModuleApp, and then click Start, as shown in Figure 11.
Figure 11. Starting the Advanced Integration service implementation EAR file
Screen                     capture of starting the Advanced Integration service implementation                     EAR file
Screen capture of starting the Advanced Integration service implementation EAR file

The enterprise application that contains the Advanced Integration service is now ready to be called from the toolkit.

Run the sample Advanced Integration service

First, open the Advanced Integration service toolkit in Case Designer by completing the following steps:

  1. Open the Process Center web page in a browser.
  2. On the Toolkits tab, select AIS and click Manage. Select Allow users to open the the toolkit in the web-based Case Designer.
  3. Click the Toolkits tab again, and then click the Open in Case Designer link to the right of the toolkit.

The sample Advanced Integration service toolkit contains a Hello client-side human service, as shown in Figure 12. This human service starts the Advanced Integration service.

Figure 12. "Hello" client-side human service
Screen                     capture of example Hello client-side human service
Screen capture of example Hello client-side human service

Complete the following steps to start the Hello client-side human service:

  1. In Case Designer, click User Interfaces > Hello.
  2. To run this client-side human service, click Run.
Figure 13. Running the "Hello" client-side human service
Screen                     capture of Running the Hello client-side human service
Screen capture of Running the Hello client-side human service

The Advanced Integration service in this sample provides a translation service with some major restrictions. If the language is not "French" or the message to be translated is not "Hello", it throws an exception!

To test the Advanced Integration service service in the Hello client-side human service, complete the following steps:

  1. For Your Name, enter your name. For Language enter French. For Message, enter Hello.
  2. Click Translate, as shown in Figure 14.
Figure 14. "Hello" client-side human service – happy path
Screen                     capture of a happy path for the example Hello client-side human service
Screen capture of a happy path for the example Hello client-side human service

Now complete the following steps to try the exception path:

  1. Click TRY AGAIN.
  2. For Your Name, enter your name. For Language, enter French, and for Message enter Greetings.
  3. Click Translate.
Figure 15. "Hello" client-side human service – exception path
Screen                     capture of an exception path for the example Hello client-side human service
Screen capture of an exception path for the example Hello client-side human service

Detailed steps: Creating an Advanced Integration service implementation in a stand-alone module

The previous sections described how to import, deploy, and test a sample Advanced Integration service implementation that was already created. By examining the sample implementation, you discovered how the association between the Advanced Integration service definition and the stand-alone implementation works. This section completes the details on how you implement an Advanced Integration service from scratch. It also shows how you can create an alternative implementation without affecting the business process or the service that calls the Advanced Integration service.

Remove the current implementation

Because the Advanced Integration service definition provided is already implemented, delete the current implementation from your workspace and then remove the implementation reference from the Advanced Integration service definition. Complete the following steps:

  1. To remove the AISModule from your workspace, right-click AISModule in the Business Integration view and then select Delete.
  2. To remove the Advanced Integration service definition, expand the AIS toolkit project. Under Advanced Integration Services, you see the translate Advanced Integration service.
  3. Right-click translate and then select Remove Implementation.

Create another Advanced Integration service implementation

Now that you removed the current implementation, create a different one by completing the following steps:

  1. The translate Advanced Integration service was changed to translated (unimplemented) when you removed the implementation reference from the Advanced Integration service definition. Expand the entry as shown in Figure 16 and click the Implement link to create a different implementation for the Advanced Integration service.
    Figure 16. Implement an Advanced Integration service definition
    Screen capture of how to implement an                         Advanced Integration service definition
  2. The Implement Advanced Integration Service wizard opens. Create a module that is called TranslationService to contain the Advanced Integration service implementation. Click New and then enter TranslationService in the Module Name field of the New Module window and then click Next, as shown in Figure 17.
    Figure 17. Create a module for the Advanced Integration service implementation
    Screen capture of the Implement Advanced Integration Service                             window and the New Module window
    Screen capture of the Implement Advanced Integration Service window and the New Module window
  3. The next window in the wizard displays the libraries to be referenced by the newTranslationService module. The AIS_Library contains the interface and data object definitions that are used by the Advanced Integration service to communicate with the Advanced Integration service implementation. Click Finish to create the module, as shown in Figure 18:
    Figure 18. Select Required Libraries window
    Screen capture of the Select Required Libraries window
    Screen capture of the Select Required Libraries window
  4. The module is created and is displayed in the Business Integration View. The wizard shows the module name but requires an Export name. Enter TranslationServiceExport as the export name and click Next, as shown in Figure 19.
    Figure 19. Select Implementation Location window: Export name
    Screen capture of the Select Implementation Location window
    Screen capture of the Select Implementation Location window
  5. Now choose the implementation type for the Advanced Integration service. The sample implementation used a microflow. To switch it up, use a Java component this time. Select Java component and click the Finish, as shown in Figure 20.
    Figure 20. Select an Implementation Type window
    Screen capture of the Select an Implementation Type window
    Screen capture of the Select an Implementation Type window
  6. The Advanced Integration service definition is now updated with the Advanced Integration service implementation details and you have a skeleton of an Advanced Integration service implementation to work with. The editor on the Java component is open and ready for you to enter the service logic, as shown in Figure 21:
    Figure 21. Updated definition and implementation for the Advanced Integration service
    Screen capture of the updated definition and implementation for the Advanced Integration service
    Screen capture of the updated definition and implementation for the Advanced Integration service
  7. Complete the skeleton implementation by replacing the invoke function with the following code, which adds Spanish to the BPEL implementation provided in the sample:
    	public DataObject invoke(DataObject request) {
    		// Validate
    		boolean valid = request.getString("language").equals("French") || 
    				request.getString("language").equals("Spanish");
    		String error = null;
    		if( valid == false){
    		 error = "Language '" + request.getString("language") + 
    				 "' is not supported.";
    		} else {
    		  valid = request.getString("message").equals("Hello");
    		  if( valid == false) {
    		    error = "Phrase '" + request.getString("message") + 
    		    		"' cannot be translated.";
    		  }
    		}
    		// Respond.  We use the Request as the Response.
    		if (valid) {
    			if (request.getString("language").equals("French")) {
    				request.set("message", "Bonjour");
    			} else {
    				request.set("message", "Hola");
    			}
    			return request;
    		} else {
    			throw new ServiceBusinessException(new String(error), 
    					"fault");
    		}
    	}

Publish the Advanced Integration service definition and test it

Now you publish your Advanced Integration service definition changes to the Process Center, install the Advanced Integration service implementation on the Process Center, and then test that it works properly. Complete the following steps:

  1. To publish the Advanced Integration service definition to the Process Center, select AIS Main in the Business Integration view, right-click, and select Publishto Process Center.
  2. To install the Advanced Integration service implementation on Process Center, first create the archive. Select TranslationService, right-click, and then select Export. When the Export window opens, expand Java EE, select EAR file, and then click Next, as shown in Figure 22.
    Figure 22. Create the archive for the Advanced Integration service implementation
    Screen capture of creating the archive for the Advanced Integration service implementation
    Screen capture of creating the archive for the Advanced Integration service implementation
  3. Now specify the destination of the archive. Either type in the destination or click Browse and select the destination. Click Finish to create the archive.
    Figure 23. EAR Export window
    Screen capture of the EAR Export window
    Screen capture of the EAR Export window
  4. To install and start the TranslationServiceApp.ear application on Process Center, follow the instructions in the previous Deploy the stand-alone module section.
  5. To test the service, follow the instructions in the previous Run the Advanced Integration service sample section. Instead of typing French as the language, type Spanish. This test verifies that you are calling the correct service. You should see the output shown in Figure 24.
    Figure 24. Test results from the new Advanced Integration service implementation
    Screen capture of the Test results from the new Advanced Integration service implementation
    Screen capture of the Test results from the new Advanced Integration service implementation

Publish the Advanced Integration service implementation

The final step is to publish the Advanced Integration service implementation to your source control management system (SCM). Because this step is highly dependent on the type of your SCM and how you intend to build the service, this section describes only what files should be added and outlines some considerations for handling the library project.

Open the Project Explorer view to see the projects in your workspace, as shown in Figure 25. Publish the TranslationService and the AIS_Library, which defines the interface to the Advanced Integration service definition.

Figure 25. Files to publish to the SCM
Screen capture of the files to publish to the SCM
Screen capture of the files to publish to the SCM

Note: TranslationServiceApp and TranslationServiceWeb are generated by Integration Designer and do not need to be published, assuming that your build uses the serviceDeploy command to create the Java Platform, Enterprise Edition archive (which also automatically generates the TranslationServiceApp and TranslationServiceWeb projects).

The AIS_Library project contains the Web Services Description Language (WSDL) code that represents the interface for the Advanced Integration service definition and the XML schema Definition Language files that represent the business object definitions that are used in the interface. This project is the only project that is shared between the Advanced Integration service definition and the Advanced Integration service implementation. If you followed the previous steps, the project is stored in two places: the Process Center and your SCM. Then, your challenge is to ensure that the two copies of the library are kept in sync.

As a rule of thumb, treat the version of the Advanced Integration service library in your SCM as a copy of the library in the Process Center. Any changes to the interface should occur in the Process Center copy and be propagated to your SCM copy.

An alternative approach for storing the Advanced Integration service library

When changes occur to the Advanced Integration service interface, you must propagate the changed library to your SCM. This propagation can be cumbersome, because manual merging of the Process Center Advanced Integration service library into the SCM copy of the Advanced Integration service library is required.

One way to avoid this manual merge is to make a physical copy of the Advanced Integration service library and use that in your Advanced Integration service implementation. To easily determine which Advanced Integration service definition version is present in your SCM, use a simple naming convention so the snapshot version of the toolkit is appended to the Advanced Integration service library project name. For example, complete the following steps.

  1. In the Process Center, take a snapshot of your Advanced Integration service toolkit and name it 3.0.
  2. In Integration Designer, replace the current Advanced Integration service project with the new snapshot, and then copy the AIS_Library to AIS_Library_3.0.
  3. Change the library dependency in the TranslateService project to AIS_Library_3.0, as shown in Figure 26.
    Figure 26. Create an Advanced Integration service library copy
    Screen capture of creating an Advanced Integration service library copy
    Screen capture of creating an Advanced Integration service library copy
  4. Publish the updated TranslationService and the new AIS_Library_3.0 to your SCM.

Now, if the Advanced Integration service definition changes, you can easily bring the Advanced Integration service definition into your workspace from the Process Center and bring your Advanced Integration service implementation from the SCM without conflict. You can repeat steps 1-4 (and possibly use a new version) to update the Advanced Integration service implementation.

Conclusion

This tutorial showed how to implement and use Advanced Integration services. You walked through an example of how to use the new option for creating and deploying an Advanced Integration service to a stand-alone SCA module.

You learned an approach to develop and deploy the Advanced Integration service with Integration Designer, completely independent of the development of toolkits that use it. Now you can apply this approach to your own environment.

Acknowledgments

The authors would like to thank Dan Cho for his review and comments.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware
ArticleID=1027088
ArticleTitle=Develop Advanced Integration services for IBM Business Process Manager V8.5.6
publish-date=01042017