Using Workflows to Exchange Business Messages

You can use WebLogic Process Integrator workflows to exchange XOCP business messages in the WebLogic Collaborate environment. WebLogic Process Integrator accelerates application development by providing a visual design tool for designing workflows (process models); a run-time Process Engine for executing workflows; and process monitoring capabilities. Using WebLogic Process Integrator in the WebLogic Collaborate environment involves a combination of design, programming, and administrative tasks.

The following sections describe how to exchange business messages in WebLogic Collaborate by using WebLogic Process Integrator workflows:

About Using Workflows

The following sections describe key concepts for using WebLogic Process Integrator workflows in WebLogic Collaborate applications:

About This WebLogic Process Integrator Version

The version of WebLogic Process Integrator that is bundled with WebLogic Collaborate provides all of the functionality of WebLogic Process Integrator version 1.2, which ships separately. It also provides additional functionality for integrating with the WebLogic Collaborate environment, including:

For more information about the WebLogic Process Integrator application, see the following documents:

Architectural Overview

This section describes how WebLogic Process Integrator integrates with the WebLogic Collaborate architecture.

Architecture Diagram

The following figure shows the WebLogic Collaborate c-enabler architecture with WebLogic Process Integrator components.

Figure 2-1 C-Enabler Architecture

WebLogic Process Integrator Components in WebLogic Collaborate

WebLogic Collaborate provides the following WebLogic Process Integrator components:

Table 2-1 WebLogic Process Integrator Components

Component	Description
WebLogic Process Integrator Studio	Client application that is used at design time to define workflows and at run time to monitor running workflows.
WebLogic Process Integrator Process Engine	Run-time controller and workflow engine that executes and manages workflows and tracks workflow instances.
WebLogic Process Integrator Database	Database in which workflow templates are stored. This database can reside locally on the c-enabler node, or it can reside on a different node that is network accessible to the c-enabler. The database can be deployed so that it is accessible to a single c-enabler only, to multiple c-enablers within the same trading partner organization, or to multiple c-enablers across trading partners in different organizations.
WebLogic Process Integrator Worklist	Application that is used to view and perform tasks that are currently assigned to a user or to roles to which the user belongs, such as reassigning tasks to other users, marking tasks as done, unmarking tasks done, viewing a workflow status, manually starting a workflow, and so on.

Key Concepts

This section describes key concepts that you need to understand before using WebLogic Process Integrator workflows in WebLogic Collaborate applications.

Workflows, Workflow Templates, and Workflow Template Definitions

This section describes the following key WebLogic Process Integrator concepts:

Conversations, Conversation Definitions, and Business Messages

This section defines the following key WebLogic Collaborate concepts:

Initiators and Participants

A conversation involves an initiator who starts the conversation and participants who participate in the conversation once it has started. Each perspective requires a different kind of workflow.

Table 2-2 Types of Workflows

Workflow Type	Description
Conversation initiator workflow	Defined to have conversation properties and a non-Business Message start property. This type of workflow initiates and terminates the conversation.
Conversation participant workflow	Defined to have conversation properties and a Business Message start property. This type of workflow can join and exit the conversation but cannot initiate or terminate it.

Figure 2-2 Sample Business Process with Two Workflows

Sent and Received Business Messages

When trading partners exchange business messages, initiator and participant workflows both typically send and receive business messages.

It is important to keep in mind which parts of the workflow send business messages and which parts receive them. For example, a buyer might submit a bid request (a business message) to a seller. In this case, the buyer workflow is sending the business message and the seller workflow is receiving it. When the seller replies to the request with a bid (another business message), then the roles are reversed: the seller workflow is the sender and the buyer is the recipient workflow.

The design and programming tasks differ for sending and receiving business messages. However, in both cases, you must define certain properties in the workflow template definition and write application code (that implements the com.bea.b2b.wlpi.MessageManipulator interface) to manipulate the business message.

Run-Time Prerequisites

Before exchanging messages at run time, the following prerequisites must be met:

Summary of Workflow Integration Tasks

Using WebLogic Process Integrator workflows to exchange business messages in WebLogic Collaborate requires a combination of administrative, design, and programming tasks.

Administrative Tasks

Integrating WebLogic Process Integrator workflows requires the following administrative tasks:

Design Tasks

Integrating WebLogic Process Integrator workflows requires the following design tasks that you perform in WebLogic Process Integrator Studio:

Note: You can run WebLogic Process Integrator workflows in the WebLogic Collaborate environment even if they are not integrated with WebLogic Collaborate features. For example, you can run workflows created in WebLogic Process Integrator version 1.2 (shipped separately from WebLogic Collaborate) without specifically adapting them to integrate with WebLogic Collaborate.

Programming Tasks

Programming tasks depend on the specific needs of each application that makes use of a workflow. The following tasks are required:

Designing Workflows for Exchanging Business Messages

For example, you link a workflow template definition to a particular role in a conversation definition in the c-hub repository. You also define some additional attributes, including the message delivery Quality of Service, message token handling, and conversation termination.

The following sections describe how to design workflows to exchange business messages in the WebLogic Collaborate environment:

Using Workflow Templates Created in Other WebLogic Process Integrator Versions

The version of WebLogic Process Integrator that ships with WebLogic Collaborate is designed to work seamlessly within the WebLogic Collaborate environment. If you have workflows that were designed in other versions of WebLogic Process Integrator, you can use still these workflows in WebLogic Collaborate, but you must complete the following additional tasks to adapt them for use in WebLogic Collaborate:

Note: Standalone versions of WebLogic Process Integrator cannot use workflows that were created or modified using the version of WebLogic Process Integrator Studio that ships with WebLogic Collaborate.

Exporting Workflow Template Definitions

To export a workflow template definition from a WebLogic Process Integrator version that shipped separately from WebLogic Collaborate:

Importing Workflow Template Definitions

Defining Conversation Properties

Opening Workflow Template Definitions

To define a workflow template definition in WebLogic Process Integrator Studio:

Linking Workflows to Conversations

Before you use a WebLogic Process Integrator workflow to exchange business messages in WebLogic Collaborate, you first link the workflow template definition in WebLogic Process Integrator with a particular conversation type (a conversation name, version, and WebLogic Collaborate role) in the WebLogic Collaborate c-hub repository.

To link a workflow template definition with conversation type:

Defining the Quality of Service for Message Delivery at the Template Level

The Quality of Service (QoS) is a set of attributes that are defined for reliable business message publishing. In WebLogic Process Integrator, you can define the QoS at the following levels:

To specify the Quality of Service at the workflow template definition level:

Linking C-Enabler Session Names to a Workflow Template Definition

You can associate a workflow template definition with one or more workflow c-enabler session names. At a minimum, you must link at least one c-enabler session name. The WebLogic Process Integrator Studio allows you to add, update, and delete linked session names.

A workflow template definition can have more than one defined session name. This allows the same workflow template definition (different instances) to be used by different c-enablers in the same conversation. For example, a workflow template definition could be defined with three different session names (such as sessionA, sessionB, and sessionC). Each trading partner in the conversation can then use the appropriate session when providing their own implementation (manipulate message) to process the request.

Session names are defined in the c-enabler XML configuration file. Each session name refers to one session entry in a c-enabler configuration file (which is known only at run time). Each session entry in the c-enabler XML configuration file refers to a specific c-hub, c-space, and trading partner.

Adding Sessions

To add a session:

Updating Sessions

To update a session:

Deleting Sessions

To delete a session:

Defining Start Actions

You define a start action based on the type of workflow and according to the following rules:

Defining the Start for a Conversation Initiator Workflow

To define the Manual start property for a conversation initiator workflow:

Defining the Start for a Conversation Participant Workflow

A conversation participant workflow is started when it receives an initial business message from a conversation initiator workflow. You must define a Business Message start state for such workflows.

To define the Business Message start state for a conversation participant workflow:

Defining Conversation Termination

A conversation is terminated when the conversation initiator workflow reaches a done state. Conversation participant workflows can end their participation in a conversation before the conversation is terminated.

Defining the Termination of Conversation Initiator Workflows

For a conversation initiator workflow, you define the conversation termination property (terminate with success or failure) for any done node in the workflow. Once a done node is reached in the workflow, the running instance of the workflow is marked done, regardless of whether the active workflow has reach all the done nodes. A conversation initiator workflow can terminate a conversation, but other participants in the conversation cannot.

To define the termination for a conversation initiator workflow:

Defining the End of Conversation Participant Workflows

A conversation participant workflow has defined conversation properties, a Business Message start property, and (optionally) a Conversation Terminate event. The Conversation Terminate event is used in a participant workflow to wait for a conversation termination signal from the conversation initiator. It allows a participant workflow to perform additional processing (such as housekeeping operations) based on the status of the conversation termination.

Note: The use of this event is optional. A workflow that does not wait for this event can leave the conversation by simply ending the workflow (a Done node).

A workflow event shape represents a notification node. The workflow waits for a conversation terminate to trigger the event. Upon that trigger, actions defined within the event can be executed and/or workflow variables can be set.

To add a Conversation Terminate event to a conversation participant workflow:

WebLogic Process Integrator assigns the conversation terminate status value to a WebLogic Process Integrator Boolean variable, which can be accessed by the workflow or passed to a business operation. The developer of the workflow should take appropriate actions based on this value.

Defining WebLogic Process Integrator Variables for Workflows

A WebLogic Process Integrator variable is typically used to store application-specific information required by the workflow at run time. Variables are created and assigned values largely to "control" the logical path through a workflow instance; the same workflow template definition is instantiated multiple times and can be traversed in different ways if the flow contains decision nodes, which evaluate workflow variable values and branch to either the next True or next False within the workflow, as appropriate.

You must define WebLogic Process Integrator variables for a workflow template definition that contains processes that require variables during run time. During workflow execution, you can access a WebLogic Process Integrator variable in the following ways:

Associations Between WebLogic Process Integrator Variables and Java Data Types

If you access a WebLogic Process Integrator variable within a business operation, you need to know how WebLogic Process Integrator variable types correspond to Java data types. The following table shows how they are related.

Table 2-7 WebLogic Process Integrator Variables and Java Data Types

WLPI Variable Type	Java Data Type
String	java.lang.String
Integer	Java.lang.Integer
Long	Java.lang.Long
Double	java.lang.Double
Date	java.util.Date
Boolean	java.lang.Boolean
Complex Object	java.lang.Object (must implement Serializable)
XML	org.w3c.dom.Node

When defining WebLogic Process Integrator variables, comply with the following rules:

Defining Input Variables

Before a WebLogic Collaborate application can set an input variable, you must define it in WebLogic Process Integrator Studio.

To define an input variable:

Defining Output Variables

Variables that must be retrieved after the workflow completes must be declared as output variables. Otherwise, their value will not be preserved.

To define an output variable:

Working with Business Messages

You use WebLogic Process Integrator in conjunction with WebLogic Collaborate to exchange business messages between trading partners. The following sections describe how to work with business messages exchanged by using workflows:

About Business Messages

A business message is the basic unit of communication exchanged between trading partners in a conversation. A business message is a multi-part MIME message that consists of:

Summary of Prerequisite Tasks for Exchanging Business Messages

You must perform the following tasks before you can send and receive business messages. Subsequent sections describe these tasks in detail.

Defining Variables and Manipulating Business Messages

The following sections describe procedures you perform in regard to both sent and received messages:

Defining WebLogic Process Integrator Variables for Business Messages

At run time, a business message is stored in a WebLogic Process Integrator variable (of type Java Object) when it is ready to be sent or when it has been received. When a business message is ready to be sent, the application code associated with the Manipulate Business Message action constructs the business message and returns it in this variable to the workflow instance. When a business message has been received, the application code associated with the Manipulate Business Message action obtains this variable from the workflow instance and uses it to process the incoming business message.

Note: In WebLogic Collaborate, XOCP business messages are not stored in WebLogic Process Integrator variables of type XML Document.

For each workflow template definition, you must define a separate variable for each business message that the workflow sends or receives. For example, if a workflow sends a request and receives a reply, you must define variables for both in its workflow template definition.

To define a variable for a business document in WebLogic Process Integrator Studio:

Defining Manipulate Business Message Actions

At run time, the Manipulate Business Message action is invoked to manipulate a business message. If the workflow is sending a business message (such as request), the Manipulate Business Message action runs the associated application code to create the business message and save it in an output variable that is sent subsequently in a Send Business Message action. If the workflow is receiving a business message (such as a reply), the Manipulate Business Message action captures the incoming business message in an input variable and passes it onto the associated application code for processing.

The Manipulate Business Message action can be associated with any of the following nodes: task, decision, event, and start. You must explicitly add the Manipulate Business Message action to the workflow template definition.

Adding a Manipulate Business Message Action

To define the Manipulate Business Message action for a workflow in WebLogic Process Integrator Studio:

Example of a Manipulate Business Message Action

For example, suppose you specify the following settings in the Manipulate Business Message dialog box.

Table 2-10 Sample Settings in the Manipulate Business Message Dialog Box

Field	Description
Class name	examples.wlpiverifier.ProcessRequest
Input variable	requestMsg
Output variable	replyMsg

Writing Business Operations to Manipulate Business Messages

You write business operations that use WebLogic Process Integrator variables and Java code to manipulate business messages that are exchanged between trading partners. The Manipulate Business Message action invokes a special WebLogic Collaborate business operation, a message manipulator, to create a business message to send or to process a business message that has been received. A message manipulator is a Java class that implements the com.bea.b2b.wlpi.MessageManipulator interface.

Supported Operations

Message manipulators support the following operations for processing business messages:

MessageManipulator Interface

To process business messages that are exchanged between roles in a conversation, workflow applications use Java classes that implement the com.bea.b2b.wlpi.MessageManipulator interface. This interface contains a single operation, manipulate, with the following signature:

XOCPMessage manipulate(WorkflowInstance instance, XOCPMessage in) throws WLPIException;

When calling the manipulate operation, a workflow specifies the following parameters.

Table 2-11 Parameters in the Manipulate Operation

Parameter	Description
instance	Current workflow instance, which can be used to get or set variables. For more information, see Defining WebLogic Process Integrator Variables for Business Messages.
in	XOCP message stored in the WebLogic Process Integrator variable specified as an input variable in the associated Manipulate Business Message action. If no input variable was specified in the Manipulate Business Message action or if the variable is empty, then null is passed.

Note: Classes that implement the message manipulator interface must have a public default constructor (a constructor without arguments). The Process Engine uses Java reflection to create objects of that class and therefore invokes the default constructor.

Creating and Defining Messages to Send

The following sections describe how to prepare messages to be sent:

Steps for Creating Business Messages

The PrepareQuery class in the WebLogic Process Integrator Verifier program is an example of a message manipulator that constructs a business message before it is sent. It is called by the Manipulate Business Message action that occurs in the workflow. It returns a reply message (replyMsg variable) that is passed back to the workflow as the business message to send.

Step 1: Import the Necessary Packages

The following listing shows the packages that the PrepareQuery class imports, which includes the XOCP messaging objects that are used to create the XOCP message.

Listing 2-1 Importing the Necessary Packages

package examples.wlpiverifier;

import java.io.*;

import org.apache.xerces.dom.*;
import org.w3c.dom.*;

import com.bea.eci.logging.*;
import com.bea.b2b.wlpi.MessageManipulator;
import com.bea.b2b.wlpi.WorkflowInstance;
import com.bea.b2b.wlpi.WLPIException;

import com.bea.b2b.protocol.conversation.ConversationType;
import com.bea.b2b.enabler.*;
import com.bea.b2b.enabler.xocp.*;
import com.bea.b2b.protocol.messaging.*;
import com.bea.b2b.protocol.xocp.conversation.local.*;
import com.bea.b2b.protocol.xocp.messaging.*;

Step 2: Implement the MessageManipulator Interface

The following listing shows the PrepareQuery class declaration that implements the MessageManipulator interface.

Listing 2-2 Implementing the MessageManipulator Interface

public class PrepareQuery implements MessageManipulator{
...
}

Step 3: Call the Manipulate Method

The code in the following listing calls the manipulate method, which retrieves the current workflow instance object as well as the incoming business message.

Listing 2-3 Calling the manipulate Method

  public XOCPMessage manipulate(WorkflowInstance instance,
                                        XOCPMessage in)
    throws WLPIException{

Step 4: Get the Input Variables from the Current Workflow Instance

The code in the following listing gets the input variables associated with the current workflow instance by calling the getVariable method on the workflow instance.

Note: The WlpiVerifierConstants class contains constant values.

Listing 2-4 Getting the Input Variables

    int current = ((Integer)instance.getVariable(WlpiVerifierConstants.CURRENT)).intValue();

    String req = (String)instance.getVariable(WlpiVerifierConstants.REQUESTSTR + current);
    boolean last;
    if (current < 4){
      try{
        String v = (String)instance.getVariable(WlpiVerifierConstants.REQUESTSTR + (current + 1));
        if (v == null || v.length() == 0)
          last = true;
        else 
          last = false;
      }catch (WLPIException e){
        last = true;
      }
    }else 
      last = true;

    if (last)
      instance.setVariable("last", new Integer(1));

Listing 2-5 Creating the Request Message

    XOCPMessage xocpmsg = null;
    try{
      DOMImplementationImpl domi = new DOMImplementationImpl();

      // "request" - (param1) The qualified name of the document type to be created.
      // "request" - The document type public identifier.
      // "upper-request.dtd" - The document type system identifier
      DocumentType dType = domi.createDocumentType("request",
"request", "upper-request.dtd");

      org.w3c.dom.Document rq = new DocumentImpl(dType);
      Element root = rq.createElement("request");
      rq.appendChild(root);
      Text t = rq.createTextNode(req);
      root.appendChild(t);
      root.setAttribute("last", last ? "true" : "false");

      xocpmsg = new XOCPMessage("");
      xocpmsg.addPayloadPart(new BusinessDocument(rq));

    }catch(Exception e){
      e.printStackTrace();
      throw new WLPIException("PrepareQuery raised exception:" + e);
    }

Step 5: Return the Request Message

The code in the following listing returns the request message in the variable xocpmsg (of type XOCPMessage) The return value is then assigned to an output variable (of type Java Object) in the workflow in preparation for sending the business message.

Listing 2-6 Returning the Request Message

    return xocpmsg;

Defining Send Business Message Actions

After you create a business message in WebLogic Process Integrator using a Manipulate Business Message action and a message manipulator, you send the business message using the Send Business Message action.

To define a Send Business Message action: