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
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.
|Name||Value (in our scenario)|
|CICS Transaction Gateway host name||demomvs.demopkg.ibm.com|
|CICS Transaction Gateway port number||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:
- Log into Process Designer and create a process application, selecting a name and an acronym.
- 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
Figure 2. Opening the application in the Process Designer
- 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
- Enter the name of your process and click Finish. In our
example, we called the process ProcessWithAIS, as shown in
Figure 4. Naming the BPD
- 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
InputDatacomplex variable of type
DataInwith two fields:
AccountID, both of type String. Then we created an
OutputDatacomplex variable of type
DataOutwith the following fields:
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
- 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
- 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
- Enter a service name such as
callCICSand click Finish, as shown in Figure 8.
Figure 8. Naming the AIS
The Process Designer opens the editor for the Advanced Integration Service definition.
- 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
- When you have finished, close the editor of the
callCICSservice, 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
- Leave all the fields unchanged faults and click Finish, as
shown in Figure 11.
Figure 11. Creating the human service
- 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
- Edit the coaches, as shown in Figures 13 and 14, to show the
Figure 13.Capturing the input information
Figure 14. Displaying the output information
- 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
- 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
- Launch Integration Designer. Specify a workspace folder name, as
shown in Figure 16, and click OK.
Figure 16. Opening Integration Designer
- Click Switch to Process Center perspective, as shown in Figure
Figure 17. Opening Process Center within Integration Designer
- Fill in the required data to log in and click Login, as shown
in Figure 18.
Figure 18. Specifying the credentials for Process Center
- Close the Getting Started window. You should now be on the main Process Center console page.
- 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
Figure 19. Opening the application in the Integration Designer workspace
- 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
- 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
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.
- Right-click the unimplemented callCICS service and select
Implement, as shown in Figure 22.
Figure 22. Starting the implementation of the AIS
- 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
- Click Finish.
- 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
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
- 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. Locating the CICS adapter RAR file
- 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
- Select Resources => Resource Adapters => Resource
Adapters, and click Install RAR, as shown in Figure 27.
Figure 27. Installing the adapter
- In the Install RAR File window, browse to the CICS connector file
from Step 1 (cicseci.rar), then click Next, as shown in Figure
Figure 28. Importing the adapter file
- Accept the default values and click OK, as shown in Figure 29.
Figure 29. Completing the import
- 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
- 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
- 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
- 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
- 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
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.
- 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. Creating the business object for the CICS invocation
- Expand Languages and select COBOL, then click
Next, as shown in Figure 36.
Figure 36. Selecting COBOL as the source for the business object
- 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
- 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
- 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
- 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
- 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
- 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
- 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
- On the New External Service dialog, click Add to add an
operation to the interface.
Figure 44. Adding an operation to invoke
- 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
- 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
- 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
Figure 47. 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
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.
- From the palette, drag and drop a Mediation Flow component
onto your assembly diagram, and rename it as appropriate, as shown in
Figure 49. Adding a mediation flow
- 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
- Right-click MediateIFandData and select Generate
implementation, as shown in Figure 51.
Figure 51. Generating the implementation
- Accept the defaults for the destination folder and click OK,
as shown in Figure 52.
Figure 52. Using the default implementation
- In the editor, click the callCICS invoke operation and select
Service Integration, as shown in Figure 53.
Figure 53. Using the service integration template
- 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
- 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
Figure 55. Using an XSL transformation to mediate the request flow
- 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
- 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
Figure 57. Accessing the properties of the XSL transformation
- In the New XML Map dialog, click Finish.
Figure 58. 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
- 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
- Figure 61 shows the sample transformation we built. When you're done,
save your work.
Figure 61. 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
- 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
- Accept the default value and click Finish, as shown in Figure
Figure 64. Selecting the adapter project for Process Center
- 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
- Select Refresh and Publish, as shown in Figure 66.
Figure 66. Refresh and publish
Test the solution
You're nearly finished!
- Open the IBM Process Portal web application and log in, as shown in
Figure 67. Log in to Process Portal
- Launch a new process by selecting New and choosing the process,
as shown in Figure 68.
Figure 68. Invoking the new BPD
- Click the Run icon to run the human activity, as shown in
Figure 69. Claiming the human task
- 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
- Open the resulting human activity to see the answer coming from your
CICS server, as shown in Figure 71.
Figure 71. Viewing the results
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.
|Copy book file||custprog.zip||1KB|
- IBM Business Process Manager V7.5.1 Information Center.
- developerWorks BPM zone: Get the latest technical resources on IBM BPM solutions, including downloads, demos, articles, tutorials, events, webcasts, and more.
- IBM BPM Journal: Get the latest articles and columns on BPM solutions in this quarterly journal, also available in both Kindle and PDF versions.
Dig deeper into WebSphere on developerWorks
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.