Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy
WebLogic Java Adapter for Mainframe User Guide Doc Home | BEA WebLogic Java Adapter for Mainframe User Guide | Previous Topic | Next Topic | Contents | Index

Using BEA WebLogic Process Integrator with JAM

WebLogic Process Integrator is a process modeling tool and workflow environment that combines the functions of static data and server administration, workflow definition, and workflow monitoring.

WebLogic Process Integrator may be used with JAM to provide the following key features:

- Automatically routes any type of information to the right person at the right time.

- Takes full advantage of "push technology" that allows WebLogic Process Integrator to process most of an organization's work according to complex, intelligent business rules; it flags only those exceptions that require human intervention.

- Uses a breakthrough embedded workflow-enabling approach that is written in 100% pure Java.

This section discusses the following topics:

- WebLogic Process Integrator Overview

- WebLogic Process Integrator Architecture

- Integration with JAM

WebLogic Process Integrator Overview

WebLogic Process Integrator is a Java implementation of a workflow management system. A workflow management system has been defined as one that "defines, manages, and executes workflows through the execution of software whose order of execution is driven by a computer representation of the workflow logic."

Such a system automates a business process by merging the sequence of activities and invoking the appropriate resources required by the various activities or steps. Individual business processes may have life cycles ranging from minutes to days (or longer), depending on the complexity and duration of the various constituent activities. To achieve this, a workflow management system must provide support in four broad functional areas:

- Workflow definition-Capturing the definition of the business process (workflow).

- Workflow execution-Managing the execution of workflow processes in an operational environment, sequencing the various activities to be performed.

- Workflow monitoring-Monitoring the status of workflow processes and dynamically configuring the run-time controller.

- Data administration-Managing organizations, users, and roles, rerouting tasks when needed, and maintaining business workflow calendars.

WebLogic Process Integrator Architecture

At the center of the WebLogic Process Integrator architecture is the Process Engine, which serves as the run-time controller and is responsible for keeping track of workflow instances and managing the execution of workflows. The high-performance WebLogic Process Integrator workflow engine has been developed using a breakthrough embedded workflow-enabling approach that is written in 100% pure Java.

The WebLogic Process Integrator data and server administration facility allows users to administer components of the WebLogic Process Integrator server and database. More specifically, it allows users to maintain functions such as adding, updating, deleting users, roles, and organizations; disconnecting users and shutting down the server, rerouting tasks from one user to another, and creating calendars that are used in workflow definition.

The WebLogic Process Integrator workflow definition facility allows users to graphically create and edit workflows, mapping out the tasks in the workflow and the business rules that must be followed. Workflow definitions are used as templates, which can be used to create multiple workflow instances.

The WebLogic Process Integrator workflow monitor facility allows users to monitor and modify workflows. More specifically, it allows users to perform functions such as displaying the status of workflow instances, modifying the tasks associated with a workflow instance (for example, re-assigning work tasks or forcing work to be re-done), creating a variety of customized reports on workload and statistical data, and viewing a user or role worklist in order to dynamically maintain workflows.

Finally, the WebLogic Process Integrator worklist facility provides users with a list of tasks describing work currently assigned to them (or the roles to which they belong) and provides the means for users to select and perform those tasks.

The following diagram illustrates the WebLogic Process Integrator architecture.

Figure 8-1 WebLogic Process Integrator Architecture

Integration with JAM

When using WebLogic Process Integrator with JAM, the WebLogic Process Integrator functions vary depending upon the type of request:

- WebLogic Process Integrator to Mainframe-Request originating in WebLogic Process Integrator sent to JAM for service in a mainframe application.

- Mainframe to WebLogic Process Integrator-Requests originating from the mainframe sent to JAM for service in WebLogic Process Integrator.

JAM's mechanisms for implementing both WebLogic Process Integrator to mainframe and mainframe to WebLogic Process Integrator requests have been tailored to the capabilities of WebLogic Process Integrator. WebLogic Process Integrator to mainframe requests make use of an object-based interface. Mainframe to WebLogic Process Integrator requests make use of an XML event interface.

The WebLogic Process Integrator configuration for JAM requires several steps to transfer dataview objects to and from the mainframe. A dataview object, a data helper object, and a session object must be created. The dataview object is first instatiated through a business operation for a java class. The instantiated dataview object is then passed as a parameter to a datahelper method that permits set operations to be performed. On set operations the datahelper object updates the dataview object. An EJB session variable, which is a new WebLogic Process Integrator data type, is instantiated with an ApplicationView.create() call. Finally, an EJB method call to the invoke() method is made using the session variable for the EJB instance. The service name and the dataview are passed as parameters.

WebLogic Process Integrator to Mainframe Requests

WebLogic Process Integrator to mainframe requests are the most frequent type of communication. In a WebLogic Process Integrator to mainframe request, a workflow requires a service from the mainframe application. The invocation of a mainframe application is essentially a two step process: the input message required by the remote application is created and the service is invoked.

JAM facilitates this interaction with the following tools:

- eGen COBOL utility

  The eGen portion of JAM can generate an additional class that is required to facilitate data creation within a workflow. This additional class is generically known as a "document holder." The document being held is the message required for the mainframe service. eGen creates a document holder as part of the code generation from the mainframe COBOL copybook.

- EJB called ApplicationView

  JAM also uses an EJB, called ApplicationView, that matches the WebLogic Process Integrator service invocation with the eGen client that packages the service request for the JAM gateway.

Using the eGen COBOL Utility for WebLogic Process Integrator to Mainframe Requests

The general process for using JAM with WebLogic Process Integrator for WebLogic Process Integrator to mainframe requests is to run the eGen COBOL utility with the mainframe COBOL copybook and the support xml keywords in the egen script. This process results in the standard eGen/JAM output of java source for client and dataview. The following new outputs are provided:

- A document holder for use in WebLogic Process Integrator

- An XML Schema for use by any other application that may want to send data to JAM via XML

The compiled version of the document holder is provided to the workflow developer, while the client and dataview is deployed in the WebLogic server the way JAM clients currently are deployed. Both the dataview and document holder classes must be compiled and deployed in the WebLogic Server where WebLogic Process Integrator is installed and these classes must be on the WEBLOGICCLASSPATH for WebLogic Server 5.1 and the CLASSPATH for WebLogic Server 6.0. Refer to Developing Java Applications for further details on developing and deploying applications using JAM.

Workflow Development for WebLogic Process Integrator to Mainframe Requests

The document holder provides the workflow developer with methods to instantiate and populate a document object for use in a mainframe service request.

Following is the general sequence of activities for workflow development:

1. Define business operations to allow access to the JAM components.

   1. Define business operations for creating a new empty document.

   2. Define business operations for all of the methods on the document holder object. These will allow you to both set these fields and get their current values.

   3. Define business operations for invoking the ApplicationView EJB.

2. Use the defined operations within your workflow template.

   1. Create a new empty document.

   2. Set the fields within the document as required by your mainframe application.

   3. Acquire access to the ApplicationView EJB and invoke the desired method on it.

   4. Get data from the fields in the returned document.

This general process could encompass a large number of workflow operations depending on the complexity of the data. The workflow could be manually started, in which case the factory invocation could be specified in a start node. The workflow could be initiated by an XML event where the event provided the input data to populate the document object for use in the mainframe request.

The general process for using JAM with WebLogic Process Integrator for WebLogic Process Integrator to mainframe requests is illustrated in the following diagram.

Figure 8-2 WebLogic Process Integrator to Mainframe Requests from WebLogic Process Integrator

In the above figure, the Document Holder is a lightweight class for use with WebLogic Process Integrator operations. It provides a document factory for creating new document instances. The document instance is passed in to the document holder constructor when the document holder methods are used as WebLogic Process Integrator business operations. Document holder methods forward requests to actual document methods. The actual document is passed on an application view service call.

Mainframe to WebLogic Process Integrator Requests

Mainframe to WebLogic Process Integrator requests to WebLogic Process Integrator are asynchronous requests. An application used to initiate a workflow should be capable of 'request only' processing.

The general process for using JAM with WebLogic Process Integrator for Mainframe to WebLogic Process Integrator requests is illustrated in the following diagram.

Figure 8-3 Mainframe to WebLogic Process Integrator Requests to WebLogic Process Integrator

In the above figure, MyTPName is received from the mainframe. The local service name is obtained from the JCRMGW.CFG file. JAMToJMS is registered in JNDI with the local service name. The JAMToJMS EJB uses a schema name to construct a data view to convert mainframe data into XML. XML is then posted to a JMS topic found in the deployment descriptor.

Example of JAM Application Integrated with WebLogic Process Integrator

This application shows an example of JAM integration with WebLogic Process Integrator. The scenario illustrates the creation of an employee record on the mainframe. This record is then read back into WebLogic Process Integrator and selected fields are extracted and stored in WebLogic Process Integrator variables. Refer to the JAM and WebLogic Process Integrator documentation for issues of operation and configuration.

This in no way is a complete illustration of WebLogic Process Integrator usage, but it does provide a starting point for constructing real workflows that interact with a JAM gateway using eGen client EJB's. Refer to your WebLogic Process Integrator documentation for detailed information about using WebLogic Process Integrator.

Note: Integration of JAM with WebLogic Process Integrator as shown in this example only works with WebLogic Process Integrator 1.2.1 and WebLogic Server 5.1.

Task 1: Define Business Operations for the Create Employee Record Example

For this task, you will define the business operations required to create an employee record.

Note: You must have used eGen COBOL to generate both your dataview and helper class, compiled the generated code, and deployed them on the classpath for the instance of WebLogic Server that is running WebLogic Process Integrator before you can define your business operations.

Step 1: Set Up Create New Employee Record Object

Refer to "Defining a Business Operation" in the BEA WebLogic Process Integrator Studio Guide for detailed information about setting up Business Operations.

Perform the following steps to set up your first business operation:

1. Start WebLogic Process Integrator Studio and select Configuration->Business Operations to display the Business Operations dialog box where you will define your first Business Operation.

2. From the Business Operations dialog box, click Add to add a new business operation.

3. The Define Business Operation dialog box displays. Enter a name in the Business Operation Name text box, in this case enter Create empRecData Object.

4. The Add Business Operation process can accept methods from an EJB or a Java Class. Because the JAM Data Helpers are classes, select the Java Class option and click the Set button.

5. The Java Class Name dialog box displays.

   Enter the Java Class Name here. For this sample application the Java Class Name is empRecDataHelper.

   This is the fully qualified class name including the complete package name as specified in the eGen script that created the data helper class. In this example, a package was not specified in the eGen script, so no package is required in this dialog box. The class specified here must be located on the WebLogic Server CLASSPATH.

6. Click OK and the Define Business Operation dialog box redisplays with the Java class name displayed in the Fully Qualified Java Class Name text box.

   The Define Business Operation dialog box has a pull-down list of all of the available Java class methods that can be called when the business operation is invoked. In this example, select the Data Factory method named newXml, which is the default constructor type method for this sample application. This method must be used first in the workflow to create a new empRecData object that can then be used for the other business operations.

7. Now you will use the same procedure as in Steps 2 through 7 to define a second Business Operation that constructs a helper object. Name your new business operation Create empRecDataHelper object.

   Once again specify the empRecDataHelper class, but this time select the method named empRecDataHelper(java.lang.Object o) from the pull-down list.

   This time you will need to specify a name for the method parameter. Select the parameter from the Parameters list in the lower half of the dialog box and then click the Update button. Name the parameter dataview.

   Click OK to complete the definition.

Step 2: Set Up Data Accessor Business Operations

In this step, you will set up additional business operations for accessing the data required to create an employee record. When you are through, you will have a list of business operations similar to the following:

Definine a new business operation to access data for the employee's first name:

1. On the Define Business Operation dialog box, enter set employee first name in the Business Operation Name text box.

2. Select the Java Class option and click Set to display the Java Class Name dialog box.

3. Enter the Java Class Name, which is empRecDataHelper as described in the sixth task of Step 1: Set Up Create New Employee Record Object. Click OK to return to the Define Business Operation dialog box.

4. Use the Method to Call drop-down list to select a method. When the method you select is a set function, the Parameters list in the lower half of the dialog box shows one parameter. You must specify a name for this parameter by selecting it then clicking the Update button. Choose descriptive names, for instance, the setFirstname method should be given a parameter name like setFirstname.

5. Continue adding methods until all accessors have been set up as business operations. Following is a sample list of business operations that you might set up. In each case, the Business Operation Name and the Method to Call parameter are entered to reflect a descriptive term for the method and parameter. The Fully Qualified Java Class Name for all the accessors is empRecDataHelper.

   ####

   Fully Qualified Java Class Name | Business Operation Name | Method to Call
   --- | --- | ---
   empRecDataHelper | GetFirstName | getEmpNameFirst
   empRecDataHelper | GetMiddleInitial | getEmpNameMI
   empRecDataHelper | GetLastName | getEmpNameLast
   empRecDataHelper | GetSSN | getEmpSsn
   empRecDataHelper | GetState | getEmpAddrST
   empRecDataHelper | GetStreet | getEmpAddrStreet
   empRecDataHelper | GetZipCode | getEmpAddrZip
   empRecDataHelper | SetFirstName | setEmpNameFirst
   empRecDataHelper | SetMiddleInitial | setEmpNameMI
   empRecDataHelper | SetLastName | setEmpNameLast
   empRecDataHelper | SetSSN | setEmpSsn
   empRecDataHelper | SetState | setEmpAddrST
   empRecDataHelper | SetStreet | setEmpAddrStreet
   empRecDataHelper | SetZipCode | setEmpAddrZip

Step 3: Set Up ApplicationView Business Operations

In this step, you will define the business operations necessary to access the ApplicationView EJB to invoke a mainframe operation.

Begin by defining a business operation that acquires access to an instance of the ApplicationView session EJB:

1. Add a new business operation and name it Create ApplicationView.

2. Select the Session EJB type. The EJB selection dialog box displays.

3. From the EJB list, select jam.AppViewHome.

4. From the Method list, select create(). Then select OK to complete the definition of this Business Operation.

Continue by defining a business operation that uses an ApplicationView session EJB to invoke a service on the mainframe:

1. Add a new business operation and name it Create Mainframe Employee Record.

2. Select the Session EJB type and select the jam.AppViewHome EJB.

3. From the Method list, select DataView invokeService(DataView).

4. The Parameters list in the dialog box shows two parameters. You must specify a name for these parameters by selecting each parameter and then clicking Update. The first parameter may be named serviceName and the second inputData.

5. Select OK to complete the definition of this Business Operation.

Task 2: Set Up a Workflow Template

Now a workflow template can be defined to make use of the business operations set up in Task 1: Define Business Operations for the Create Employee Record Example. Refer to the BEA WebLogic Process Integrator Studio Guide for detailed information about setting up workflows.

Use the following guidelines to set up your workflow for creating an employee record:

1. Create a new template by selecting and clicking Templates in the WebLogic Process Integrator Folder Tree.

2. The Template Properties dialog box displays. Select the organizations under which you want to define the template.

3. Right-click on your new template in the WebLogic Process Integrator Folder Tree and select New Template Definition to display the Template Definition dialog box. Select the Effective, Expiration, and Enable auditing characteristics for your definition.

4. Click OK and a default workflow template definition is presented in the workflow drawing area, along with a toolbar containing drawing shapes used for defining the workflow template. The default workflow template definition contains three nodes: Start, Task, and Done.

Task 3: Define Variables

In this task, you will define variables to be used in your workflow.

1. Right mouse-click on Variables in the WebLogic Process Integrator Folder Tree.

2. Define the following variables with the data types listed in parentheses:

Task 4: Define the Start Node

In this task, you will modify and define properties for the Start node to create an employee record and helper objects.

1. From the workflow drawing area, double-click on the Start node to display the Start Properties dialog box.

2. Rename the Start node by modifying the Description to fit your workflow. In this case the Description could be Begin JAM Test.

3. Select the Manual option to define a workflow that is manually started.

4. Next, add an action to the Start node by selecting the Actions tab and clicking Add.

5. The Add Action dialog box displays. Expand the Integration Actions item and select Perform Business Operation. Click OK to display the Perform Business Operation dialog box.

6. Click the pull-down Operation text box and select the Create empRecData Object operation. Click the pull-down Assign result to variable list and select the empRecord variable. This business operation does not require a parameter.

7. Click OK to return to the workflow drawing area.

8. Repeat steps 4 through 7 to add a second Perform Business Operation. This time use the Create empRecDataHelper operation and assign the result to the empRecHelper variable. This operation requires a parameter that you will specify as originating from the setempRec variable in the Parameters Value field.

   This completes the Start node.

Task 5: Create a Task to Set Up an Employee Name

Actions can now be added as tasks to your Create Employee Records workflow. You may add as many tasks as you need to complete your process. In this example, the first task, Set Up Name, is created and several business operations are used to set values in the various fields that make up the name.

1. From the workflow drawing area, double-click on the Task 1 node to create the Set Up Name task. The Task Properties dialog box displays.

2. Select the Activated tab and click Add to add a business operation to the Add Action dialog box. Expand the Integration Actions, select Perform Business Operation, and click OK to display the Perform Business Operation dialog box.

3. Select Set employee last name from the pull-down Operation list. Remember the names in this list originate from the methods defined in the Method to Call list for the business operations you set up in Task 1: Define Business Operations for the Create Employee Record Example.

   Specify the emRecHelper (object) as the Instance Variable.

4. Double-click on the Value for LastName to display the Expression Builder dialog box.

   For this example, enter the last name in the Expression text box and select the Literals option. The name could have been obtained in any manner and used from a variable or other source.

   Click OK to return to the Perform Business Operation dialog.

5. Click OK to add this business operation to the action and return to the Task Properties dialog.

6. Repeat Steps 1 through 9 to add the additional business operations required to set up the employee name with the first name and middle initial. These operations include the setFirstName and setMI methods.

Task 6: Create a Task to Set Up the Employee Address

A second task to set up the employee address is created and added to the Create Employee Records workflow.

1. Follow the steps in Task 5: Create a Task to Set Up an Employee Name to set up the employee address. Add business operations for the setStreet, setState, and setZip methods to create the employee address.

2. From the Task Properties dialog box, link the Set Up Address task to the Done task by clicking the Done option in the Next tab property box.

3. Then link the Set Up Address task to the Set Up Name task by opening the Task Properties dialog box for the Set Up Name task and selecting the Set Up Address option in the Next tab property box.

Task 7: Create Additional Tasks to Complete the Employee Record

Set up the following additional tasks similarly to the steps described in Task 5: Create a Task to Set Up an Employee Name:

- Setup SSN

- Make Mainframe Request

Refer to your WebLogic Process Integrator documentation for more detailed information about using WebLogic Process Integrator Studio.

Following is a brief description of each additional task:

1. Add a Setup SSN task to set the social security number. All of the DataHelper accessor set methods take string parameters. The data conversion is handled automatically for the field. Therefore, in this example the value set for the social security Expression is a literal string.

2. Link the Setup Address task to the Setup SSN task.

3. Since the employee record only requires a name, address, and social security and all the required data has been set up, you can now create a Create mainframe employee record task.

   This task contains two actions. The first acquires access to an ApplicationView through use of the Create ApplicationView EJB Business Operation and the second invokes the mainframe service through the use of the Create mainframe employee record Business Operation.

4. Add a new action by selecting the Business Operation, Create Application View EJB. This operation has no parameters, but does produce a result. Assign the result to the empRecEJB(session) variable.

5. Add another action by selecting the Business Operation, Create mainframe employee record. This action requires you to specify an instance. Use the empRecEJB(session) variable created in the previous step.

6. Specify two parameters. The first is a literal string that names the service to be invoked, use empRecCreate. Note that the service name must match a remote service defined in your jcrmgw.cfg file. The second parameter is your employee record stored in the setempRec variable.

After you finish setting up your workflow, you can execute it. Refer to your BEA WebLogic Process Integrator documentation for detailed information about starting a workflow.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher.