Integrating business process applications with CICS in IBM Business Process Manager Advanced V7.5

Calling a JCA-CICS adapter from a process using an Advanced Integration Service

In this article, you'll learn how to use the JCA Adapter for CICS® to integrate a BPMN process created with the IBM® Process Designer with a CICS system without having to write any Java™ code. To achieve this integration, you'll create an Advanced Integration Service (AIS) in IBM Integration Designer. This content is part of the IBM Business Process Management Journal.

Marco Dragoni (marco_dragoni@it.ibm.com), Senior IT Specialist , IBM

Marco Dragoni photoMarco Dragoni has been a Senior IT Specialist in IBM Software Group for seven years. He joined IBM in 1990. He worked in operating system support (AIX), then as a network specialist, and is now a BPM client technical professional.



Pierangelo Giusta (p_giusta@it.ibm.com), Senior IT Specialist, IBM

Pierangelo GiustaPierangelo Giusta is a Senior IT Specialist in Italy. He has been with IBM for 26 years, in various technical positions, and has been with the IBM Software Group since 1995. He holds a degree in Electronic Engineering from the University of Genova, Italy. His main area of expertise is communication and messaging infrastructure, with special emphasis on WebSphere MQ, WebSphere Message Broker, and WebSphere ESB. In the past, he also worked in the area of IMS.



Michele Chilanti (chilanti@us.ibm.com), Consulting IT Specialist, IBM

Author photoMichele Chilanti is a Client Technical Professional with the World Wide Business Process Management Technical Sales organization at IBM. He has over 20 years of experience working with a variety of products and software technologies, especially in the areas of business process modeling, implementation, and deployment of Business Process Management and services-oriented solutions. Michele presents regularly at technical conferences worldwide, and has authored or co-authored a number of technical publications.



15 February 2012

Overview

Most business process solutions require some form of integration with backend systems. One of the most popular mainframe backends is CICS. This article shows you how to integrate a BPMN process developed with IBM Process Designer with a CICS backend system, using the JCA Adapter for CICS. The integration is achieved using an advanced integration service (AIS) developed using IBM Integration Designer. The target runtime environment is IBM Business Process Manager V7.5, complemented by a CICS environment hosted on a z/OS® server. The CICS system front-end is the CICS Transaction Gateway (CTG), which allows client applications to access the backend. Figure 1 shows the architecture of the scenario.

Figure 1. Scenario architecture
Scenario architecture

(See a larger version of Figure 1.)

In order to interact with a CICS server, you need to collect some information about the configuration of the execution server. Table 1 shows the required parameters.

NameValue (in our scenario)
CICS Transaction Gateway host name demomvs.demopkg.ibm.com
CICS Transaction Gateway port number 12006
CTG connectionURL tcp://demomvs.demopkg.ibm.com:12006
CICS Region (serverName) CICSACB2
CICS Program Name CUSTPROG

We'll discuss these parameters in more detail later in this article.


Build a simple process in Process Designer

We start by creating a simple BPMN process in the Process Designer tool. We won't cover every single step; however, you can review the complete process by unzipping and importing the project file (provided for download with this article) into your local Process Designer. To build the process, complete the following steps:

  1. Log into Process Designer and create a process application, selecting a name and an acronym.
  2. Once the application is created, click Open in Designer to start editing your Business Process Definition (BPD). In our example, we created a Customer Inquiry process application, as shown in Figure 2.
    Figure 2. Opening the application in the Process Designer
    Opening the application in Process Designer
  3. In the Designer view, expand the plus sign (+) to the right of Processes, and select Business Process Definition in the Create New context menu, as shown in Figure 3.
    Figure 3. Creating a new BPD
    Creating a new BPD
  4. Enter the name of your process and click Finish. In our example, we called the process ProcessWithAIS, as shown in Figure 4.
    Figure 4. Naming the BPD
    Naming the BPD
  5. Switch to the Variables tab and create two private process variables as appropriate for your use case. As shown in Figure 5, for our example, we created an InputData complex variable of type DataIn with two fields: RequestType and AccountID, both of type String. Then we created an OutputData complex variable of type DataOut with the following fields: AccountID, FirstName, LastName, Company, and Address. All of the fields are of type String. The first variable stores the input for the CICS services, while the second variable stores the response.

    Don't forget to check the Has default flag for the input variable.

    Figure 5. Adding the necessary variables
    Adding the necessary variables
  6. Once you're done creating the variables, switch to the Diagram tab, and create the process flow. Drag and drop an activity into your process diagram and position it between the Start and the End node, then link the activity with the available node. The resulting diagram should look like Figure 6.
    Figure 6. Creating a simple process flow
    Creating a simple process flow
  7. From the navigation menu of the Designer view, click the plus sign (+) by Implementation and select Advanced Integration Service, as shown in Figure 7.
    Figure 7. Adding the Advanced Integration Service
    Adding the Advanced Integration Service
  8. Enter a service name such as callCICS and click Finish, as shown in Figure 8.
    Figure 8. Naming the AIS
    Naming the AIS
    The Process Designer opens the editor for the Advanced Integration Service definition.
  9. In the main editor pane, add an Input and an Output variable. One common practice is to use the same variable names and types as for the process variables. In that case, no new variable is created, as shown in Figure 9.
    Figure 9. Using the same variable for input and output
    Using the same variable for input and output
  10. When you have finished, close the editor of the callCICS service, and go back to editing your process definition. Right-click on the only available task, Ask Data, and select Activity Wizard, as shown in Figure 10.
    Figure 10. Using the Activity wizard to implement the human service
    Using the Activity wizard to implement the human service
  11. Leave all the fields unchanged faults and click Finish, as shown in Figure 11.
    Figure 11. Creating the human service
    Creating the human service
  12. Double-click the Ask Data task, then start editing the diagram, adding another Coach and a nested service in order to build a similar flow, as shown in Figure 12.
    Figure 12. The human service flow
    The human service flow
  13. Edit the coaches, as shown in Figures 13 and 14, to show the appropriate data.
    Figure 13.Capturing the input information
    Capturing the input information
    Figure 14. Displaying the output information
    Displaying the output information
  14. Associate the previously defined callCICS AIS service and check the Data Mapping tab to verify that the input and output are correctly set.
    Figure 15. The completed human service
    The completed human service
  15. Save your work.

The process definition is updated in the Process Center. You can now minimize the Process Designer.


Build the AIS with Integration Designer

In order to create the implementation of the AIS we just defined in the Process Designer, we'll use the Integration Designer tool.

Open and synchronize your Integration Designer environment

  1. Launch Integration Designer. Specify a workspace folder name, as shown in Figure 16, and click OK.
    Figure 16. Opening Integration Designer
    Opening Integration Designer
  2. Click Switch to Process Center perspective, as shown in Figure 17.
    Figure 17. Opening Process Center within Integration Designer
    Opening Process Center within Integration Designer
  3. Fill in the required data to log in and click Login, as shown in Figure 18.
    Figure 18. Specifying the credentials for Process Center
    Specifying the credentials for Process Center
  4. Close the Getting Started window. You should now be on the main Process Center console page.
  5. In the Process Apps tab, you should see the application you just created in the Process Designer. In our example, it is called Customer Inquiry. Click Open in workspace, as shown in Figure 19. This imports the definition of the AIS you need to implement.
    Figure 19. Opening the application in the Integration Designer workspace
    Opening the application in the Integration Designer workspace
  6. The workspace build process starts. Wait until it is complete, then select the detailed view, as shown in Figure 20.
    Figure 20. Switching to detailed mode
    Switching to detailed mode
  7. Now, open all the elements in the Business Integration menu to check that the necessary artifacts have been imported from Process Center into your workspace. Your workspace should look similar to Figure 21.
    Figure 21. Business process application elements in the workspace
    Business process application elements in the workspac
    Notice that there is an unimplemented callCICS service under Advanced Integration Services. In the next section, you'll implement that service.

Implement the callCICS service

In this section, you'll complete the implementation of the AIS.

  1. Right-click the unimplemented callCICS service and select Implement, as shown in Figure 22.
    Figure 22. Starting the implementation of the AIS
    Starting the implementation of the AIS
  2. Select Empty implementation, as shown in Figure 23. This choice allows you to use a mediation flow to implement the service. You'll add the mediation later on. The idea is to use a mediation to map the data between the process and the CICS service.
    Figure 23. Selecting "Empty implementation" allows you to pick a mediation later on
    Selecting empty implementation allows you to pick a mediation later on
  3. Click Finish.
  4. The Assembly Diagram editor opens. Notice that an SCA export called callCICS has been added to your assembly diagram, as shown in Figure 24.
    Figure 24. An export is created for the AIS
    An export is created for the AIS
    The export allows the BPMN process to invoke this component. However, it is not yet connected to any implementation because you selected Empty Implementation.

Define the resources in the Process Server runtime

  1. Before continuing with the implementation, you need to copy the CICS connector into the Integration Designer folder. We recommend you use exactly the same version of the cicseci.rar connector file that is used by the CTG server (make sure that you get the XA version if you are using a CICS transaction). Your CICS administrator should be able to provide you with the correct connector file. Ensuring you have the right version of the connector file prevents possible runtime errors. Copy the file into the Integration Designer installation folder (C:\IBM\IntegrationDesigner\v7.5\ResourceAdapters\cics15), as shown in Figure 25.
    Figure 25. Locating the CICS adapter RAR file
    Locating the CICS adapter RAR file
  2. Now you need to configure the Process Server hosted in the Process Center. Point your browser to http://localhost:9060/ibm/console to open the administrative console. If required, accept the certificate warning and specify the username and password defined during the installation of your environment, then click Log in, as shown in Figure 26.
    Figure 26. Logging on to the Admin Console
    Logging on to the Admin Console
  3. Select Resources => Resource Adapters => Resource Adapters, and click Install RAR, as shown in Figure 27.
    Figure 27. Installing the adapter
    Installing the adapter
  4. In the Install RAR File window, browse to the CICS connector file from Step 1 (cicseci.rar), then click Next, as shown in Figure 28.
    Figure 28. Importing the adapter file
    Importing the adapter file
  5. Accept the default values and click OK, as shown in Figure 29.
    Figure 29. Completing the import
    Completing the import
  6. You need a connection factory to enable connectivity through the CICS adapter. In the navigation on the left, select J2C connection factories, select the appropriate Scope (usually the Node), and click New, as shown in Figure 30.
    Figure 30. Creating the J2C Connection Factory for CICS
    Creating the J2C Connection Factory for CICS
  7. In the J2C connection factories dialog, select the ECIResourceAdapter for Provider. Give it a name and a JNDI name, as shown in Figure 31. Take note of the JNDI name, since it will be referenced by the Import node responsible for calling the CICS program. When you have finished, click Apply.
    Figure 31. Associating the new Connection Factory with the adapter
    Associating the new Connection Factory with the adapter
  8. Now, select Custom Properties to enter some additional information required to invoke CICS, as shown in Figure 32.
    Figure 32. Accessing the custom properties of the Connection Factory
    Accessing the custom properties of the Connection Factory
  9. The number of fields you need to fill out really depends on the specifics of your environment. In most cases, the following fields, highlight in Figure 33 are sufficient:
    • ConnectionURL defines the server running the CTG server
    • PortNumber is the CTG port
    • ServerName is the CICS Applid name
    Figure 33. Specifying the custom properties for the Connection Factory
    Specifying the custom properties for the Connection Factory
  10. Save your work to the master configuration and log out of the console, as shown in Figure 34.
    Figure 34. Logging out of the Admin Console
    Logging out of the Admin Console

Add the CICS import to your assembly diagram

Now you're ready to create an Import in the assembly diagram that points to the CICS server. But before you do that, you need to create the data structure (business object) that corresponds to the data being exchanged with CICS. To do so, you can use a COBOL copybook, which should be provided to you by your CICS administrator.

  1. In Integration Designer, create a new business object by importing the CICS Copy COBOL .cpy provided to you. Normally, you would create this object in a library. However, due to a limitation of the first release of Integration Designer, you should create these objects in the same integration project that hosts the assembly diagram. Since this limitation is going to be removed soon, we'll use the library approach in this article. Right-click the implementation module created during the synchronization with the Process Center and select New => Business Object from External Data, as shown in Figure 35.
    Figure 35. Creating the business object for the CICS invocation
    Creating the business object for the CICS invocation
  2. Expand Languages and select COBOL, then click Next, as shown in Figure 36.
    Figure 36. Selecting COBOL as the source for the business object
    Selecting COBOL as the source for the business object
  3. Browse to the location where your COBOL copybook is located, and select it, then click Next, as shown in Figure 37.
    Figure 37. Importing the COBOL copybook
    Importing the COBOL copybook
  4. In the Select Data Structures dialog, shown in Figure 38, you must select precisely the correct platform that hosts your CTG and make sure the code page is correctly specified. Failing to do so will cause errors at execution time. In our case, CICS is hosted on a mainframe system (z/OS®) located in the United States, so the code page is set to IBM-037 (US English). After specifying the platform and code page, click Find to discover the data structures contained in your copybook file, then click Next.
    Figure 38. Selecting the appropriate backend and code page
    Selecting the appropriate backend and code page
  5. In the Generate Business Objects dialog, verify the settings and click Finish, as shown in Figure 39.
    Figure 39. Completing the definition of the business object
    Completing the definition of the business object
  6. Now that you have the required business object, you can create the Import. In the Assembly Diagram editor, expand Outbound Adapters in the palette and drag and drop the CICS icon onto the canvas, as shown in Figure 40.
    Figure 40. Creating the CICS import using drag-and-drop
    Creating the CICS import using drag-and-drop
  7. Next select the adapter, making sure to choose the correct version. Integration Designer comes with several adapters at different levels. These are normally stored in a library called <IID Install Dir>/ResourceAdapters. If the adapter used by your server is not among those available, you may want to add it to the directory. Select the correct RAR file and click the Next, as shown in Figure 41.
    Figure 41. Selecting the right adapter for the import
    Selecting the right adapter for the import
  8. On the Import a RAR File dialog, click Next again, as shown in Figure 42(normally the defaults are OK).
    Figure 42. Pointing to the correct RAR file
    Pointing to the correct RAR file
  9. On the Security and Configuration Properties dialog, specify the JNDI name of your J2C Connection Factory, as shown in Figure 43, and click Next. In our example, we're using predefined properties, which is the recommended approach.
    Figure 43. Associating the import with the Connection Factory you created
    Associating the import with the Connection Factory you created
  10. On the New External Service dialog, click Add to add an operation to the interface.
    Figure 44. Adding an operation to invoke
    Adding an operation to invoke
  11. Specify a name for the operation, as shown in Figure 45. In our example, we use invokeCICS. For Input type browse to and select the BO created by the import external data of the .cpy file. Our example uses the same data structure for both input and output, but you can select a different output, if desired. When you're done, click Finish to return to the New External Service dialog.
    Figure 45. Specifying input and output
    Specifying input and output
  12. Here you'll need a piece of information that can be obtained from your z/OS administrator - the program name. This information is called Function name in the dialog, but CICS administrators may be more familiar with the program name terminology. Enter the function name, as shown in Figure 46. Leave -1 for the Commarea length field. This means that the entire data structure represented by business object will be passed to CICS as the program COMMAREA. Click Next.
    Figure 46. Specifying function name and commarea length
    Specifying function name and commarea length
  13. The final dialog, shown in Figure 47, shows a summary and the name of the import component that will be created in your assembly diagram. If needed, change this name based on your policies. Do not select Deploy connector with module because you have already installed the connector in your Process Server runtime. Click Finish.
    Figure 47. Ensuring "Deploy connector with module" is not selected
    Ensuring Deploy connector with module is not selected

Your assembly diagram now includes the CICSImport component, as shown in Figure 48.

Figure 48. The import appears in the assembly diagram
The import appears in the assembly diagram

Add the mediation component

Now you can add the mediation flow that is needed to map the data exchanged by the interface of the BPMN process and the interface exposed by the CICS transaction.

  1. From the palette, drag and drop a Mediation Flow component onto your assembly diagram, and rename it as appropriate, as shown in Figure 49.
    Figure 49. Adding a mediation flow
    Adding a mediation flow
  2. Connect the callCICS export component to the MediateIFandData, and then connect the latter to the CICSImport import component. Your assembly diagram should look like Figure 50.
    Figure 50. Wiring the various components
    Wiring the various components
    6
  3. Right-click MediateIFandData and select Generate implementation, as shown in Figure 51.
    Figure 51. Generating the implementation
    Generating the implementation
  4. Accept the defaults for the destination folder and click OK, as shown in Figure 52.
    Figure 52. Using the default implementation
    Using the default implementation
  5. In the editor, click the callCICS invoke operation and select Service Integration, as shown in Figure 53.
    Figure 53. Using the service integration template
    Using the service integration template
  6. In the Select the Services dialog, click Add and select the target service (invokeCICS in our example), then click OK, as shown in Figure 54.
    Figure 54. Setting the target service
    Setting the target service
  7. Start editing your mediation flow. You'll build the request flow first. Later, you'll complete the response flow. Connect the callCICS element with the CICSImportPartner, as shown in Figure 54. Since the two data types are incompatible, you'll be prompted to select some type of data transformation. Select an XSLT transformation primitive.
    Figure 55. Using an XSL transformation to mediate the request flow
    Using an XSL transformation to mediate the request flow
  8. A new element appears on your Request flow, representing the XSLT operation, as shown in Figure 56.
    Figure 56. The XSL transformation shows up on the diagram
    The XSL transformation shows up on the diagram
  9. Click the new XSL transformation element, and select the Properties tab, then select Details, as shown in Figure 57. Click New to start creating your transformation file.
    Figure 57. Accessing the properties of the XSL transformation
    Accessing the properties of the XSL transformation
  10. In the New XML Map dialog, click Finish.
    Figure 58. Creating a new map
    Creating a new map

    Figure 59 shows the mapping implementation for the example. As you can see, it's fairly simple.

    Figure 59. Defining the mapping
    Defining the mapping
  11. Save your work and exit the XML Transformation editor. Switch to the Response tab, shown in Figure 60, and start building a new transformation to map the CICS program response to the data expected by the process.
    Figure 60. Using XSL for the response as well
    Using XSL for the response as well
  12. Figure 61 shows the sample transformation we built. When you're done, save your work.
    Figure 61. The response map
    The response map

Associate the new module with the Process Center and publish it

While working in Integration Designer, you were not connected to the Process Center. Even when you saved your development work, you were saving to the local file system, not to the Process Center.

Furthermore, while in Integration Designer, you create a new project cicseci to gather CICS adapter information. The Process Center has no knowledge of this project.

You need to align your changes with the Process Center. The need for this alignment is highlighted in the Problem tab, as shown in Figure 62.

Figure 62. Error on Problem tab
Error on Problem tab
  1. Right-click the cicseci module and select Associate with Process Center, as shown in Figure 63.
    Figure 63. Make the adapter visible to Process Center
    Make the adapter visible to Process Center
  2. Accept the default value and click Finish, as shown in Figure 64.
    Figure 64. Selecting the adapter project for Process Center
    Selecting the adapter project for Process Center
  3. The error is now resolved, and the Process Center now knows about the cicseci project. However, the alignment is not completed until you publish the changes in your Integration Designer workspace to the Process Center. To do this, right-click the main module, as shown in Figure 65.
    Figure 65. Publishing the project to Process Center
    Publishing the project to Process Center
  4. Select Refresh and Publish, as shown in Figure 66.
    Figure 66. Refresh and publish
    Refresh and publish

Test the solution

You're nearly finished!

  1. Open the IBM Process Portal web application and log in, as shown in Figure 67.
    Figure 67. Log in to Process Portal
    Log in to Process Portal
  2. Launch a new process by selecting New and choosing the process, as shown in Figure 68.
    Figure 68. Invoking the new BPD
    Invoking the new BPD
  3. Click the Run icon to run the human activity, as shown in Figure 69.
    Figure 69. Claiming the human task
    Claiming the human task
  4. Specify the Account ID to call the CICS program, as shown in Figure 70, and click OK.
    Figure 70. Specifying the input parameters for CICS
    Specifying the input parameters for CICS
  5. Open the resulting human activity to see the answer coming from your CICS server, as shown in Figure 71.
    Figure 71. Viewing the results
    Viewing the results

Conclusion

After completing the steps in this article, you have learned how to develop a business process calling a CICS program without having to write any Java code. The sample use case showed how development productivity can be increased by reducing the time spent on creating an integration solution with backend systems.


Downloads

DescriptionNameSize
Project fileCICSProcess_AISV1.zip1.6MB
Copy book filecustprog.zip1KB

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=792972
ArticleTitle=Integrating business process applications with CICS in IBM Business Process Manager Advanced V7.5
publish-date=02152012