Understanding Workflow Objects and Properties

Note: The Worklist client application is being deprecated as of this release of WebLogic Integration. For information about the features that are replacing it, see the BEA WebLogic Integration Release Notes.

In this section, we continue our tutorial by exploring the Order Processing Trigger workflow. After an overview that describes the workflow, we take a close look at the workflow's objects to help you gain a better understanding of:

• Template definition properties

• Variable properties

• Start node properties

• Task node properties

• Workflow expressions

Finally, to gain practice with using some of the Studio features, we will:

• Edit the XML document to be posted

• Export the XML document to the repository

• Save the template definition

This section of the tutorial assumes that you have done the following:

• Logged on to the Studio, as described in Starting the WebLogic Integration Studio.

• Imported and opened the Order Processing Trigger template definition as described in Importing Workflow Objects: Importing the Tutorial Package File and Viewing a Workflow: Opening the Order Processing Trigger Template Definition.

 

---

About the Order Processing Trigger Workflow

The Order Processing Trigger workflow simulates the process by which the Order Processing workflow would normally be triggered. In a real-world application, this would most likely be accomplished by a servlet that sends an XML document to a JMS queue. The arrival of the XML message on the queue would trigger the start of the Order Processing workflow, as depicted in the following figure.

Figure 3-1 Simulated Order Processing Start

 

For the purposes of this tutorial, we will simulate this process by having a Worklist user start the process of posting the XML document. A detailed view of the Order Processing Trigger workflow is shown in the following figure. The numbered steps in the figure are described in a table after the figure, which maps the real-world process and implementation to the actual implementation in the sample workflow.

Figure 3-2 Order Processing Trigger Workflow: Detailed View

 

Table 3-1 Order Processing Trigger Workflow Summary

Process	Implementation
A customer submits an order for goods to CDExpress, a music retailer, through an online mechanism such as a browser-based order form. The customer supplies his or her name, the appropriate e-mail address, the state to which the order will be shipped, the desired items (IDs and names), and the requested quantities. In a real-world application, the order would be processed by a servlet which forwards an XML document to an external JMS queue for receipt by the workflow.	1. The Start node is defined as manual, so that the workflow is started by a Worklist user.
	2. The first task is assigned to the same Worklist user who starts the workflow. When the task is executed, the <neworder> XML document is posted to an internal JMS queue. The XML document contains the order status and ID, the customer ID, name, e-mail, address, phone number, and state, and the item name, ID, and quantity.

 

Note: This workflow does not contain a done node, which means that it loops interminably. As you will see later in the tutorial, when you run the workflows, this mechanism allows the workflow to be started from within the task list window in the Worklist application.

 

---

Understanding Template Definition Properties

To view template definition properties, with the Order Processing Trigger template definition open, right-click the template definition in the folder tree, or anywhere in the workflow design window, and from the pop-up menu that appears, select Properties. The Template Definition Order Processing Trigger dialog box appears.

Figure 3-3 Template Definition Order Processing Trigger Dialog Box

 

Although multiple template definitions can have the same effective and expiry dates, each active definition must have unique dates or times. At run time, if there are multiple template definitions for a workflow, the processing engine selects the most current active template definition according to its effective and expiry dates and times.

Because we activated the Order Processing Trigger template definition during the import process, the dialog box shows it as already active. This template definition workflow has been effective since May 2, 2001, and it never expires.

We have not used a label for this workflow.

 

---

Understanding Variable Properties: Viewing the OrderID Variable

To view variable properties, go to the folder tree, and under the Variables folder, double-click the variable OrderID. The Variable Properties dialog box appears.

Figure 3-4 OrderID Variable: Variable Properties Dialog Box

 

Variables can be passed as parameters to other template definitions, XML documents, and EJB and Java class methods. An input parameter indicates that the variable is to receive its value from the calling, or parent, workflow. An output parameter indicates that the variable contains a value that will be passed back to the calling workflow.

Within the Order Processing Trigger template, the OrderID variable is not marked as an input parameter nor an output parameter, as shown in Figure  3-4. As you will see later, within the Order Processing and Order Fulfillment workflow templates, the variable is marked as an input parameter, meaning that it is passed from another workflow. Because the OrderID variable is used to track the number of the order for each instance of the workflow, it is passed to both the Order Processing and Order Fulfilment workflows.

Variables are global in scope, meaning that they apply to an entire workflow. You can view a summary of the nodes and actions in which variables are used for the current workflow.

To view the usage for the OrderID variable, go to the folder tree, and under the Variables folder, right-click the variable OrderID, and from the pop-up menu that appears, select Usage. The Variable Usage window appears.

Figure 3-5 OrderID Variable: Variable Usage Window

 

As you can see, the OrderID variable is used in the Set Workflow Variable action of the Start Order Processing task. This action is described in more detail in Understanding Workflow Expressions: Viewing the Set Workflow Variable and Assign Task to User Actions.

You will create a variable in Adding a Workflow Label and throughout Defining Workflow Nodes.

 

---

Understanding Start Node Properties

Because the Order Processing Trigger contains a single start node, the start node is not named. However, you can also define workflows that contain multiple start nodes, to specify multiple processing paths that run in parallel. You can also use start nodes to initialize any workflow variables.

To view start node properties, go to the workflow design window and double-click the Start node. The Start Properties dialog box appears.

Figure 3-6 Start Properties Dialog Box

 

As you see in the dialog box, there are four ways to start a workflow:

• Timed—The workflow starts automatically according to an exact date and time that you specify. We do not use any timed starts in this tutorial.

• Manual—The workflow is started by a Worklist user. The Order Processing Trigger workflow is defined as a manual start, which allows us to start the entire tutorial sample.

• Called—The workflow is called by another workflow. The Order Fulfillment workflow, for example, uses a called start.

• Event—The workflow is triggered by the arrival on a JMS queue of an XML document. We create an event-triggered start for the Order Processing workflow in Defining Workflow Nodes, and later in this section we work with the XML document that acts as the trigger for that workflow.

Also, in this start node, the OrderID variable, which will be incremented each time the workflow is run, is initialized to 0. For more information on this variable, see Understanding Variable Properties: Viewing the OrderID Variable.

 

---

Understanding Task Node Properties: Viewing the Start Order Processing Task Node

To view task node properties, go to the workflow design window, and double-click on the Start Order Processing task node. The Task Properties dialog box appears.

Figure 3-7 Start Order Processing Task: Task Properties Dialog Box

 

Note that under the Next tab the successor to this task is itself (indicated in the workflow design window by the looping arrow), and that there is no Done node in the list. This means that the workflow never actually terminates; every time the Start Order Processing task is executed, it creates another instance of itself. You will see this process in action when we run the workflows in Executing and Monitoring the Example Workflows.

About Task States and Actions

The tabs on the left side of the dialog box indicate four different run-time states. Actions placed on each state-specific tab for a given task are performed when the designated state is reached. The four states are:

• Created—Any actions listed in this tab are executed as soon as the workflow is started.

• Activated—The flow reaches this particular task and the actions listed here executed. You typically specify all automated actions under this tab.

• Executed—These actions are only performed after an action has been executed manually in the Worklist, programatically by the execute task API, or by the use of the Execute Task action. If none of these occurs, any actions specified in the Executed tab will never be performed.

• Marked Done—A task is marked done by the Mark Task as Done action or the corresponding API. This tab is normally used in the case that the Mark Task as Done action is not specified within itself but by some other node in the flow. It is typically used to specify clean-up actions such as writing audit information to a log.

See "Defining Task Properties" in Defining Workflow Templates in Using the WebLogic Integration Studio for a more thorough discussion of task states.

Actions are grouped into the following categories:

• Task actions—specify operations for a particular task

• Workflow actions—specify operations for an entire workflow

• Integration actions—invoke interfaces to external components

• Exception Handling actions—invoke a custom exception handler

• Miscellaneous actions—perform other operations such as sending e-mail or making an audit entry.

As you can see in the Task Properties dialog box (or in the folder tree), the Start Order Processing task contains the following actions:

• Activated

  • Set workflow variable—a workflow action that sets the OrderID variable for the workflow. See Understanding Workflow Expressions: Viewing the Set Workflow Variable and Assign Task to User Actions for more information.

  • Assign task to user —a task action that assigns a manual task to a workflow user. See Understanding Workflow Expressions: Viewing the Set Workflow Variable and Assign Task to User Actions for more information.

• Executed

  • Post internal XML event —an integration action that publishes an XML message to be used by the Order Processing workflow. See Posting an Internal XML Event: Editing the Neworder XML Document for more information.

  • Mark task as done—a task action that allows the flow to proceed to the next node. All task nodes require that you specify this action to instruct the flow to move on.

We look more closely at how to define actions in Defining Workflow Nodes.

About Task Permissions

Finally, the Permissions tab lets you set the types of actions a Worklist user can perform for this task. The default setting is none. For this scenario, we have left the default setting, as shown in the following figure.

Figure 3-8 Start Order Processing Task: Permissions

 

For more information about task permissions, see "Defining Task Properties" in Defining Workflow Templates in Using the WebLogic Integration Studio, and Working with Tasks in Using the WebLogic Integration Worklist.

 

---

Understanding Workflow Expressions: Viewing the Set Workflow Variable and Assign Task to User Actions

Use the scroll bar at the bottom of the Actions list of the Task Properties dialog box to view the complete action definitions under the Activated tab. As you can see, they are defined as follows:

• Set workflow variable "OrderID" to expression: $OrderID + 1

• Assign task "Start Order Processing" to user WorkflowAttribute("Initiator")

To get more information about each of these actions, double-click each action. The properties dialog box for each action is displayed.

Figure 3-9 Set Workflow Variable Dialog Box

 

Figure 3-10 Assign Task to User Dialog Box

 

As you can see, both of these actions are defined by expressions. If you think of nodes as the building blocks of workflows, and actions as the building blocks of nodes, then you can think of expressions as the building blocks of actions. Expressions are statements that are evaluated at run time to calculate and supply a value. They can combine variables, constants, literals, operators, and predefined functions. One of the most common types of expressions you will define uses the XPath function to extract values from XML documents.

Some basic rules of the workflow expression language that you should know are:

• String literals must be surrounded by quotation marks (" ").

• Variable names must be preceded by a dollar sign ($) or a colon (:).

• Different element types can be concatenated with the plus sign (+) operator.

Thus, the expression for the first action specifies that the value for the OrderID variable should be incremented by 1 every time the workflow runs. You will see this in action when we run the workflows in Executing and Monitoring the Example Workflows.

The expression for the second action uses a built-in function to specify that the Start Order Processing task should be assigned to the same Worklist user who initiates the workflow.

We create expressions using the Expression Builder and the XPath Wizard in Defining Workflow Nodes.

For detailed information about the workflow expression language and functions, see Using Workflow Expressions in Using the WebLogic Integration Studio.

 

---

Posting an Internal XML Event: Editing the Neworder XML Document

To view the Post XML Event action:

1. In the Start Order Processing Task Properties dialog box, select the Executed tab.

2. Select the Post XML Event action, and click Update. The Post XML Event dialog box appears, with an XML document already defined.

   Figure 3-11 Post XML Event Dialog Box

   
    

When you post an XML event, you can specify various options, including the following:

• Destination—Internal JMS queue or external JMS topic or queue. The default destination is internal.

• Transaction mode—Send message when transaction commits or immediately. The default transaction mode is when transaction commits.

• XML message—A document that has been stored in an XML variable, or one that you create by composing it within the XML editor in the action's dialog box. The default setting is to compose a new document.

In our example, we use the default settings. In a production environment, you will probably also want to take advantage of the various JMS messaging and addressing options offered for posting XML events. For more information on all Post XML Event action options, see "Posting an XML Message to a JMS Topic or Queue" in Defining Actions in Using the WebLogic Integration Studio.

Editing the XML Document Structure

The XML document that is posted by this action simulates an XML document that would be sent by a servlet to the workflow. It contains information about the order and has the structure shown below.

Listing 3-1 Neworder XML Document

<neworder>
   <id>$OrderID</id>
   <shiptostate>KK</shiptostate>
   <status>new</status>
   <customer>
       <id>6831</id>
       <name>John Doe</name>
       <address>3126 Blue Street Anytown CA 96822</address>
       <phone>408 534 9567</phone>
       <email>[e-mail]</email>
   </customer>
   <item>
       <id>236</id>
       <name>CD storage rack</name>
	<quantity>2</quantity>
   </item>
</neworder>

The element values in this XML document will be extracted and stored in workflow variables by the Start node of the Order Processing workflow. Values will then be used throughout the Order Processing and Order Fulfillment workflows as indicated in the following table, which lists the variables, their uses in the workflow, and the XML elements to which they correspond.

Table 3-2 Neworder XML Elements

XML Element	Corresponding Workflow Variable	Use in Workflows
<status>	OrderStatus	Can change at various points of the workflow
<id>	OrderID	Value is provided by the workflow itself; appears as the workflow label in the Worklist and increments each time the workflow is run
<shiptostate>	ShipToState	Passed to the calculate() method of the POBean; the initial value will be caught by the exception handler
<customer> <id>	CustomerID	Used for the credit check task
<customer> <name>	CustomerName	Used for the customer notification task and is passed to the Order Fulfillment workflow for the shipping task
<customer> <address>	CustomerAddress	Passed to the Order Fulfillment workflow for the shipping task
<customer> <phone>	CustomerPhone	Used in the customer notification task
<customer> <email>	CustomerEmail	May be used in the order confirmation task
<item> <id>	ItemID	Passed to the checkInventory() and calculate() methods
<item> <name>	ItemName	Not used
<item> <quantity>	ItemQuantity	Passed to the checkInventory() and calculate() methods

 

Default values have been entered for each element. Note that the <shiptostate> element contains incorrect data, with the state abbreviation KK. This is used to simulate the possibility of invalid data being passed to the POBean EJB in the Order Fulfillment workflow, so that a custom exception handler can be triggered. (For more information, see Using a Custom Exception Handler.)

In Sending an E-mail Message: Defining the Confirm Order Fulfillment Task, you can define an action to send an e-mail. In the action definition, the e-mail address will be taken from the value provided in the XML document sent out by this Post XML Event action. If you would like to receive the e-mail sent to confirm the order at the end of the process when you run the workflows in Executing and Monitoring the Example Workflows, you can edit the XML document to specify your own real-world information.

Note: For this procedure to work at run time, your e-mail server must be appropriately configured in your server domain. For more information, see "Customizing Mail Session Properties" in Customizing WebLogic Integration in Starting, Stopping, and Customizing BEA WebLogic Integration.

To specify your own data, edit the XML document as follows:

1. In the XML Document Structure portion of the Post XML Event dialog box, expand the element nodes to view their values. Use the scroll bar to view additional fields.

   Figure 3-12 Neworder XML Document Structure

   
    

2. In the customer e-mail element value field, type in your own e-mail address, surrounded by quotation marks. Press Enter to enter the value.

   Note: Be sure to enter a valid e-mail address if you intend to specify the Send E-mail action in Sending an E-mail Message: Defining the Confirm Order Fulfillment Task.

3. If you like, edit values for the other customer and item attribute values to put in your own preferred information.

   Note: Do not edit the erroneous data in the shiptostate element value field. This value will be used at run time to invoke the exception handler in the Order Fulfillment workflow.

4. When done, click OK to save your changes and exit the Post XML Event dialog box.

 

---

Using the XML Repository: Exporting the Neworder XML Document

When you create or edit an XML document in the Studio, you can save it to a file on disk, or export it to the XML repository. The repository stores XML documents, DTDs, schemas, style sheets, and other entities for later access, and offers you a convenient way to export and import previously-defined XML documents for reuse by other nodes, workflows or even organizations.

Because the Order Processing workflow will reference the data stored in the XML document of our Start Order Processing task, storing the XML document in the repository will greatly simplify our task of defining XPath expressions to extract the data from the document in Defining XPath Statements.

To save the document to the repository:

1. In the Task Properties dialog box, under the Executed tab, double-click the Post internal XML Event action to display the Post XML Event dialog box.

   
    

2. In the toolbar, click the Export button . The XML Finder dialog box appears.

3. Select the Repository tab.

   Figure 3-13 XML Finder Dialog Box

   
    

4. To create a new folder in which to store the XML document, right-click the XML Repository folder, and from the pop-up menu, select Add Folder. The Add Folder dialog box appears.

   Figure 3-14 XML Finder: Add Folder Dialog Box

   
    

5. In the Name field, enter a name for the new folder, such as Tutorial, and click OK. The new folder now appears in the Repository window.

6. In the Repository window, right-click the new folder and from the pop-up menu, select Add Entity. The Add Entity dialog box appears.

   Figure 3-15 XML Finder: Add Entity Dialog Box

   
    

7. From the Type drop-down list, select XML Document.

8. In the Name field, enter a name for the document, such as Neworder, and click OK. This creates an empty container for the new document, which appears in the list of entities for the folder.

   Figure 3-16 XML Finder Dialog Box

   
    

9. Select the new document, and click OK to exit the XML Finder dialog box. The container is populated with the contents of the XML document you defined in the XML editor.

10. Click OK to exit the Post XML Event dialog box.

11. Click OK to exit the Task Properties dialog box.

 

---

Saving a Template Definition

You may notice that when you make changes to a template definition, its label in the folder tree and in the title bar of the workflow design window is preceded by an asterisk. This means that the template definition contains unsaved changes.

To save the workflow:

1. In the folder tree, expand the Order Processing Trigger template, and right-click the workflow template definition.

2. From the pop-up menu, select Save.

You are now ready to create and define the Order Processing workflow, as described in the following sections of the tutorial.