Starting Collaborative Workflows

 

The following sections explain how to define start actions for collaborative workflows:

• About Starting Collaborative Workflows

• Starting a Conversation Initiator Workflow

• Defining the Start Node for a Conversation Participant Workflow

• Defining the Start Public Workflow Action

• Developing Applications that Start Conversation Initiator Workflows

 

---

About Starting Collaborative Workflows

The job of starting collaborative workflows comprises two tasks:

• Defining Collaborative Workflow Start Properties

• Starting the Collaborative Workflow at Run Time

The following two sections describe the design and programming implications of each task.

Defining Collaborative Workflow Start Properties

There are three ways in which you can start a collaborative workflow:

• Programmatically, via a Java application that starts the workflow

• As a subworkflow, via the Start Public Workflow action defined on a node in the parent workflow

• When a business message is received, via the business message start state

You define the start properties for a workflow based on the type of workflow being designed (conversation initiator versus conversation participant) and according to the following rules:

• For a conversation initiator workflow that is started programmatically, you must specify a manual start property in the Start node.

• For a conversation initiator workflow that is started via the Start Public Workflow action, you must specify a called start state in the Start node.

• For a conversation participant workflow, you must define a business message start state in the Start node.

Note: To instantiate any workflow, the workflow template definition must be active and not expired.

Starting the Collaborative Workflow at Run Time

How you start a collaborative workflow at run time typically depends on whether the workflow is a conversation initiator or conversation participant:

• Conversation initiator workflows can be started in either of two ways:

  • A parent, or other local workflow, can start the conversation initiator workflow by using the Start Public Workflow action defined on one of the parent workflow's nodes. When the node with the Start Public Workflow action is executed, the conversation initiator workflow is started.

  • A user-written application can start the conversation initiator workflow at run time. WebLogic Integration provides the Message Manipulator API (package com.bea.b2b.wlpi) that the application uses to start the workflow and handle exceptions.

• Conversation participant workflows are started when the business message defined to start that workflow is received by the WebLogic Integration process engine.

 

---

Starting a Conversation Initiator Workflow

A conversation initiator workflow is started in one of the following ways:

• Programmatically via a Java application

• Via another local workflow

Conversation initiator workflows that are started programmatically must have a manual start property defined in the Start node. For more information about starting a conversation initiator workflow programmatically, see Developing Applications that Start Conversation Initiator Workflows.

Conversation initiator workflows that are started via another local workflow must have the called start property defined in the Start node. The local workflow—in the design pattern used in the sample applications, this local workflow is called a private workflow—starts the conversation initiator workflow as a subworkflow. For more information about the sample applications, see Learning to Use BEA WebLogic Integration and Running the B2B Integration Samples.

To define the start property for a conversation initiator workflow:

1. Display or add the start shape, as described in Defining Workflow Templates in Using the WebLogic Integration Studio.

2. Double-click the start shape to display the Start Properties dialog box.

   Figure 3-1 Start Properties Dialog Box: Manual Start

   
    

3. Change the text in the Description field to a unique, identifiable name, if desired.

4. If the workflow will be started programmatically, select Manual. If the workflow will be started via another workflow, select Called.

   For more information about these options, see Defining Workflow Templates in Using the WebLogic Integration Studio.

5. Click OK.

 

---

Defining the Start Node for a Conversation Participant Workflow

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

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

1. Display or add the start shape, as described in Defining Workflow Templates in Using the WebLogic Integration Studio.

2. Double-click the start shape to display the Start Properties dialog box.

3. In the Start Properties dialog box, select Event, and in the drop-down list that appears to the right, select Business Message.

   Figure 3-2 Choosing a Business Message Start State

   
    

   The Start Properties dialog box is displayed again with the additional fields, shown in the following figure. In these fields you add information specific to the collaborative workflow, particularly information related to the business protocol on which the workflow is based. (The following figure shows the Start Properties dialog box for a workflow based on the XOCP protocol.)

   Figure 3-3 Start Properties for a Conversation Participant Workflow

   
    

4. Change the text in the Description field to a unique, identifiable name.

5. Provide the information required by the business protocol on which the workflow is based, described in the following sections:

   • For XOCP 1.1-based workflows, see Starting Conversation Participant Workflows Based on the XOCP 1.1 Protocol.

   • For RosettaNet 2.0-based workflows, see Starting Conversation Participant Workflows Based on the RosettaNet 2.0 Protocol.

   • For RosettaNet 1.1-based workflows, see Starting Conversation Participant Workflows Based on the RosettaNet 1.1 Protocol.

6. Specify a start organization, as described in Defining Workflow Templates in Using the WebLogic Integration Studio.

7. Click OK.

Starting Conversation Participant Workflows Based on the XOCP 1.1 Protocol

In the Start Properties dialog box, enter the following information for workflows based on the XOCP 1.1 protocol.

Figure 3-4 XOCP 1.1 Start Properties

 

1. The target variable is a workflow variable of type object that will contain an instance of an internal type that, in turn, contains the business message.

2. The router expression is a workflow variable of type string containing the router expression that was set by the sender of the business message.

3. The sender name is a workflow variable of type string that contains the name of the trading partner who sent the business message.

   If you want to specify that the sender name is to be converted to an XPath expression, select the XPath Conversion button.

Starting Conversation Participant Workflows Based on the RosettaNet 2.0 Protocol

In the Start Properties dialog box, enter the following information for workflows based on the RosettaNet 2.0 protocol.

Figure 3-5 RosettaNet 2.0 Start Properties

 

1. The content variable is a workflow variable of type XML that contains the business message content.

2. The attachment descriptor variable is an optional workflow variable of type XML that contains XML data that describes the attachment files to the business message.

For complete details about creating start properties for workflows based on the RosettaNet 2.0 protocol, see Implementing RosettaNet for B2B Integration.

Starting Conversation Participant Workflows Based on the RosettaNet 1.1 Protocol

In the Start Properties dialog box, enter the following information for workflows based on the RosettaNet 1.1 protocol.

Figure 3-6 RosettaNet 1.1 Start Properties

 

1. The content variable is a workflow variable of type XML that contains the business message content.

2. The attachment descriptor variable is an optional workflow variable of type XML that contains XML data that describes the attachment files to the business message.

For complete details about creating start properties for workflows based on the RosettaNet 1.1 protocol, see Implementing RosettaNet for B2B Integration.

 

---

Defining the Start Public Workflow Action

You can use the Start Public Workflow action to start a collaborative workflow from a parent workflow. When you use the Start Public Workflow action, you need to specify the following:

• The values for the conversation definition, role, and a minimum number of parties needed to uniquely identify the collaboration agreement associated with the called workflow instance

• Values of the child workflow input variables

• A variable name to contain the instance ID of the child workflow

• Child output variables in which the parent workflow is interested and the variables in the parent workflow that will contain the child workflow output values

When you start a collaborative workflow via the Start Public Workflow action, that collaborative workflow must include a means to synchronize the collaborative workflow with the parent workflow.

The sections that follow explain how to define the Start Public Workflow action and how to synchronize the called collaborative workflow with the parent workflow.

Defining the Start Public Workflow Action

The Start Public Workflow action can be associated with any workflow nodes, but typically is associated with a task node. You must explicitly add the Start Public Workflow action to the workflow template definition.

Adding a Start Public Workflow Action

To define the Start Public Workflow action for a parent workflow in the Studio:

1. Open the workflow in which you want to add the Start Public Workflow action, making sure that the workflow is active and not expired.

2. In any dialog box where you can specify an action (typically in a task node), click Add to display the Add Action dialog box.

   Figure 3-7 Add Action Dialog Box

   
    

3. Click the Integration Actions folder to expand it.

   Figure 3-8 Add Action Dialog Box with Integration Actions

   
    

4. Click the B2B Integration folder to expand it.

5. Select Start Public Workflow.

6. Click OK to display the Start Public Workflow dialog box.

   Figure 3-9 Start Public Workflow Dialog Box

   
    

7. Complete the following sections on the Conversation page of the Start Public Workflow dialog box. The values and variables you specify in this page uniquely identify the collaboration agreement that contains the workflow required for the conversation.

   Table 3-1 Sections on the Conversation Page

   Dialog Box Section	Description
   Conversation	Enter the following: Name of the conversation definition in the WebLogic Integration repository Conversation definition version Conversation role represented by the collaborative workflow to be started
   Parties	The trading partner name, role, and delivery channel of the parties configured in the collaboration agreement for the associated conversation definition to which the workflow applies. You do not need to specify all the parties, but you must identify enough to uniquely identify the collaboration agreement associated with the workflow. The information you provide for role and delivery channel must match the information configured for the corresponding trading partner in the repository. Specifying the role and delivery channel is optional, depending on whether that informaiton is required to uniquely identify the collaboration agreement. To specify a trading partner name, click on the cell under the TP Name column, and enter the name of trading partner. To specify a role, click on the cell under the Role column and enter the role name. To specify a delivery channel, click on the cell under the Delivery Channel column and enter the delivery channel name. To insert a row into a list of parties, right-click the row where you want to make the insertion and choose Insert. A blank row is created above the row in which you clicked. To remove a row from the list of parties, right-click the row you want to remove and select Delete. You can use the Expression Builder to specify party values in the Start Public Workflow dialog box. For more information, see Using the Expression Builder to Specify Values in the Start Public Workflow Dialog Box.
   Notes	Optional descriptive text.
   Actions	Tab in which you can add workflow actions. In the Actions tab, you typically add the "Mark Task as Done" property to synchronize the public workflow with the parent workflow. For more information, see Synchronizing the Child Workflow With the Parent Workflow.

   
    

8. Select the Workflow tab. The following page is displayed.

   Figure 3-10 Workflow Page of the Start Public Workflow Dialog Box

   
    

9. Complete the following fields and sections of the Workflow tab, which identify both the variable that will contain the workflow instance ID of the child workflow and the variables passed between the parent and child workflows.

   Table 3-2 Fields and Sections of the Workflow Tab

   Field or Section	Description
   Reference via	The workflow variable of type String that will contain the instance ID of the child workflow. You use this variable as a means to implement a standard communication mechanism between the parent and child workflows.
   Parameters	The variable names (in the Name column) and their respective values (in the Expression column) to be passed from the parent workflow to the child workflow. The variable names that you specify here must also be specified as input variables to the respective child workflow. As explained in About Using Workflow Variables, you should define these variables in both the parent and child workflows before you select them in this dialog box. This ensures that the variables chosen have the correct name and type. You can use the Studio Expression Builder to create an expression for each variable's value. For more information about using the Expression Builder, see Using the Expression Builder to Specify Values in the Start Public Workflow Dialog Box.
   Results	Output variable names and their respective values to be passed from the child workflow back to the parent after the child workflow has completed its execution. As with input variables, these output variables should be defined in both the parent and child workflows before you select them in this dialog box.
   Notes	Optional descriptive text.

   
    

10. Click OK to save your changes.

Using the Expression Builder to Specify Values in the Start Public Workflow Dialog Box

You can use the Studio Expression Builder to specify the following values in the Start Public Workflow dialog box:

• Trading partner names

• Roles

• Delivery channels

• Workflow parameter expressions

To display the Expression Builder, right-click in the cell in which you specify one of the preceding values and choose Expression. The Expression Builder is displayed, as shown in the following figure.

Figure 3-11 Studio Expression Builder

 

For information about how to use the Expression Builder, see Using Workflow Expressions in Using the WebLogic Integration Studio.

Synchronizing the Child Workflow With the Parent Workflow

As mentioned in Defining the Start Public Workflow Action, when you start a collaborative workflow via the Start Public Workflow action, you must have a means of synchronizing that collaborative workflow with the parent workflow. You can do this in either of two ways:

• Use an application that implements its own synchronization with the workflows.

• In the parent workflow where you define the Start Public Workflow action, mark the task as done in the Start Public Workflow actions (not in the Task actions). This prevents the parent workflow from passing execution to the next node in its workflow until the called public workflow has finished processing.

 

---

Developing Applications that Start Conversation Initiator Workflows

You can start a conversation initiator workflow at run time via a Java application, known as a workflow application. The following sections describe how to create a workflow application to start a conversation initiator workflow programmatically:

• Message Manipulator API

• Programming Steps for Accessing Conversation Initiator Workflows

To start a conversation initiator workflow programmatically, the start node for the workflow template must have a Manual start property, as described in Starting a Conversation Initiator Workflow.

Note: In WebLogic Integration release 2.0 and later, attempting to start a collaborative workflow via the Worklist results in an error.

Message Manipulator API

Workflow applications can use the com.bea.b2b.wlpi package to start workflows. This package provides the following interface and classes.

Table 3-3 Components of the com.bea.b2b.wlpi Package

Object	Description
MessageManipulator interface	Implemented by all classes that are used in a Manipulate Message action inside a workflow task
WorkflowInstance class	Represents a running workflow instance
WLPIException class	Thrown by a public method of the workflows API if an error occurs with processing

 

For details about this package, see the BEA WebLogic Integration Javadoc.

Programming Steps for Accessing Conversation Initiator Workflows

To access a conversation initiator workflow, a workflow application completes the following steps:

• Step 1: Import the Necessary Packages

• Step 2: Create a Workflow Instance Object for a Specific Workflow Template

• Step 3: Initialize Input Variables

• Step 4: Start a Workflow Instance

• Step 5: Wait for the Workflow Instance to Complete

• Step 6: Handle Results in Output Variables

The workflow application also needs to handle exceptions thrown by each of the method invocations on the Message Manipulator API, as explained in Handling Exceptions.

Note: Before creating an application that starts a workflow, verify the following:

• The template definition for the workflow has been created.

• The workflow has a manual start state, is active, and has not expired.

Step 1: Import the Necessary Packages

To access a workflow, a workflow application begins by importing the necessary package(s). At a minimum, the application must import the com.bea.b2b.wlpi package, as shown in the following example.

Listing 3-1 Importing the com.bea.b2b.wlpi Package

import java.io.*;
import java.util.*;
import javax.servlet.*;
import javax.servlet.http.*;
import javax.naming.*;

import com.bea.wlpi.common.*;
import com.bea.b2b.wlpi.*;

import com.bea.eci.logging.*;

Step 2: Create a Workflow Instance Object for a Specific Workflow Template

The workflow application next needs to create a workflow instance object of a specific workflow template definition, as shown in the following example.

Listing 3-2 Creating a Workflow Instance Object

Hashtable[] array = new Hashtable[2];
Hashtable party1  = new Hashtable();
Hashtable party2  = new Hashtable();

party1.put(WorkflowInstance.PARTYNAME_KEY, PARTY_SOURCE);
party2.put(WorkflowInstance.PARTYNAME_KEY, PARTY_DEST);

array[0] = party1;
array[1] = party2;

WorkflowInstance wi = new WorkflowInstance(BUSINESS_PROCESS_NAME,
                               BUSINESS_PROCESS_MAJOR,
                               BUSINESS_PROCESS_MINOR,
                               BUSINESS_PROCESS_ROLE,
                                array);

Step 3: Initialize Input Variables

If input variables are defined for a conversation initiator workflow, you must initialize and assign values to them in the application before starting the workflow instance. These input variables must first be declared in the template definition in the Studio, as described in About Using Workflow Variables.

A workflow application sets instance variables by invoking the setVariable method on the workflow instance and passing it the name and value of the variable. The setVariable method requires the following parameters.

Table 3-4 Parameters for the setVariable Method

Parameter	Description
name	Name of the variable to be set.
value	Value for the variable. The value must be represented as a Java object, as described in Associations Between Workflow Variables and Java Data Types.

 

The following example shows how to use the setVariable method to specify values for two variables in the workflow to be started.

Listing 3-3 Setting the Value of Input Variables

wi.setVariable( INTEGER_ONE_VAR, new Long( 3 ) );
wi.setVariable( INTEGER_ONE_VAR, new Long( 5 ) ); 

Step 4: Start a Workflow Instance

After creating a workflow instance and initializing input variables, a workflow application starts the workflow instance by invoking the start method on the instance object, as shown in the following example.

Listing 3-4 Start a Workflow Instance

wi.start();

Step 5: Wait for the Workflow Instance to Complete

Once a workflow instance has been started, a workflow application can wait for its completion by calling the waitForCompletion method on the workflow instance. The operation blocks until the workflow instance has completed.

Listing 3-5 Waiting for Completion of the Workflow Instance

wi.waitForCompletion();

While waiting for the workflow instance to complete, a workflow application can determine the completion state of the workflow instance by invoking the isCompleted method on the workflow instance. This method returns a Boolean true if the execution of the workflow is complete, or false if it is not.

Step 6: Handle Results in Output Variables

After a workflow instance has completed, a workflow application can handle the results of the workflow instance by retrieving the information stored in output variables. These output variables must first be declared in the template definition in the Studio.

A workflow application retrieves the value of an instance variable by calling the getVariable method on the workflow instance and passing it the name of the variable to be retrieved, as shown in the following example listing.

Listing 3-6 Retrieving the Results in Output Variables

product = (String)wi.getVariable(MULTIPLY_REPLY_VAR);
note = (String)wi.getVariable(NOTE_VAR);

The getVariable method returns a Java object that should be cast to the appropriate Java data type. For information about the Java types to which you must cast the return values, depending on the corresponding workflow variable types, see Using the WebLogic Integration Studio.

Handling Exceptions

If an error occurs while a workflow application is running, a com.bea.b2b.wlpi.WLPIException is thrown. With each method invocation on the workflows API, workflow applications can catch this exception and process it as appropriate, as shown in the following listing.

Listing 3-7 Handling WLPIExceptions in Workflow Applications

catch (WorkflowException we){    
      debug("Error starting workflow");
      we.printStackTrace();
}