Using Mainframe Applications with Workflows

 

BEA WebLogic Java Adapter for Mainframe (JAM) works with BEA WebLogic Process Integrator to access information or applications on the mainframe. This interaction occurs in two different ways:

• WebLogic Process Integrator workflows invoke mainframe programs

• Mainframe programs initiate WebLogic Process Integrator workflows

 

---

Action List

To use JAM with WebLogic Process Integrator, you must complete the following tasks.

	Your action...	Refer to...
1	Verify prerequisite tasks have been completed.	Prerequisites
2	Verify the setup for the JAM Plug-in for WebLogic Process Integrator.	Task 1: Verifying the JAM Plug-in Setup
3	Set up data translation.	Task 2: Setting Up Data Translation
4	Set up workflow with JAM for mainframe services.	Setting Up the Workflow with JAM for Mainframe Services

 

---

Prerequisites

Before creating WebLogic Process Integrator workflows with JAM, make sure the following tasks have been completed:

	Your action...	Refer to...
1	Install and configure WebLogic Server.	BEA WebLogic Server Installation Guide
2	Install and configure WebLogic Process Integrator.	BEA WebLogic Process Integrator Installation Guide
3	Install and configure WebLogic XML/Non-XML Translator.	BEA WebLogic XML/Non-XML Translator Installation Guide
4	Install and configure WebLogic Java Adapter for Mainframe.	BEA WebLogic Java Adapter for Mainframe Installation Guide
5	Read Release Notes for each product so that you are aware of any special considerations.	BEA WebLogic product documentation
6	Understand the way these products work together.	Understanding WebLogic Process Integrator Interaction with the Mainframe in this guide

 

---

Preparing to Use JAM in Workflow Processing

To use mainframe applications during workflow processing with WebLogic Process Integrator, you must prepare your system. The following tasks must be completed:

• Verifying the JAM Plug-in setup

  This task is required only once.

• Setting up data translation.

  This task must be completed each time a new COBOL copybook is used.

Task 1: Verifying the JAM Plug-in Setup

The JAM Plug-in is a component that allows the JAM gateway to interact with WebLogic Process Integrator. It runs with WebLogic Process Integrator in the WebLogic Server environment. The JAM Plug-in should have been set up during the JAM installation process.

1. If the JAM Plug-in was not properly set up, you may need to add the entries in Listing 2-1 to the WebLogic Process Integrator application definition to the WebLogic Server configuration file (config.xml).

   Warning: Copy the config.xml file and store it in an alternate location as a backup in case the config.xml file you are working with is corrupted during setup.

   Listing 2-1 JAM Plug-in Setup

   <EJBComponent Name="jampi.jar" Targets="myserver"
   	URI="jampi.jar"/> 

   <WebAppComponent Name="com.bea.jam.JamPlugin" 
          	Targets="myserver" URI="jampi.war"/> 

   The WebLogic Server configuration file (config.xml) is located at:

   <bea_home> <install.dir>/config/<domain.name>

   In this address:

   install.dir

   is where WebLogic Process Integrator is installed

   domain.name

   is the domain from which WebLogic Process Integrator is started

   Listing 2-2 shows an example of this address:

   Listing 2-2 Example of config.xml Address

   C:/BEA/WLPI/config/wlpidomainexample

2. Review your server configuration. If the server name is not myserver, the Targets entry needs to be modified with the name of your server.

3. Verify that the WebLogic Process Integrator application configuration section of the WebLogic Server config.xml file contains the entries shown in Listing 2-3. If not, edit the config.xml file with the appropriate entries.

   Listing 2-3 WebLogic Process Integrator Application Configuration Section of the WebLogic Server config.xml

   <Application Deployed="true" Name="WLPI Application" Path="lib">

   <EJBComponent Name="wlpi-mdb-ejb.jar" Targets="myserver" URI="wlpi-mdb-ejb.jar"/>

   															<EJBComponent Name= "repository-ejb.jar"Targets="myserver"URI="repository-ejb.jar"/>

   <EJBComponent Name="wlpi-ejb.jar" Targets="myserver"
   			    URI="wlpi-ejb.jar"DeploymentOrder=0/>

   <EJBComponent Name="wlxtpi.jar" Targets="myserver" URI="wlxtpi.jar"/>

   <WebAppComponent Name= "com.bea.wlxt.WLXTPlugin"Targets="myserver"URI="wlxtpi.war"/>

   <EJBComponent Name="jampi.jar" Targets="myserver" URI="jampi.jar"/>

   <WebAppComponent Name="com.bea.jam.JamPlugin" Targets="myserver"
   URI="jampi.war"/>

   </Application>

Task 2: Setting Up Data Translation

To ensure that workflows operate properly, you must set up your system to enable the different software applications to interact. In order for WebLogic XML/Non-XML Translator to convert XML data to the binary format expected by your mainframe program, a description of the binary format must be created and stored in your WebLogic Process Integrator repository. WebLogic XML/Non-XML Translator Format Builder can be used to create this description. Format Builder imports the COBOL copybook for your mainframe application, and automatically creates a description that details the layout of the COBOL copybook. Using this description, WebLogic XML/Non-XML Translator converts instances of this layout to and from XML.

To set up your system for the required data translation, complete the following steps:

1. Obtain the COBOL copybook(s) or C header file(s) used by your mainframe application. For more information about obtaining the COBOL copybook, refer to the BEA Java Adapter for Mainframe Programming Guide.

2. Import the Copybooks(s) or C header file(s) into the WebLogic Process Integrator repository using the following steps:

   1. Launch the WebLogic XML/Non-XML Translator Format Builder and select Log In from the Repository menu, as shown in Figure 2-1.

      Figure 2-1 WebLogic XML/Non-XML Translator

      
       

   2. From the WLPI Repository Login dialog box, log in as shown in Figure 2-2. Enter your user name and password. If your server is different than the default shown in Figure 2-2, enter your server address.

      Figure 2-2 WLPI Repository Login

      
       
       

   3. From the Tools menu, select Import and COBOL Copybook Importer, as shown in Figure 2-3. If you are working with a C Struct, select C Struct Importer.

      Figure 2-3 WebLogic XML/Non-XML Translator Tools Menu

      
       

   4. Import the copybook files into WebLogic XML/Non-XML Translator by entering the copybook file name in the File Name field. If you are unsure of the location or name of the copybook file, use the Browse feature to locate the correct file. See Figure 2-4. The emprec.cpy is a sample copybook available in the samples.jar file.

      Figure 2-4 WebLogic XML/Non-XML Translator COBOL Copybook Importer Dialog Box

      
       

   5. The COBOL Copybook Importer dialog box displays the default settings, as shown in Figure 2-4. To accept these default settings, click OK. If the default settings are not appropriate for your use, refer to the "Building Format Definitions" section of the BEA WebLogic XML/Non-XML Translator User Guide for more information about other options.

   6. After your copybook has been imported, select Store As from the Repository menu to open the Store Document dialog box.

   7. Enter your name for this document in the Name field, as shown in Figure 2-5. This name is the SCHEMA name you will use to modify the gateway configuration file. Enter appropriate information in the Description and Notes fields, as needed.

   8. Click Store in the Store Document dialog box to save the document in the WebLogic XML/Non-XML Translator Repository.

      Figure 2-5 WebLogic XML/Non-XML Translator Store Document Dialog Box

      
       

   9. From the Tools menu, select Test to open the Format Tester dialog box as shown in Figure 2-6. From the Generate menu, select XML to display a sample of the XML you will use during the creation of your workflow.

      Figure 2-6 Sample XML

      
       

 

---

Setting Up the Workflow with JAM for Mainframe Services

Determine how your workflow will use mainframe services:

• Request mainframe services from WebLogic Process Integrator

• Initiate workflows in WebLogic Process Integrator from the mainframe

Requesting Mainframe Services from the Workflow

To request mainframe services from WebLogic Process Integrator, you must:

• Modify the JAM gateway configuration file (jcrmgw.cfg)

• Add appropriate mainframe actions to tasks contained in the WebLogic Process Integrator workflow template definition

Modify the Gateway Configuration File

The JAM gateway configuration file must have a JC_REMOTE_SERVICE entry for each of the services to be accessed using JAM. This definition must specify the schema that was created in the previous step.

The JAM gateway configuration file is located at:

<bea_home> <install.dir>/config/<domain.name>/jcrmgw.cfg

In this address:

install.dir

is where WebLogic Process Integrator is installed

domain.name

is the domain from which WebLogic Process Integrator was started

To access mainframe applications from a WebLogic Process Integrator workflow, specify each remote service in the JC_REMOTE_SERVICES section of the JAM gateway (jcrmgw.cfg) file. For specific information about configuring the JAM gateway, refer to the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide.

• If the translation schemas for the request and response are the same, you can specify them with a single schema entry for the service as follows:

  SCHEMA=myemployeerecord

• If the translation schemas for the request and reply are different, specify each in the following way:

  INPUTSCHEMA=myemployeerecordin

  INPUTSCHEMA specifies the translation schema for the request sent to the mainframe.

  OUTPUTSCHEMA=myemployeerecordout

  OUTPUTSCHEMA specifies the translation schema for the response received from the mainframe.

Listing 2-4 is an example of the JC_REMOTE_SERVICES section of the jcrmgw.cfg file.

Listing 2-4 JC_REMOTE_SERVICES Example

#----------------------------------------------------------------
*JC_REMOTE_SERVICES
sampleRead		RDOM="CICS4"
		RNAME="DPLDEMOR"
		TRANTIME=10000
		SCHEMA=sample.emprec
sampleUpdate		RDOM="CICS4"
		RNAME="DPLDEMOU"
		TRANTIME=10000
		SCHEMA=sample.emprec
sampleCreate		RDOM="CICS4"
		RNAME="DPLDEMOC"
		TRANTIME=10000
		SCHEMA=sample.emprec

For specific information about configuring the JAM gateway, refer to the WebLogic Java Adapter for Mainframe Configuration and Administration Guide.

Using Mainframe Actions in Workflows

You can design and edit Mainframe Actions used by WebLogic Process Integrator workflows in the following ways:

• Add mainframe actions

• Update mainframe actions

• Delete mainframe actions

• Change the sequence of mainframe actions

Adding Mainframe Actions

Mainframe Actions can be added during design time from the WebLogic Process Integrator Studio Console. The following steps allow you to add a mainframe action:

1. Open an existing or new workflow template definition to which you want to add a mainframe action.

2. From the workflow template definition, double-click the Task node to which you want to add a mainframe action. The Task Properties dialog box displays as shown in Figure 2-7.

   Figure 2-7 Task Properties

   
    

3. In the Task Properties dialog box shown in Figure 2-7, select the appropriate Actions tab to designate when the mainframe action will be executed.

   Determine when the action is executed by selecting the appropriate tab defined in Table 2-1.

   Table 2-1 WebLogic Process Integrator Actions Definitions

   Tab	Description
   Created	The workflow is started and all tasks in the workflow are created.
   Activated	The workflow diagram indicates a task transition has occurred, usually as a result of another task being marked as done or a decision being evaluated. The task is available to be performed.
   Executed	An event has occurred that causes this task to be executed. This usually occurs when a user selects a task in the worklist and executes it, often by double-clicking the task, or when an Execute Task action is performed for that task.
   MarkedDone	The task has been completed. This event usually occurs in response to the execution of a Mark Task as Done action.

   The BEA WebLogic Process Integrator Studio User Guide provides information about the execution of workflows.

4. Click Add to display the Add Action dialog box shown in Figure 2-8.

   Figure 2-8 Adding Mainframe Actions

   
    

5. Double-click the Mainframe Actions folder to expand it. Select Send a mainframe request, and click OK to display the Mainframe Action dialog box.

6. Enter data in the fields as shown in Figure 2-9. A description of the input fields for this dialog box is shown in Table 2-2.

   Figure 2-9 Mainframe Actions Dialog Box

   
    

   Table 2-2 lists the fields used for adding and updating mainframe actions when using WebLogic Java Adapter for Mainframe (JAM) with a WebLogic Process Integrator workflow.

   Table 2-2 Mainframe Action Definitions

   Field	Description
   Mainframe Action Definition
   Service Name	Select the name of a remote service from the drop-down list or enter the name of a new service. This drop-down list displays all the remote services defined in the JAM jcrmgw.cfg file. If you enter the name of a new service, you must be sure to add the service to the JC_REMOTE_SERVICES section of the jcrmgw.cfg file before you can run the workflow.
   Input Schema	Displays the input schema name that corresponds to the Service Name you selected. The schema specified by this field must be created using Format Builder prior to executing this workflow. You may also manually enter a new schema name, but you must define the schema with Format Builder before you can run the workflow. Schemas must be in the repository.
   Output Schema	Displays the output schema name that corresponds to the Service Name you selected. The schema specified by this field must be created using Format Builder prior to executing this workflow. You may also manually enter a new schema name, but you must define the schema with Format Builder before you can run the workflow. Schemas must be in the repository.
   Input Variable	Select an input variable from the drop-down list or manually enter a new variable. This variable contains the XML document that is converted to binary format using the Input Schema and then sent to JAM. The variable must be of type "String" or "XML." If you enter a variable name that does not currently exist, you will be asked if you wish to create it.
   Output Variable	Select an output variable from the drop-down list or manually enter a new variable. This variable is the destination for response data from the mainframe that has been received by the JAM gateway and translated into XML using the output schema. The variable must be of type "String" or "XML." If you enter a variable name that does not currently exist, you will be asked if you wish to create it.
   Notes	Enter your own custom notes about the mainframe action.
   Mainframe Action Buttons
   OK	Saves your mainframe action definition information and closes the Mainframe Action dialog. If any fields are blank, an error message displays and you will be returned to the Mainframe Action dialog. If either variable name specifies a variable that does not exist, a message displays allowing you to add the variable.
   Cancel	Closes the Mainframe Action dialog without saving any mainframe action definition information that you entered.

   
    

7. Click OK. The action is added to the Task Properties dialog box and will be implemented when the workflow is executed.

Updating Mainframe Actions

Mainframe actions can be updated during design time or runtime from the WebLogic Process Integrator Studio Console. The following steps allow you to update a mainframe action:

1. Open an existing workflow template definition that you want to update.

2. From the workflow template definition, double-click the Task node you want to update. The Task Properties dialog box displays.

3. In the Task Properties dialog box shown in Figure 2-7, select the appropriate Actions tab to designate when the mainframe action is executed. The Actions are defined in Table 2-1.

4. Select the Mainframe Action to be updated from the Actions tab.

5. Click Update to display the Update Action dialog box.

6. Modify the fields in the dialog box as needed. Refer to Table 2-1 for the definitions of the Mainframe Action Fields.

7. Click OK to save the changes.

Deleting a Mainframe Action

To delete a mainframe action:

1. Open the existing WebLogic Process Integrator workflow template definition.

2. From the workflow diagram, double-click the Task node for which you want to delete a mainframe action. The Task Properties dialog box displays.

3. Select the desired action in the Actions section of the Task Properties dialog box, and click the Delete button.

4. A confirmation dialog box displays to prevent accidental deletions. Click Yes to confirm the deletion or No to cancel the deletion.

   When an action is deleted, all references to the action are removed. The action is removed from all instances of the workflow, including those currently running.

Changing the Sequence of Mainframe Actions

The sequence of mainframe actions can be changed during design time or run time.

To change the sequence of actions:

1. From your workflow diagram, double-click the Task node for which you want to change the sequence of a mainframe action. The Task Properties dialog box displays.

2. Click on an action in the Actions list.

3. Press the up or down arrow button to move the action's position up or down in the list.

4. Click on OK to save the change to the workflow template definition.

Initiating Workflows from the Mainframe

By working with JAM and WebLogic XML/Non-XML Translator, WebLogic Process Integrator workflows can be initiated from mainframe applications. To initiate workflows from the mainframe, you must:

• Modify the gateway configuration file

• Create a WebLogic Process Integrator workflow with an XML event-driven start node

Example of Initiating a Workflow from the Mainframe

In the following example, a new employee record is created on the mainframe. It is sent to the workflow process to be added the employee database.

The screen data is validated and moved into the employee record copybook. This copybook corresponds to the copybook used to generate the MFL in the WebLogic XML/Non-XML Translator Distributed Program Link (DPL).

The COBOL CICS program in Listing 2-5 illustrates how a workflow may be initiated. The CICS link sends the employee record to the workflow. The SYSID directs the LINK to the correct remote environment, and the PROGRAM name corresponds to the RNAME in the jcrmgw.cfg JC_LOCAL_SERVICES entry.

Listing 2-5 Example of Initiating a Workflow From the Mainframe

Modify the Gateway Configuration File

The JAM gateway configuration file must have a JC_LOCAL_SERVICE entry for each of the services in your configuration. This definition must specify the schema that was created when you set up data translation.

To enable the mainframe to initiate a workflow in WebLogic Process Integrator specify each local service in the JC_LOCAL_SERVICES section of the jcrmgw.cfg file. Each JC_LOCAL_SERVICE that is to work within WebLogic Process Integrator must specify JAMToWLPIHome as its name. This name specifies the Home Interface of the EJB delivered with the JAM plug-in. Within the JAMToWLPIHome service, specify the translation schema to be applied to each service using the schema keyword in the following way:

SCHEMA = emprec

Listing 2-6 is an example of the JC_LOCAL_SERVICES section of the jcrmgw.cfg file.

Listing 2-6 JC_LOCAL_SERVICES Example

#----------------------------------------------------------------
*JC_LOCAL_SERVICES
JAMToWLPIHome		RNAME='DPL1SVR'
SCHEMA=emprec

For specific information about configuring the JAM gateway, refer to the BEA WebLogic Java Adapter for Mainframe Configuration and Administration Guide.

Edit the Workflow Start Node

For a mainframe event or action to initiate a workflow, it must be included in the Start Node of the WebLogic Process Integrator workflow. To edit the workflow Start Node to initiate the workflow, complete the following steps.

1. Double click on the Start Node you wish to edit.

2. In the Start Properties dialog box, shown in Figure 2-10, select Event as the start method for the workflow.

   Figure 2-10 Start Node

   
    

3. In the Document/Type field, enter the root element name of the XML document. To obtain this name, view the XML document structure in the WebLogic XML/Non-XML Translator Format Builder.

4. To define the variable, select the variable tab and click Add.

5. In the Workflow Variable Assignment dialog box, shown in Figure 2-11, enter the name you want to assign to the variable. You may want to use an XPath function to select fields from the XML. For more information about XPath functions, refer to the BEA WebLogic Process Integrator Studio Guide.

   Figure 2-11 Workflow Variable Assignment Dialog Box

   
    

The workflow will be started automatically when data is received from the mainframe.