Using BEA WebLogic Process Integrator with JAM


	Corporate Info \| News \| Solutions \| Products \| Partners \| Services \| Events \| Download \| How To Buy
	http://www.oracle.com/technology/documentation/index.html \| Search \| PDF Files \| Contact \| Glossary

WebLogic Java Adapter for Mainframe Doc Home \| Previous Topic \| Next Topic \| Contents \| Index

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," which 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 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.

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 Application View
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. 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. 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:

Declare business operations using the document holder that corresponds to the mainframe application to be invoked. All methods on the document holder should be declared business operations because they represent every operation required to create, populate, and extract data for the mainframe application.
When the business operations have been declared, a workflow can make reference to them. General usage of a document holder follows a standard pattern.
Use the Factory method to obtain a new instance of the document "to be held."
Populate the document data elements by using the accessor business operations provided by the document holder.
Invoke the mainframe request using the JAM Application View providing the service name and the document. (Not the document holder)
Upon returning from the request, use the accessor business operations to retrieve data from the document which has been provided/updated by the mainframe application.

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 more information about using WebLogic Process Integrator.

Task 1: Set Up JAM Components as Business Operations

Perform the following steps to set up JAM components as business operations:

Start WebLogic Process Integrator Studio
Choose Configuration menu -->Business Operations.

The business operation definition dialog displays.

Any existing business operations are listed. In this example business operations from the WebLogic examples are shown. The methods for the JAM Document Helper components will also be added here.
Click Add button and the following dialog displays.

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.
Click OK to display the Java Class Name dialog.
Enter the Java Class Name here.
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. The class specified here must be located on the Java CLASSPATH. In this example the empRecDataHelper is located in $WLS_HOME/myserver/clientclasses.
Click OK and the following dialog displays.

The business operation dialog has a pull-down list of all of the available methods. Methods can be selected in any order. In this example, select the Data Factory method named newXml. This method must be used in the workflow first to create a new empRec that can then be used for the other business operations.
Add a description for the new business operation. This description displays in the pull down list when defining a new workflow.

Note the left side of the dialog has a pull down list for constructors. The default constructor will always be first on this list. The newXml method must be used with the default constructor.
Continue adding data accessors by selecting other methods from the pull down list.

The data accessors must use the second constructor provided. This constructor takes a single object as a parameter. That object is the empRec object that is created by the newXml method. This is illustrated by naming the parameter for the constructor emp Record.

Again, add a simple description to be added to the workflow definition pull-down list displayed for the business operations. In this example the getEmpAddrZip method is given the description get ZipCode.

Continue adding methods until all accessors have been set up as business operations.

Following is an example of a business operation for the set FirstName method. Constructor 2 is specified with the object parameter for empRecord and string parameter for SetEmpNameFirst.

The final list should look something like the following.

Click Done when you are finished and the WebLogic Process Integrator main window redisplays.

Task 2: Set Up a Workflow

Now a workflow can be defined to make use of these business operations.

Perform the following steps to define a workflow:

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

The Template Properties dialog displays.
Select one or more organizations for the template.
Right click on your new template to create a new definition and select New Template Definition to display the Template Definition dialog.
Select the characteristics for your definition.

In this example the workflow becomes effective on October 2, 2000 and expires on October 27, 2000.
Click OK.
A new workflow opens.

Task 3: Define the Start Node

Double-click on the start node to begin using the empRec Data Helper. Enter Begin JAM Test in the Description text box.

The Start Properties dialog determines the type of workflow to be created. In this example a manually started workflow is created.
Click Add to create a variable to hold a new employee record object. The Workflow Variable Assignment dialog displays.
Enter the Variable named empRecord and click OK. Since it does not yet exist, a prompt displays asking if you want to create it.
Click Yes to display the Variable Properties dialog for the new variable.
Select Complex Object for the Type because this variable will be used to hold an object reference. You may also add a description of the variable in the Notes text box.
Click OK and the Start Properties dialog redisplays.

The start node is now ready to have an action added to it.

Task 4: Set Up the Start Node Properties

From the Start Properties dialog, select the Actions tab and click Add.
The Add Action dialog displays. Expand the Integration Actions item and select Perform Business Operation.

Click OK and the Perform Business Operation dialog displays.
Pull down the operation list and select the Create New Employee Record Object operation.
Pull down the Assign result to variable list and select the empRecord variable that was previously created.

This completes the start node. Click OK to return to the Workflow window.

Task 5: Create a Setup Name Task

Actions can now be added by double clicking on the Task box displayed for the workflow diagram. The Task Properties dialog displays.

A task can use several business operations. In this example the task Setup Name is created and several methods are used to set values in the various fields that make up the name.

Select the Activated tab and click Add button to add a business operation on the Add Action dialog.
Expand the Integration Actions, select Perform Business Operation, and click OK to display the Perform Business Operation dialog.
Select the set LastName operation from the pull down list in he Perform Business Operation dialog. Remember the names in this list originate from the description property on the business method as it was configured. For this reason, it is good to adopt a simple standard when creating descriptions.

The method used to set the last name requires two parameters. One parameter is for the constructor and one parameter is for the method itself. In this example the constructor takes the empRecord variable that has been populated in the start node. The business operation takes a string representing the last name.
Double-click on the Value for empRecord to display the Expression Builder dialog.

This dialog allows you to set the value of the required parameter. In this example a variable is used. Select the Variables option to display a list of all the variables defined for this workflow. This example uses the empRecord variable that was defined and populated in the start node.
Select and double-click on the required variable, the variable name is set in the expression. Click OK to return to the Perform Business Operation dialog.
Select the set LastName operation and double-click on the Value for empRecord to display the Expression Builder dialog.
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.
Select empRecord from the Assign result to drop-down list to complete the definition.
Click OK to add this business operation to the action and return to the Task Properties dialog.
Repeat steps through 8. to add the additional business operations required to set up the employee record. These operations will include setFirstName and setMiddleName.
Create an additional Task named Setup Address and link it to the Done node.
Link the Setup Name task to the Setup Address task by selecting Setup Address in the Next property.

Task 6: Create Additional Tasks

This section shows examples that were set up similarly to the tasks described in the previous steps. Refer to your WebLogic Process Integrator documentation for more information about using WebLogic Process Integrator Studio.

The following figure shows the example from the previous steps with a new task named Setup SSN added 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.

The Setup Address task is linked to the Setup SSN task.

Since the employee record only requires a name, address, and social security, a Make Mainframe Request task can now be created.

Once the data has been set up, the mainframe request can be made. All JAM requests are made through the JAM Application View invokeService method. The JAM Application view is a stateless session enterprise Java bean registered in JNDI as jam.AppViewHome. The actual client EJBs used to invoke the service do not need to be known to WebLogic Process Integrator. The AppView will invoke the proper bean and method based upon the service name. The service name must match a remote service that has been configured for the JAM gateway. JAM gateway configuration is specified in the jcrmgw.cfg file.

The business operation required is invokeService, which will use the default constructor and take two parameters. The first parameter is a Service Name and the second is the Mainframe Data Object that was created with the newXml method invoked in the Start node.

A new task named Make Mainframe Request is created using the invokeService business operation.

For purposes of this example, a Clear Address task was created so that the workflow can read the item just created.

The set methods are used to clear state, street and zip code.

A new task called Read Mainframe Data has been created and linked to a task called Save Address that will extract state, street and zip code.

The business operation, Make Mainframe Request, is again used but in this example the service name is empRecRead. This service has been set up in the jcrmgw.cfg as a remote service.

After reading the mainframe employee record the address fields will be extracted into WebLogic Process Integrator variables.

In the following example, three new variables for state, street and zip code have been added.

The task, Save Address uses the get methods to extract the state, street, and zip code that was returned from the mainframe. This task is linked to a Done node, however additional processing could have been added.

Following is an example of how the finished workflow might look.