bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Using the Studio

Defining Actions

The following sections introduce and explain how to use WebLogic Integration actions to accomplish various workflow activities:

- Understanding Actions

- Overview of Action Definition Tasks

- Working with Actions

- Setting a Variable Value

- Controlling Program Flow

- Using Timed Operations

- Using Sub-Workflows

- Monitoring Run-Time Status

- Setting Up Manual Tasks

- Sending E-Mail Messages

- Invoking Components

- Posting an XML Message to a JMS Topic or Queue

- Transforming XML Documents

- Handling Exceptions

Understanding Actions

While nodes and connections serve to specify the logical sequence and control of business processes, it is actions that perform the real work of a workflow definition. An action is the most basic unit of a workflow that can perform some activity. This activity may be as simple as initializing a variable, or as complex as calling a custom application on a client system. Actions can be added to all types of nodes (except Joins), to exception handlers, and even to other actions.

The following sections provide important background information for using actions to perform activities in workflows. It includes:

- Action Categories

- Understanding Action Types and Placement

- Placing Actions in Task Nodes

Action Categories

Actions are organized into categories in the Studio. In this guide, however, we categorize actions into the major activities that you can perform. The following table lists the categories, the actions contained within them, the activities they accomplish, and the sections of the guide where each one is described in more detail.

Category | Actions | Use to . . .
--- | --- | ---
Task | Mark Task as Done Unmark Task Done Execute Task | Control main program flow For information, see Controlling Program Flow
Assign Task to User Assign Task to Role Assign Task Using Routing Table Unassign Task Set Task Comment Set Task Priority | Assign and set properties of manual tasks For more information, see Setting Up Manual Tasks.
Set Task Due Date | Set a due date for manual and non-manual tasks or introduce a time delay For more information, see Setting Up Manual Tasks.
Workflow | Mark Workflow as Done Abort Workflow | Control main program flow For information, see Controlling Program Flow
Start Workflow | Call a sub-workflow For more information, see Using Sub-Workflows.
Set Workflow Variable | Initialize variables For more information, see Setting a Variable Value.
Set Workflow Comment | Monitor run-time status For more information, see Monitoring Run-Time Status.
Integration | Perform Business Operation Call Program | Integrate the workflow with external software components, such as EJBs and Java classes, or executable programs. For more information, see Invoking Components.
Send XML to Client | Perform different operations on a Worklist or custom client system. For more information, see Setting Up Manual Tasks.
Post XML Event | Exchange XML messages between workflows, components, and applications. For more information, see Posting an XML Message to a JMS Topic or Queue.
XSL Transform | Transform an XML document from one format to another according to a style sheet. For more information, see Transforming XML Documents.
Exception Handling | Set Workflow Exception Handler Exit Exception Handler | Manage the exception handler(s) to be used for a workflow For more information, see Handling Workflow Exceptions.
Invoke Exception Handler | Call a sub-workflow to handle exceptions For more information, see Handling Workflow Exceptions.
Miscellaneous | No Operation Cancel Workflow Event | Control main program flow For information, see Controlling Program Flow.
Evaluate Condition | Embed a conditional sub-workflow For more information, see Using Sub-Workflows.
Timed Event | Embed a timed sub-workflow and introduce a time delay For more information, see Using Timed Operations.
Send E-Mail Message | Send e-mail to a user, role or external client For more information, see Sending E-Mail Messages.
Make Audit Entry | Monitor run-time status and debug workflow design For more information, see Monitoring Run-Time Status.

Understanding Action Types and Placement

In addition to the action categories presented by the Studio, such as Task, Workflow, Integration, Exception Handling, and Miscellaneous categories, you should be aware of other distinctions between actions and their behavior:

- Terminal actions versus non-terminal actions, which can contain other actions

- Synchronous versus asynchronous execution of actions or sub-actions, which allows parallel processing

These distinctions are significant, as they can affect the order in which workflow operations are executed. Each of these distinctions is described in more detail in the following sections.

Terminal Actions and Non-Terminal Actions

Most actions are terminal, meaning that they cannot contain any other actions. However, some actions allow you to define sub-actions inside of them that are performed according to specific conditions, depending on the nature of the parent action. The following actions can have sub-actions defined within them and are, therefore, non-terminal:

- Evaluate Condition—sub-actions may be performed according to the true or false result of a condition that you define.

- Timed Event—sub-actions are executed according to a date and time, and may be re-executed according to a schedule.

- Send XML to Client—sub-actions may be performed when the workflow receives a reply from the client application.

- Start Workflow—sub-actions may be performed when the called workflow is completed.

- Set Task Due Date — sub-actions may be performed after a due time on a task has passed.

Note that sub-actions are only visible in the Properties dialog box for these non-terminal actions, but do not appear in the folder tree.

The special relevance of non-terminal actions is that, while most terminal actions are always executed in a synchronous fashion, which means that the workflow waits until they have finished executing, non-terminal actions can perform operations that are executed in both a synchronous or asynchronous fashion. Asynchronous execution of non-terminal actions means that the workflow does not wait for the action's operations, or its sub-actions, to complete before proceeding, but continues to be processed in parallel. This distinction is explained in more detail in the next section.

Synchronous and Asynchronous Execution of Actions

All actions are synchronous, which means that the workflow does not proceed to the next action until the operations performed by the current action have completed, with the exception of the following:

- Call Program—This action invoke an executable which always runs in parallel with the workflow.

- Post XML Event—This action sends off an XML message in a "fire and forget" model, so that any workflows or applications that are triggered by the receipt of the message are executed in parallel. (However, for information on forcing a synchronous functioning of this action, see Posting an XML Message to a JMS Topic or Queue.)

However, the following actions, and any sub-actions they may contain, can be executed in a synchronous or asynchronous fashion, depending on how you place the action:

- Timed Event—sub-actions may be performed asynchronously or synchronously

- Send XML to Client—XML message transmission, receipt of reply, and optional callback sub-actions may be performed asynchronously or synchronously

- Start Workflow—the sub-workflow and optional sub-actions may be executed asynchronously or synchronously

- Set Task Due Date —optional overdue sub-actions may be performed asynchronously or synchronously

These non-terminal actions and their sub-actions are performed asynchronously in the following conditions:

- If the action is placed in a Start, Event, or Decision node.

- If the action is placed in a Task node, and the Mark Task as Done action is placed in the Task Properties, as in the following figure.

Figure 6-1 Non-Terminal Action in Task Node with Task Marked Done from Task Properties

In these cases, the action's operations, and any specified sub-actions, are simply performed in parallel with the subsequent nodes in the workflow, as illustrated in the following figure.

Figure 6-2 Asynchronous Execution of Workflow Actions

By contrast, non-terminal actions and their sub-actions are performed synchronously if the Task node in which they are placed is marked done in the action's properties, as illustrated in the following figure.

Figure 6-3 Non-Terminal Action with Task Marked Done in Action Properties

That is, the workflow waits until all operations and sub-actions are completed before proceeding to the next node, as illustrated in the following figure.

Figure 6-4 Synchronous Execution of Workflow Actions

More information on action design issues is provided in the following topics:

- Calling a Sub-Workflow

- Embedding a Timed Sequence

- Setting a Task Due Date

- Sending an XML Message to a Client Application

More information on marking tasks done is provided in the following sections.

Placing Actions in Task Nodes

When you use Task nodes, you need to know how to place actions in order to perform a particular activity. This requires that you do the following: place the action on the correct tab of the Task Properties dialog box (Activated or Executed), and mark the task done at the appropriate point. For more information on Task Properties dialog box tabs, see Understanding Task States.

Using the Activated and Executed Tabs

The only ways a task can be executed are:

- By using the Assign Task to User action to assign the task to a Worklist or custom client user, who executes it manually

- By using the Execute Task action

- Programmatically, through an API call.

Thus, in general, you can follow these guidelines when considering action placement:

- Any actions that should be performed before a user manually executes a task (or it is executed by the other means listed above) should be placed on the Activated tab.

- The Assign Task to User action is always placed at the end of the list on the Activated tab. Any actions listed after this action on the Activated tab are not performed.

- Place any actions to follow an Assign Task to User action on the Executed tab.

A detailed table with guidelines for using Task Properties dialog box tabs to perform each of the major activities identified in this guide is provided in Guidelines for Action Placement in Task Nodes.

Marking Tasks Done

All tasks must be marked done, either manually by a Worklist or custom client user, if the Mark Done Without Executing permission is assigned to the task (for more information, see About Task Permissions), or explicitly at design time by using the Mark Task as Done action.

If a task is not marked done, the workflow will not proceed from the Task node. Conversely, any actions that are listed after a Mark Task as Done action in the Task Properties dialog box are not performed, unless they are placed on the Marked Done tab of the Task Properties dialog box.

Note: In a similar fashion, any actions placed after the Mark Task as Done action in the action properties dialog box for a non-terminal action (as described in Synchronous and Asynchronous Execution of Actions) are not performed.

These are general guidelines you can use for marking tasks done:

- If the task does not contain an action that can execute it, place the Mark Task as Done action as the last action on the Activated tab, as shown in the following figure.

Figure 6-5 Marking Non-Executed Tasks Done

- If the task does contain an action that can execute it, such as Assign Task to User, or Execute task, place the Mark Task as Done action as the last action on the Executed tab.

  Figure 6-6 Marking Executed Tasks Done

- To perform a non-terminal action and its subactions asynchronously, place the Mark Task as Done action in the Task Properties dialog box, as the last action on the Activated or Executed tab as appropriate. (See Figure 6-1.)

- To perform a non-terminal action and its subactions synchronously, place the Mark Task as Done action as the last action in the action's properties dialog box. (See Figure 6-3.)

A detailed table with guidelines for using Task Properties dialog box tabs to perform each of the major activities identified in this guide is provided in the following section.

Guidelines for Action Placement in Task Nodes

In general, you should try to place actions in Task nodes only, and avoid using them in other types of nodes. You should also use shorter action lists in more Task nodes, rather than longer action lists in fewer Task nodes. Using a "shallow" or "flat" design approach ensures that the logic and transactional units of your workflows remain immediately apparent in their graphical representations.

In some cases, however, it will be necessary to specify more than one action in the same node, for example, when you need to specify various properties of a user-assigned task. (For more information, see Setting Up Manual Tasks.) Similarly, you may find it more efficient in some cases to simply add an action to nodes other than Tasks, or even to the action list in a Task node, rather than to complicate the graphical flow with an extra Task node. This may be the case for simple activities such as setting variable values, setting task or workflow comments, or making audit entries.

The following table provides guidelines you can use as a reference for designing reusable node patterns that perform major common activities.

Table 6-1 Guidelines for Action Placement

Activity | In a Task node, place this action . . . | on this tab . . . | Mark the task done on this tab . . . | For more information, see . . .
--- | --- | --- | --- | ---
Calling a Java Component | Perform Business Operation | Activated | Activated | Calling a Business Operation.
Calling an Executable Program | Call Program | Activated | Activated | Calling an Executable Program on the Server
Transforming XML Documents | XSL Transform | Activated | Activated | Transforming XML Documents
Sending E-mail | Send E-mail Message | Activated | Activated | Sending E-Mail Messages
Posting an XML Message to a JMS Topic or Queue | Post XML Event | Activate | Activated | Posting an XML Message to a JMS Topic or Queue
Using a Plug-In Action | custom action | Activated | Activated |
Assigning a Manual Task | Set Task Comment (optional) Set Task Due Date (optional) Assign Task to User/Role/Using Routing Table | Activated | Executed | Setting Up Manual Tasks
Send XML to Client (optional) | Executed | Callback Actions in the Send XML to Client dialog box | Sending an XML Message to a Client Application
Calling a Sub-Workflow Synchronously | Start Workflow | Activated | Actions tab in the Start Workflow dialog box | Calling a Sub-Workflow
Introducing a Time Delay | Set Task Due Date | Activated | Overdue Actions tab in the Set Task Due Date dialog box | Setting a Task Due Date
Timed Event | Activated | Actions when triggered tab in the Timed Event dialog box | Embedding a Timed Sequence

Overview of Action Definition Tasks

Once you have created a workflow and configured required resources, you can begin to add actions to nodes and other objects. Adding and defining actions is an iterative process, which will undoubtedly entail adding additional nodes, creating additional variables, reconfiguring data and resources, defining XML documents, and so on. Defining actions involves the following tasks, that you can perform in any order:

Note: You may also want to familiarize yourself with the workflow expression language and the Studio's Expression Builder and XPath Wizard tools before beginning to define actions, since most actions require entering expressions into dialog box fields. Complete information on workflow expressions is available in Using Workflow Expressions.

- Define business operations as described in Configuring Business Operations, in order to define a Perform Business Operation action.

- Optionally, define users, as described in Maintaining Users, to specify users for an Assign Task to User, Assign Task Using Routing Table, or Send E-mail Message action.

- Optionally, define roles, as described in Maintaining Roles, to specify roles for an Assign Task to Role, Assign Task Using Routing Table, or Send E-mail Message action.

- Optionally, define business calendars, as described in Administering Business Calendars, for a Timed Event or Set Task Due Date action. Alternatively, you can import previously exported calendars from existing workflow packages; see procedures in Importing Workflow Packages.

- Add nodes to a template definition. Procedures are given in Working with Nodes.

- Create variables to be referenced by actions. Procedures are given in Working with Variables.

- Add actions to Task nodes, and if necessary, Start, Event, and Decision nodes. Procedures for adding actions are given in Adding an Action.

- Add actions to non-terminal actions.

- Add the Mark Task as Done action to Task nodes or non-terminal actions. Procedures are given in Marking a Task Done.

- Add Exception Handlers. Procedures for defining exception handlers are given in Defining Exception Handlers.

- Add actions to exception handlers. Procedures for defining exception handlers are given in Defining Exception Handlers.

- Add additional nodes to the workflow to refine your design to ensure that each discrete activity is represented by a node. Procedures for adding nodes are given in Adding, Arranging, and Connecting Nodes.

- Compose or import XML documents that are required for any of the actions that embed XML documents into workflows, such as Post XML Event, Send XML to Client, and Set Workflow Variable. Procedures for working with XML documents with action properties dialog boxes are given in Working with XML Entities.

Working with Actions

You add and update actions in Task, Decision, Event, Done and Start node properties dialog boxes, as well as in custom Exception Handlers, and the action properties dialog boxes listed in Terminal Actions and Non-Terminal Actions. Each dialog box has an Actions tab which you use for action placement and maintenance. This section describes the functions that are common to all actions.

Adding an Action

To add an action:

1. Do one of the following:

   - In the design area, double-click the node to which you want to add the action, and in the Properties dialog box that appears, select the appropriate Action tab and click Add.

   - In the folder tree, expand the folder representing the object to which you want to add the action, right-click on the Actions folder, and, from the dialog box that appears, select Create Action.

   The Add Action dialog box is displayed.

   Figure 6-7 Add Action Dialog Box

   Note: If a plug-in is defined for actions, this dialog box contains the new action.

2. Double-click an action type folder to expand it, select an action, and click OK. A properties dialog box specific to the selected action is displayed.

3. Complete the fields in the dialog box and click OK. Detailed procedures for each action type are provided in the remainder of this guide.

   The action is added to the properties dialog box for the node you selected and immediately appears in the folder tree under the folder representing the node or exception handler that contains it.

Updating an Action

To update an action:

1. Do one of the following:

   - In the properties dialog box which contains the action you want to update, select the appropriate action and click Update.

   - In the folder tree, expand the folder that contains the action you want to update, right-click the action, and from the pop-up menu, select Properties.

   The properties dialog box for the selected action is displayed.

2. Make changes to the action definition as desired, and click OK when done.

Deleting an Action

To delete an action:

1. Do one of the following:

   - In the properties dialog box which contains the action you want to delete, select the appropriate action and click Delete.

   - In the folder tree, expand the folder that contains the action you want to delete, right-click the action, and from the pop-up menu, select Delete.

2. When prompted by a warning message, click OK to confirm the deletion, or Cancel to cancel.

Copying an Action

You can copy actions within or between a workflow node within or between workflow template definitions (and templates) to create reusable design patterns. Since any properties that have been defined within the action are also copied, you can save time by simply making minor modifications to the action.

Note: If you are copying actions between template definitions, be sure that any variables referenced by the action have been created in the target template definition, and that other referenced objects, such as roles, users, or business calendars, are defined for the organization with which the template is associated.

To copy an action and its properties within or between nodes:

1. Do one of the following:

   - In the design area, double-click the node that contains the action you want to copy. In the Properties dialog box, select the appropriate Actions tab, right-click the action, and select Copy from the popup menu.

   - In the folder tree, expand the folder which contains the action you want to copy, right-click the action you want to copy, and, from popup menu, select Copy.

2. If you are pasting to a different node or template definition, do one of the following:

   - Click OK to close the node Properties dialog, and from the design area of the target template definition, right-click the node shape to which you will paste the defined action. In the Properties dialog box, select the appropriate Actions tab, right-click, and select Paste from the pop-up menu.

   - In the folder tree, expand the folder in which you want to paste the action, right-click the Actions folder, and select Paste from the pop-up menu.

   The properties dialog box for the action is displayed, with all settings copied from the source action.

3. In the action's properties dialog box, make any changes to the settings as necessary.

4. Click OK to save the changes and add the action to the target object.

Reordering Actions

Actions are displayed in the sequence that they will be executed. To re-sequence actions, select an action from the list in the Properties dialog box and press the up or down arrow to move its position in the list.

Adding Notes to an Action

All action properties dialog boxes contain a Notes text box in which you can enter a comment about the action. This is helpful for other users who access the same workflow and need to understand the workflow logic or design.

Figure 6-8 Notes Text Box

Setting a Variable Value

You use the Set Workflow Variable action to assign a value to an existing workflow variable at any point in the workflow, in any type of node. For example, to design a loop, you can use this action to increment a counter. For details about defining variables, see Working with Variables.

The value you assign to the variable can be an expression or a constant. The expression is evaluated at run time when the action is executed, and the result assigned to the variable you specify.

You can also use this action to compose or import an existing XML document and store the content in an XML or string type variable. You can then reuse the variable to reference the XML content in various places in a workflow, such as for posting an XML event action (see Posting an XML Message to a JMS Topic or Queue).

Note: For non-XML variables, you can also use the Variables tab of Start and Event node, Send XML to Client, and Exception Handler properties dialog boxes to set variable values.

Figure 6-9 Set Workflow Variable Dialog Box

To assign a value to a variable:

1. From the Workflow Actions folder in the Add Action dialog box, select Set Workflow Variable and click OK to display the Set Workflow Variable dialog box.

2. From the Variable to be set drop-down list, select an existing variable to which you will assign a value, or type one in. (For details, see Working with Variables.)

3. Choose one of the following options:

   - From Expression — enter an expression that is evaluated at run time to produce the value. For information on workflow expression components and syntax, see Using Workflow Expressions. To enter a constant, use the syntax described in Using Literals.

   - By Composing — set the value for an XML or string type variable by specifying an XML document. To create a new free-form document, click the Add Child button to begin adding nodes. To specify an existing XML document, click the Import button to load the document and edit as necessary. To create a new type-specified XML document, click the Set Content Type button to load a Schema document. For detailed procedures on all these options, see Composing and Editing XML Documents.

   The XML document you define is stored in the workflow template definition.

   Note: An XML document that is stored in a string type variable will first be converted to a string.

4. Click OK to add the Set Workflow Variable action.

Controlling Program Flow

In general, you should try to control the program flow through the use of nodes and connections. In some cases, however, you may need to specify alternate paths of execution from within nodes. For example, you may have an event defined that should only be allowed to be triggered up until a certain node in the workflow, and then should be disabled. Or you may need to automatically execute a task from within a different node, depending on a condition. Most importantly, you can control whether sub-actions or even entire sub-workflows are to be performed synchronously or asynchronously by the placement of the Mark Task as Done action.

Thus, the following actions may be used for program control:

- Mark Task as Done—In addition to manual tasks executed by users, you need to mark task nodes as done that contain entirely automatic actions, to ensure that the flow proceeds correctly. This action is key to ensuring your workflows execute as desired, and is described in Marking a Task Done.

- Unmark Task Done—Unmarks a task done that has already been marked done. Described in Unmarking a Task Done.

- Cancel Workflow Event—Cancels an event that you specify, ensuring that it can no longer be triggered after this point in the workflow. Described in Canceling a Workflow Event.

- Mark Workflow Done—This action has the same effect as proceeding to a done node. Described in Marking a Workflow Done.

- Abort Workflow—Terminates a running instance and removes it from the database. Described in Aborting a Workflow.

- Execute Task—Automatically executes a task node and performs any actions listed on the Executed tab of the node. Described in Executing a Task Automatically.

- No Operation—This action does not actually have any effect on the workflow, but acts as a placeholder for the workflow designer. It is described in Adding a Placeholder Action.

- Timed Event—Can be used to create a time delay in a workflow. Described in Embedding a Timed Sequence.

- Set Task Due Date—Can be used to create a time delay in a workflow. Described in Setting a Task Due Date.

Marking a Task Done

Unless a user-assigned task is defined with a permission to allow a user to manually mark the task done at run time (for information, see Defining Task Properties), every Task node must specify the Mark Task as Done action either in its Task Properties dialog box, or in the Actions tab of a non-terminal action. For more information on using this action, see Understanding Action Types and Placement.

Figure 6-10 Mark Task as Done Dialog Box

To mark a task done:

1. From the Task Actions folder in the Add Action dialog box, select Mark Task as Done and click OK to display the Mark Task as Done dialog box.

2. In the Task to mark as done field, select the task that is to be marked done when the action is executed. Only one task at a time can be selected.

3. Click OK to add the Mark Task as Done action.

Unmarking a Task Done

The Unmark Task Done action marks the task as not done. A task that is assigned this action becomes Active on the Worklist and can be executed again. Use this action to allow a task to be executed again in, for example, a loop or a parallel workflow.

Note: A task that is marked not done does not have its activated state triggered again. To trigger the activated state for the task, the workflow must initiate the task again. For details about task states, see Understanding Task States.

Figure 6-11 Unmark Task Done Dialog Box

To unmark a task done:

1. From the Task Actions folder in the Add Action dialog box, select Unmark Task as Done and click OK to display the Unmark Task Done dialog box.

2. In the Task to unmark as done field, select the task that is to be marked done when the action is executed. Only one task at a time can be selected.

3. Click OK to add the Unmark Task as Done action.

Canceling a Workflow Event

Use the Cancel Workflow Event action when you want to cancel an Event node or nodes that have been defined within a workflow. This action prevents an event from being triggered after a certain point in a workflow, so you can use it as an "expiry" mechanism for the Event node. For example, in an order processing workflow, you may have an event that waits for a cancellation notice from a customer, and performs some actions accordingly; to ensure that the cancellation cannot be issued after the order is shipped, you can define the Cancel Workflow action at the point where the shipping task is executed in the workflow, to disable the order cancellation event from being triggered.

Figure 6-12 Cancel Workflow Event Dialog Box

To cancel an event:

1. From the Miscellaneous Actions folder in the Add Action dialog box, select Cancel Workflow Event and click OK to display the Cancel Workflow Event dialog box.

2. In the Event to Cancel field, highlight the workflow event to be canceled. (Hold down the CTRL key to highlight more than one event.)

3. Click OK to add the Cancel Workflow Event action.

Marking a Workflow Done

The Mark Workflow as Done action marks the current workflow as done and serves the same purpose as a workflow reaching a Done node. It could be used, for example, in a Decision node, where you would like to skip all intervening actions before the Done node and terminate the workflow at that point.

Figure 6-13 Mark Workflow as Done

To mark a workflow as done:

1. From the Workflow Actions folder in the Add Action dialog box, select Mark Workflow as Done and click OK to display the Mark Workflow as Done dialog box.

2. Click OK to add the Mark Workflow as Done action.

Aborting a Workflow

The Abort Workflow action permanently stops a workflow that is currently in process. This action can be used in exceptional conditions where an instance must be terminated.

Note: A workflow instance that is aborted will be deleted from the database, and cannot be monitored. To specify that a workflow should simply terminate, while retaining a record of the instance, you should use a Done node or the Mark Workflow as Done action.

Figure 6-14 Abort Workflow Dialog Box

To abort a workflow:

1. From the Workflow Actions folder in the Add Action dialog box, select Abort Workflow and click OK to display the Abort Workflow dialog box.

2. Click OK to add the Abort Workflow action.

Executing a Task Automatically

You can use the Execute Task action to allow the workflow, rather than a user, to execute any task in the workflow explicitly. This action places the task in the executed state, and performs all the actions listed in the Executed tab of the Task Properties dialog box. For information on task states, see Understanding Task States.

You may use this action, for example, from within an exception handler, when you want to re-execute actions in a task node after the actions in the exception handler have been completed. Or you might use it to create a loop that would be too difficult to represent graphically.

Figure 6-15 Execute Task Dialog Box

To execute a task automatically:

1. From the Task Actions folder in the Add Action dialog box, select Execute Task and click OK to display the Execute Task dialog box.

2. In the Task to execute field, select the task that you want to execute. Only one task at a time can be selected.

3. Click OK to add the Execute Task action.

Adding a Placeholder Action

The No Operation action does not affect the workflow; it simply acts as a placeholder to remind an analyst to add an action at a later time.

Figure 6-16 No Operation Dialog Box

To add a placeholder action:

1. From the Miscellaneous Actions folder in the Add Action dialog box, select No Operation and click OK to display the No Operation dialog box.

2. In the Description field, enter a descriptive name for the No Operation action, preferably a name that will remind you to add an action at a later time.

3. Click OK to add the No Operation action.

Using Timed Operations

The following actions allow you to set up timed operations:

- Timed Event—Specifies a series of sub-actions that should be performed and, optionally, re-executed, according to an exact time schedule. Can also be used to create a time delay in a workflow. Described in Embedding a Timed Sequence.

- Set Task Due Date—Specifies a date by which a task should be executed and, optionally, a series of sub-actions to be performed after the due date. Can also be used to introduce a time delay in a workflow. Described in Setting a Task Due Date.

Embedding a Timed Sequence

You can use the Timed Event action to create a timed sequence of actions that will be triggered at an exact time and date and be optionally re-executed according to a specified schedule.

About Execution Schedules

If you want to reschedule timed events, you must specify an execution stop method, according to two options:

- When the workflow is done. In this case, the timed event is re-executed until the workflow is done.

- When the task is done. In this case, the timed event is re-executed until the Task node that contains it is marked done. This option should only be used if two conditions are met:

- The Timed Event action is specified in a Task node.

- The containing Task node is marked done from outside the task node itself, such as from a Decision node, or another action. The node cannot be marked done from within the Task node, or from within the Timed Event dialog box's sub-actions tab, because marking the task done in this fashion would effectively terminate any repeated execution of the timed event.

Executing Triggered Actions Asynchronously and Synchronously

Actions specified in a timed sequence can be performed in either a synchronous or asynchronous mode. In asynchronous mode, the sub-actions are performed in parallel, while the workflow continues to the next node. To set up the action in this way, you use the Timed Event in a Task node and mark the task containing the action done in the task node itself, or in any other type of node.

In synchronous mode, this action can serve to create a time delay in the workflow, as the workflow must wait until the trigger date and time are reached, and any sub-actions are performed, before it proceeds. To set up the action in this way, you must use the action in a Task node, and add the Mark Task as Done action to the Actions when Triggered tab of the Timed Event dialog box.

Note that in all of these cases, if you want to reschedule the timed event, you should stop the execution only when the workflow is done.

Figure 6-17 Timed Event: Trigger Event Tab

Defining a Timed Event

To define a timed event:

1. From the Miscellaneous Actions folder in the Add Action dialog box, select Timed Event and click OK to display the Timed Event dialog box.

2. On the Trigger Event tab, specify the time at which the sub-actions should be performed, by selecting one of the following options:

   - From action execution—Select this option to start the triggered actions at a specific interval of time after the timed event is executed, that is, when the Timed Event action is reached in a node's action list. Use the drop-down list to the right to select the unit of time, and in the field to the left, enter a number. For example, if you choose "4 Minutes," the sub-actions will be executed four minutes after the Timed Event action is reached in the workflow.

   - To Expression—Select this option to specify an absolute or relative date and time that you define by entering an expression in the field.

3. If you selected To Expression, enter a date function in the field to return a Java Date object, as follows:

   - Use the StringToDate() function to specify an absolute date and time value. For details, see StringToDate().

   - Use the DateAdd() function to specify a value relative to a constant or variable base date and time. For details, see DateAdd().

4. If you do not specify a business calendar as a parameter in the DateAdd() function, optionally, specify a business calendar as follows:

   - For Organization — use the business calendar assigned to the organization for which the workflow template definition instance will be executed.

   - For Assignee — only if the timed event is defined in a task node that assigns a manual task to a user, use the calendar that belongs to the user or role assigned the task that contains the event to be triggered.

5. Optionally, on the Execution Schedule tab, to repeat the triggered actions, in the Reschedule every field, enter a value to represent the interval of time that should elapse between each re-execution of the triggered actions, and select a unit of time from the drop-down list. For example, if you choose "4 Minutes," the sub-actions will be performed every four minutes after the initial triggering until specified execution stop.

   Set the Recoverable checkbox to indicate whether or not you would like a timed event to be recovered (that is, deferred until the server restarts) or skipped, if the server is not running at its scheduled start time.

   Figure 6-18 Timed Event: Execution Schedule tab

6. If you specified an execution schedule, select a Stop execution when option to specify when the trigger should stop:

   - Workflow is done—Select to stop the trigger when the entire workflow is completed.

   - Task is done—Select to stop the trigger will stop when the task in which this action is specified is marked as done. Select this option only if the Timed Event action is specified in a Task node, and the Task node is marked done from outside the node, and outside the action. For more information, see About Execution Schedules.

7. On the Actions when triggered tab, click Add to open the Add Action dialog box to select and define the sub-actions to be executed when the event is triggered. If you want to ensure that sub-actions are performed synchronously, or you want to use this action to create a time delay in the workflow, add the Mark Task as Done action at the end of the action list here. In the Mark Task as Done dialog box, select the Task node containing the Timed Event action.

8. Click OK to add the Timed Event action.

Using Sub-Workflows

Several actions allow you to specify sub-workflows that are not represented in the design area. These are described below.

Note: You can also invoke a sub-workflow by posting an XML message to an internal JMS queue to start an event-triggered workflow. For more information, see Posting an XML Message to a JMS Topic or Queue.

- Start Workflow—Calls an entirely different workflow, that has been defined with a called Start. Described in Calling a Sub-Workflow.

- Evaluate Condition—Embeds a decision branch within a single node, by specifying alternate sub-actions to be performed according to a true or false result of a condition. Described in Embedding a Conditional Sequence.

- Timed Event—Specifies a series of sub-actions that should be performed and, optionally, re-executed, according to an exact time schedule. Described in Embedding a Timed Sequence.

- Invoke Exception Handler—Calls a series of sub-actions that are defined within an exception handler at a given point in the workflow, regardless of whether an exception has occurred. For information about this action, see Handling Workflow Exceptions.

Calling a Sub-Workflow

You may want to organize your processes into multiple workflows to break down large, complex workflows into multiple parts, or to use sub-workflows for processes that are only invoked according to specific conditions.

You can use the Start Workflow action to start another workflow from the current one. The workflow being started is referred to as a sub-workflow, or as a called or child workflow. The workflow that starts the sub-workflow is called the calling or parent workflow.

In order for a workflow to be called, the workflow template must contain at least one template definition that contains a Called Start node, is marked active, and specifies currently valid effective and expiry dates. Only one workflow template definition within that workflow template can be started at a time, this being the most effective of the active workflow template definitions. For an explanation, see Working with Template Definitions.

Passing Parameters

If the sub-workflow has any variables defined as input parameters, this means that it expects to populate those variables with values received from the parent workflow. Thus, in the Start Workflow action properties, you must specify values to be passed as input parameters to the sub-workflow; usually these values will be taken from corresponding variables defined in the parent workflow.

Similarly, if the sub-workflow has any variables defined as output parameters, this means that the sub-workflow will pass values it has obtained or calculated back to the parent workflow. Again, in the Start Workflow action properties, you need to specify parent workflow variables that are to receive those result values.

Executing the Sub-Workflow Asynchronously or Synchronously

The Start Workflow action can be used to start a workflow in both synchronous and asynchronous modes. In synchronous mode, the calling workflow waits for the sub-workflow to complete before proceeding to the next node. To set up the action this way, you must use the Start Workflow action in a Start or Decision node, or in a Task node, and mark the task done as a sub-action of the Start Workflow action, rather than in the Task node.

In asynchronous mode, the calling workflow does not wait for the called workflow to complete, but continues to the next node, so that both workflows execute in parallel. To set up the action in this way, you can use it in a Task node, and mark the task done in the Task node itself, or use it in any other type of node, such as a Decision, Start, or Event.

Note: You can also cause another workflow to be executed both asynchronously or synchronously by posting an XML message to an internal JMS queue to trigger an event-triggered workflow. Interaction between the two workflows, including parameter passing, is accomplished through XML/JMS messaging, and control of execution is accomplished by the use of Event nodes in the parent workflow to receive responses back from the sub-workflow. In fact, if you are running WebLogic Integration in a clustered environment, this method provides better load balancing control. For more information, see Posting an XML Message to a JMS Topic or Queue.

Regardless of whether or not the parent workflow waits for the sub-workflow to finish executing before proceeding, you can also define an optional set of sub-actions that are performed when the called workflow has completed.

Tracking the Sub-Workflow

You can assign the called workflow instance ID to a variable defined in the calling workflow. The instance ID is returned as a string, so be sure that the variable you create is defined as a String type (for procedures, see Working with Variables). The calling workflow can then use the reference variable in expressions using the WorkflowVariable() function to retrieve variables from the called sub-workflow. For details about using the instance ID in the WorkflowVariable() function, see Obtaining Run-time Workflow Data.

Figure 6-19 Start Workflow Dialog Box

To call a sub-workflow:

1. From the Workflow Actions folder in the Add Action dialog box, select Start Workflow and click OK to display the Start Workflow dialog box.

2. In the Workflow to Start field, select the workflow template to start when the action is executed. This field displays all workflow templates associated with the current organization that contain at least one template definition with a called start, currently valid effective and expiry dates, and that is marked active. When you have selected a workflow, any variables that have been defined as input or output in that workflow appear on the Parameters and Results tabs at the bottom of the dialog box.

3. In the Start in Organization field, select one of the following options:

   - Current organization — select to start the workflow in the current organization (the organization selected from the Organization drop-down list above the folder tree).

   - Expression — select to start the workflow for an organization determined at run time by a workflow expression, and enter a string, surrounded by quotation marks, that specifies the organization, or an expression that will be evaluated at run time and become the name of an organization. For example, this could be a variable that has previously stored organization information from an incoming XML message received by another node.

4. Optionally, from the Reference via field, select a variable from the list of variables available for the current workflow. When the called workflow is instantiated, its instance ID is assigned automatically to the selected variable.

   Note: The variable must be a string type.

5. From the Parameters list on the Parameters tab, select a parameter and click Update to display the Set Parameter dialog box, which you use to specify a value to pass to the called workflow.

   Figure 6-20 Set Parameter Dialog Box

6. In the Expression field, enter the value to be passed to the sub-workflow as an expression. The value will typically consist of a corresponding variable value in the parent workflow.

7. Click OK. The parameter and its value appear in the list on the Parameters tab of the Start Workflow dialog box.

8. Repeat steps 5 to 7 for all parameters in the list.

9. From the Results list on the Results tab, select a result and click Update to display the Set Variable from Result Parameter dialog box, which you use to specify the variable in the parent workflow in which you want to store the value returned by the sub-workflow.

   Figure 6-21 Set Variable from Result Dialog Box

10. From the Variable drop-down list, select a variable in which to store the value returned by the corresponding output variable defined in the sub-workflow.

11. Click OK. The result and its value appear in the list on the Result tab of the Start Workflow dialog box.

12. Repeat steps 8 to 10 for all results in the list.

13. Optionally, select the Actions tab and click Add to display the Add Action dialog box to select and define sub-actions to be performed when the sub-workflow has completed. If you want the sub-workflow to complete before any other nodes are executed in the parent workflow, be sure to add the Mark Task as Done action to this tab. In the Mark Task as Done dialog box, select the Task node in which you have specified the Start Workflow action.

14. Click OK to add the Start Workflow action.

Embedding a Conditional Sequence

The Evaluate Condition action functions in the same way as a Decision node, that is, to evaluate a conditional expression at run time and perform alternative sequences of sub-actions depending on the result. Normally, you should use a Decision node to accomplish this type of flow. However, there may cases where you want to embed a conditional sub-workflow within a main workflow, by specifying a conditional set of actions inside another node, rather than as a distinct node on its own. This is necessary in cases where there is no other way to specify a condition, such as in an Exception Handler.

You define a series of actions to be performed if the condition evaluates to true, and/or a series of actions to perform if the condition evaluates to false.

Figure 6-22 Evaluate Condition Dialog Box

To evaluate a condition:

1. From the Miscellaneous Actions folder in the Add Action dialog box, select Evaluate Condition and click OK to display the Evaluate Condition dialog box.

2. In the Condition field, enter a valid workflow condition that will be evaluated at run time to determine which set of sub-actions to perform. For more information on constructing expressions, see Using Workflow Expressions.

3. On the False and/or True tab, click Add to invoke the Add Action dialog box and select and define the sub-actions to be executed if the condition evaluates to false or true, respectively, by using the following buttons:

4. Click OK to add the Evaluate Condition action.

Monitoring Run-Time Status

You can use two actions for workflow monitoring purposes:

- Make Audit Entry—Adds an entry whose content you specify to an audit log maintained for running workflow instances. Described in Making an Audit Entry.

- Set Workflow Comment—Displays explanatory or instructive comment to an administrator monitoring a workflow instance at run time in the Studio. Described in Setting Up a Workflow Comment.

Making an Audit Entry

WebLogic Integration provides a default audit facility whereby all major user interactions and changes are published to a JMS topic and to a log file, myserver.log, located in the logs directory of the active WebLogic Integration domain on the server.

You can use the Make Audit Entry action in any node in your workflow to define additional run-time workflow information you would like to publish to the audit log over the course of a workflow. The date and time of each entry is noted, and you define an expression that will provide the data you want to record at run time, containing variables, functions or constants. For example, you could use the CurrentUser() function in a task that is assigned to a role, to record the user who executed it. (For information on functions that return run-time workflow information, see Obtaining Run-time Workflow Data.)

Note: Auditing must be enabled in the Template Definition properties dialog box for the workflow for this action to take effect. For further information, see Creating a Workflow Template Definition.

Figure 6-23 Make Audit Entry Dialog Box

To make an audit entry:

1. From the Miscellaneous Actions folder in the Add Action dialog box, select Make Audit Entry and click OK to display the Make Audit Entry dialog box.

2. In the Audit entry expression field, enter an expression that will be evaluated to to produce the audit entry information at run time. For more information on constructing expressions, see Using Workflow Expressions.

3. Click OK to add the action.

Setting Up a Workflow Comment

You can use the Set Workflow Comment action to specify a comment for the workflow instance. The comment will be displayed in the Comment column of the Workflow Instances dialog box of the Studio when the action is executed at run time (for more information, see Working with Workflow Instances). The text is typically informative and indicates the status of the workflow at that point.

Figure 6-24 Set Workflow Comment Dialog Box

To set a workflow comment:

1. From the Workflow Actions folder in the Add Action dialog box, select Set Workflow Comment and click OK to display the Set Workflow Comment dialog box.

2. In the Comment field, enter an expression that will be evaluated at run time to produce the comment. The expression will typically consist of strings and variables. For more information on expressions and their syntax, see Using Workflow Expressions.

   Note: Workflow comments are limited to a maximum of 254 characters. The comment length is not determined until run time because the length of expressions may vary. Comments exceeding the 254-character limit are truncated at run time with no warning.

3. Click OK to add the Set Workflow Comment action.

Setting Up Manual Tasks

You can use the following Task actions to assign manual tasks or interact with WebLogic Integration Worklist or custom client application users.

- Assign Task to User—Assigns a manual task to a specific user or to a user based on workload balancing. Described in Assigning a Task to a User.

- Assign Task to Role—Assigns a manual task to a role. Described in Assigning a Task to a Role.

- Assign Task Using Routing Table—Assigns the same task to different users or roles, depending on conditions that you specify. Described in Assigning a Task Using a Routing Table.

- Set Task Due Date—Specifies a due date by which the assignee should execute the task. Described in Setting a Task Due Date.

- Set Task Comment—Displays a comment or instruction for the user executing the task at run time. Described in Setting a Task Comment.

- Set Task Priority—Displays a priority level for the task to the user at run time. Described in Setting a Task Priority.

- Unassign Task—Unassigns a task. Described in Unassigning a Task.

- Send XML to Client—Sends an XML message to the Worklist or custom client application, to display a form or prompt to a user, or call a program or custom extension on the client. Described in Sending an XML Message to a Client Application.

Guidelines for Placement of Task Actions

When assigning manual tasks, follow these guidelines for action placement:

- You must place all actions pertaining to the same task in the same Task node.

- To ensure that a comment or due date is displayed to the user who views the task before he or she executes it, you should place the Set Task Comment and Set Task Due Date actions before the Assign Task to User/Role/Using Routing Table actions.

- Mark the task done on the Executed tab of the task Properties dialog box.

- If you want to send an XML message to the client application to display a prompt message or call additional software components on the client, first assign the task to a user or role, and then place the Send XML to Client action on the Executed tab of the Task Properties dialog box.

Assigning a Task to a User

Use the Assign Task to User action to assign a specified task to an individual user. Assigning a task to a user causes a notification to be sent to the user who views and executes the task from the Worklist or custom client application. For more information about the Worklist application, see Using the WebLogic Integration Worklist

.

You can specify a particular user to whom to assign the task, or you can specify a role member, which causes the system to determine the user with the fewest pending tasks among all users belonging to a particular role at run time. The system then assigns the task to that user. The user or role can be specified as a constant or taken from a workflow expression to be provided at run time.

Figure 6-25 Assign Task to User Dialog Box

To assign a task to a user:

1. From the Task Actions folder in the Add Action dialog box, select Assign Task to User and click OK to display the Assign Task to User dialog box.

2. In the Task to assign field, select the task that you want to assign. Only one task at a time can be selected.

3. To specify a user, select from the following options:

   - To specify a user name, select the name from the User drop-down list. Only users associated with the current organization appear in this list.

   - To assign the task to a role member, select the Assign to role member, and in the User in Role drop-down list that appears, select the Role name. Only roles defined for the current organization appear in this list. At run-time the user belonging to that role who has the fewest tasks assigned to him/her will be assigned the task.

   - To specify a user whose identity will be determined at run time, select Use Workflow Expression, and in the User field, enter an expression that returns the appropriate user at run-time.

4. Click OK to add the Assign Task to User action.

Assigning a Task to a Role

Use can use the Assign Task to Role action when it is not desirable to assign a task to a particular user. Assigning a task to a role allows any user who belongs to the role to view and execute the task, although there is no explicit notification of the task in the Worklist.

To assign a task to a role, you specify the role name or provide an expression to determine the role at run time.

Figure 6-26 Assign Task to Role Dialog Box

To assign a task to a role:

1. From the Task Actions folder in the Add Action dialog box, select Assign Task to Role and click OK to display the Assign Task to Role dialog box.

2. In the Task to assign field, select the task that you want to assign. Only one task at a time can be selected.

3. To specify a role, select from the following options:

   - To specify a role name, select the name from the Role drop-down list. Only roles defined in the current organization appear in this list.

   - To specify a role whose identity will be determined at run time, select Use Workflow Expression, and in the Role field, enter an expression that returns the appropriate role at run-time. For more information on functions and expressions, and expression syntax, see Using Workflow Expressions.

4. Click OK to add the Assign Task to Role action.

Assigning a Task Using a Routing Table

You can assign a task to different users or roles depending on a set of conditions. A routing table consists of a sequence of one or more routing conditions. A routing condition specifies a potential assignee (user or role) for the task, together with a specification of the conditions under which the assignment should be made. When the action is executed at run time, the system evaluates each condition in sequence until it encounters one that yields a True result. If such a condition is encountered, the task is assigned to the corresponding user or role, and any subsequent conditions are ignored.

Note: If no routing condition is satisfied, a run-time exception occurs.

If you would like to route all tasks for a particular user or role for a specific period of time, instead of when certain conditions are met, create a routing specification for an organization. For more information, see Administering Task Routings.

Note: The Routing feature reroutes only tasks assigned to a user; it does not reroute tasks assigned to a role. Rerouted tasks can, however, be directed to another user, user in role, or role. To reroute tasks assigned to a role, see Changing the Mapping for Roles.

Figure 6-27 Assign Task Using Routing Table Dialog Box

To assign a task using a routing table:

1. From the Task Actions folder in the Add Action dialog box, select Assign Task Using Routing Table and click OK to display the Assign Task Using Routing Table dialog box.

2. In the Task to assign field, select the task that you want to assign. Only one task at a time can be selected.

3. Next to the Routing Table field, click add to display the Define Routing Condition dialog box.

   Figure 6-28 Define Routing Condition Dialog Box

4. In the Condition field, enter a valid workflow conditional expression that yields a logical result (True or False). For information on constructing expressions, see Using Workflow Expressions.

5. In the Assign To field, select one of the following options: User, User in Role, or Role.

6. In the drop-down list, select the desired user or role name.

7. Click OK to add the routing condition to the routing table.

8. Continue to add as many routing conditions as required. Use the Delete button to delete a routing, the Update button to edit a routing, and the arrow keys to re-order routings in the table.

9. Click OK to add the Assign Task Using Routing Table action.

Setting a Task Due Date

You can use the Set Task Due Date action to set the due date by which a task should be executed. The due date is displayed to the Worklist or custom client user to whom the task has been assigned. You can express the due date in minutes, hours, days, weeks, or months, or as an expression to determine the date and time at run time.

You can also use this action for non-manual tasks, without the use of the Assign Task to User action, to specify actions to be performed in parallel after a certain date, or to introduce a time delay into a workflow.

Executing Overdue Actions Asynchronously and Synchronously

If the task is not executed by the due date, you can specify sub-actions that should be performed after the due date, in either a synchronous or asynchronous mode. In asynchronous mode, the sub-actions are performed in parallel, while the workflow continues to the next node. To set up the action in this way, you mark the task containing the action done in the Task node itself. This is normally how the action is used for manually assigned tasks.

In synchronous mode, this action can serve to create a time delay in the workflow, as the workflow must wait until the due date is reached, and any overdue actions are performed, before it proceeds. To set up the action in this way, you place the action in a Task that is assigned to a user or not, and mark the task containing the action done by adding the Mark Task as Done action to the Overdue Actions tab of the Set Task Due Date dialog box.

Figure 6-29 Set Task Due Date Dialog Box

To set a task due date:

1. From the Task Actions folder in the Add Action dialog box, select Set Task Due Date and click OK to display the Set Task Due Date dialog box.

2. In the Task for which to set due date field, select the task that is to have its due date set when the action is executed. Only one task at a time can be selected.

3. On the Due Date tab, in the Set to expression field, enter an expression to specify an absolute or relative date and time. The expression must return a Java Date object, so you must use a function, as follows:

   - Use the StringToDate() function to specify an absolute date and time value. For details, see StringToDate().

   - Use the DateAdd() function to specify a value relative to a constant or variable base date and time. For details, see DateAdd().

4. If you do not specify a business calendar as a parameter in the DateAdd() function, optionally, specify a business calendar as follows:

   - For Organization — use the business calendar assigned to the organization for which the workflow template definition instance will be executed.

   - For Assignee — only if the due date is defined in a task node that assigns a manual task to a user, use the calendar that belongs to the user or role assigned the task that contains the Set Due Date action.

5. Optionally, select the Overdue Actions tab and click Add to display the Add Action dialog box to select and define sub-actions to be performed when the due date is reached. If you want the workflow to wait until the due date is reached before proceeding, use the action in a Task node, and be sure to add the Mark Task as Done action to this tab. In the Mark Task as Done dialog box, select the Task node in which you have specified the Set Due Date action.

6. Click OK to add the Set Task Due Date action.

Setting a Task Comment

You can use the Set Task Comment action to set a comment for the task instance, which displays a text message to a user viewing the task in the Worklist or the Studio when the action is executed at run time. The text typically provides information or instructions for manual work which the user is asked to perform. The text message is displayed in the Comment column next to the task in the task list in the Worklist application, or in the Workflow Instances or Worklist dialog boxes in the Studio. (For more information, see Monitoring Workflows.

Figure 6-30 Set Task Comment Dialog Box

To set a task comment:

1. From the Task Actions folder in the Add Action dialog box, select Set Task Comment and click OK to display the Set Task Comment dialog box.

2. In the Task for which to set comment, select the appropriate task. Only one task at a time can be selected.

3. In the Comment field, enter an expression that will be evaluated at run time to produce the comment. The expression will typically consist of strings and variables. For more information on expressions and their syntax, see Using Workflow Expressions.

   Note: Task comments are limited to a maximum of 254 characters. The comment length is not determined until run time because the length of expressions may vary. Comments exceeding the 254-character limit are truncated at run time with no warning.

4. Click OK to add the Set Task Comment action.

Setting a Task Priority

You can use the Set Task Priority action set a task priority to Low, Medium, or High. The priority has no effect on how the node or its actions are executed at run time, but is simply displayed to Worklist users, who can execute and sort their tasks accordingly.

Since you can set a priority for the current task in the Task's properties dialog box, you may wish to use this action as the result of a condition to specify the priority of a task elsewhere in the workflow.

Figure 6-31 Set Task Priority Dialog Box

To set a task priority:

1. From the Task Actions folder in the Add Action dialog box, select Set Task Priority and click OK to display the Set Task Priority dialog box.

2. In the Task for which to set priority, select the appropriate task. Only one task at a time can be selected.

3. From the Priority drop-down list, select Low, Medium, or High.

4. Click OK to add the Set Task Priority action.

Unassigning a Task

You can use the Unassign Task action to remove the current task assignment. The task is no longer assigned to a user or role. You may wish to unassign a task as a result of a condition.

Figure 6-32 Unassign Task Dialog Box

To unassign a task:

1. From the Task Actions folder in the Add Action dialog box, select Unassign Task and click OK to display the Unassign Task dialog box.

2. In the Task to unassign field, select the task that you want to unassign. Only one task at a time can be selected.

3. Click OK to add the Unassign Task action.

Sending an XML Message to a Client Application

Once you have assigned a task to a user, you can use the Send XML to Client action to communicate between a workflow and the Worklist or custom client application by sending an XML document to the client. The client application must be programmed to identify the XML document, perform the appropriate action, and return an XML document in response to the workflow. For the Worklist application, you can send XML messages to display message prompts and forms to users, and to call custom components or executable programs on the client system. For information on developing custom client applications, see Programming BPM Client Applications.

Note that the Send XML to Client action does not actually specify the client machine or application to which the XML is being sent. Thus, you must first assign a task to a user or role, and the XML message will be sent to the client that executes the task. For more information, see Setting Up Manual Tasks.

Sending a Message Asynchronously or Synchronously

You can send an XML message to a client application asynchronously or synchronously. In synchronous mode, the workflow waits for a response from the client before proceeding to the next node. To set up the action this way, you must use mark the Task containing the action done as a sub-action on the Callback Actions tab of the Send XML to Client dialog box, rather than in the Task node.

In asynchronous mode, the workflow does not wait for a response from the client, but continues to the next node, while any operations on the client execute in parallel. To set up the action in this way, mark the task done in the Task node itself.

Extracting Data

If your application responds to the workflow by sending a return XML message, you must create variables to store the data returned by the response document (see Working with Variables for procedures), and initialize those variables by using XPath expressions (or dot notation) to retrieve data values from the response XML document. If your application uses JMS properties in its messages, you can also retrieve this data by using the EventAttribute() function. (For more information, see Extracting Run-Time Event Data.)

Defining the Send XML to Client Action

The following procedure is generalized for any non-Worklist application. For complete information on sending an XML message to the Worklist, see Sending an XML Message to the Worklist Application. For detailed information on working with type-specified XML documents, see Working with Type-Specified Documents.

Figure 6-33 Send XML to Client Dialog Box

To send an XML message to a client:

1. From the Integration Actions folder in the Add Action dialog box, select Send XML to Client and click OK to display the Send XML to Client dialog box. A default XML document structure with a root element and actionid element is created.

   Note: The system-generated actionid element and its value are used at run time to identify the Send XML to Client action. The actionid element must be the first child element of the root element. Do not move, delete or edit the actionid element, and do not add any sub-elements to it.

2. To specify the XML Document Structure, do one of the following:

   - To create a new free-form document, begin composing the document by clicking the Add Child button to begin adding nodes.

   - To specify an existing XML document, load the document by clicking the Import button.

   - To create a new type-specified XML document, load the appropriate Schema document by clicking the Set Content Type button. The actionid value is removed and is reset when you save the action in Step 9.

   For detailed procedures for all these options, see Composing and Editing XML Documents.

   The XML document you define is stored in the workflow template definition.

3. Select the Callback Variables tab to specify the variables that will receive the response from the client, and click Add to display the Workflow Variable Assignment dialog box.

   Figure 6-34 Workflow Variable Assignment Dialog Box

4. In the Expression field, enter the expression that is evaluated at run time to extract the data from the response XML document, by doing one of the following:

   - To capture incoming JMS header data, use an EventAttribute() function. For information, see EventAttribute().

   - To capture incoming XML content, use an XPath() function (for information, see XPath()), or the dot notation for XML elements that return strings (for information, see XML Element Dot Notation). You can also use the Expression button to invoke the XPath Wizard, from which you can generate XPath expressions automatically from a sample incoming document. For information, see Creating XPath Expressions Using the XPath Wizard.

5. Click OK. The variable initialization appears in the list on the Callback Variables tab of the Send XML to Client dialog box.

6. Repeat steps 4 to 5 for all data items that need to be captured from the response document.

7. Select the Callback Actions tab and click Add to display the Add Action dialog box to specify any sub-actions to be performed when a reply is received from the client. If you want the workflow to wait for the response from the client before proceeding to other nodes in the workflow, be sure to add the Mark Task as Done action to this tab, at the end of the action list. In the Mark Task as Done dialog box, select the Task node in which you have specified the Send XML to Client action.

8. If you are using a type-specified document, you are prompted to add the actionid value. Click Yes to update the document.

9. Click OK again to save the action definition.

Sending an XML Message to the Worklist Application

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.

The Worklist client application is designed to perform an action in response to an XML document that conforms to four pairs of predefined Document Type Definition (DTD) files, which allow you to do the following:

- Display a message box with prompts to the user.

- Display a form with entry fields to the user.

- Call a custom add-in component on the client.

- Call an executable program on the client.

The four pairs of predefined DTD files are located in the following directory of your WebLogic Integration server installation:

>     WLI_HOME\docs\apidocs\com\bea\wlpi\common\doc-files

In this path, WLI_HOME represents the directory in which you installed WebLogic Integration, typically c:\bea\weblogic700\integration.

Each pair has one DTD file for a request to the Worklist client, and another DTD file for a response from the Worklist client. The following table lists the predefined DTD files, and the actions performed by the Worklist application when it receives an XML document that conforms to one of the request DTD files.

Table 6-2 Worklist DTD Files

DTD Pair | Use To...
--- | ---
Request | ClientMsgBoxReq.dtd | Display a message dialog box in which the user responds to a message or query. Reply = ok/yes/no/cancel For more information, see Displaying a Message Prompt to a User.
Response | ClientMsgBoxResp.dtd
Request | ClientSetVarsReq.dtd | Display a prompt dialog box with entry fields in which the user enters some values. Reply = field name/value pairs For more information, see Displaying a Form to a User
Response | ClientSetVarsResp.dtd
Request | ClientCallPgmReq.dtd | Execute a program on the client machine. Reply = program exit code For more information, see Calling an Executable Program on the Client.
Response | ClientCallPgmResp.dtd
Request | ClientCallAddInReq.dtd | Invoke a custom extension to the Worklist client application. Reply = custom For more information, see Calling a Custom Worklist Extension on the Client.
Response | ClientCallAddInResp.dtd

Note: If you will be accessing these DTDs often, you may want to import them into the repository for convenient retrieval. For procedures, see Managing Entities in the Repository.

For each response received from the client, you will need to create a variable in which to place the value returned by the response. Most of these will be string-type variables. For procedures for creating variables, see Working with Variables.

The following sections provide detailed descriptions of the required document structure for each DTD pair.

Displaying a Message Prompt to a User

You can use the ClientMsgBox DTDs to display a message box to the Worklist user, as in the following example.

Figure 6-35 Example Message Prompt

The request DTD requires a document with the following structure.

Listing 6-1 ClientMsgBoxReq XML Document Structure

>     <message-box title="text" style="{plain|information|question|warning|error}"
>     options="{ok|ok_cancel|yes_no|yes_no_cancel}">
>     text
>        <actionid>	provided by default	</actionid>
>     </message-box>

All elements and attributes are required, and are described below.

Table 6-3 ClientMsgBoxReq Elements and Attributes

Element or Attribute | Description | Valid Values
--- | --- | ---
message-box | Text that appears in the message of the dialog box. | Any string of text.
title | Text that appears in the title bar of the dialog box. | Any string of text.
style | The Swing icon that appears in the top left corner of the dialog box: | The default is plain.
No icon | plain
| information
| question
| warning
| error
options | The selection buttons at the bottom of the dialog box and the text they contain: | The default is ok.
Three buttons: Yes, No, and Cancel. | yes_no_cancel Valid only when style element is set to plain or question.
Two buttons: OK and Cancel | ok_cancel Valid only when style element is set to error, plain, or warning.
One button: OK | ok Valid only when style element is set to error, information, plain, or warning.
Two buttons: Yes and No | yes_no Valid only when style element is set to plain or question.

The response document provides the response of the user to the message box, according to the button selected. The response DTD requires the following structure.

Listing 6-2 ClientMsgBoxResp XML Document Structure

>     <message-box option="{ok|yes|no|cancel}" />

The element and attribute are required, and are described below, along with the expression required to return the value to a workflow variable.

Table 6-4 ClientMsgBoxResp Elements and Attributes

Element or Attribute | Description | Valid Values | Expression Required to Extract Value
--- | --- | --- | ---
option | The button selected by the client user, expressed as a string. | ok yes no cancel | XPath("/message-box/@option/text()")

Displaying a Form to a User

You can use the ClientSetVars DTDs to display a form to the Worklist user, as in the following example.

Figure 6-36 Example Form

The request DTD requires a document with the following structure.

Listing 6-3 ClientSetVarsReq XML Document Structure

>     <set-variables title="text">
>     text
>        <actionid>provided by default	</actionid>
>        <variable name="variable name" prompt="text" />
>        [<variable name="variable name" prompt="text" />]
>     </set-variables>

All elements and attributes are required. There must be at least one <variable> element and as many additional <variable> elements as you like. Element and attributes are described below.

Table 6-5 ClientSetVarsReq Elements and Attributes

Element or Attribute | Description | Valid Values
--- | --- | ---
set-variables | Text that appears in the message of the dialog box. | Any string of text.
title | Text that appears in the title bar of the dialog box. | Any string of text
name | A name to identify the entry field. | Any string of text.
prompt | The text that appears as a prompt in front of the entry field. | Any string of text.

The response document provides the responses of the user to each of the entry fields. The response DTD requires the following structure.

Listing 6-4 ClientSetVarsResp XML Document Structure

>     <set-variables>
>        <variable name="variable_name_1">response_1</variable>
>        [<variable name="variable name_2">response_1</variable>]
>        .
>        .
>        .
>     </set-variables>

All elements and attributes are required, and the number of <variable> elements should correspond to the number used in the request document. Elements and attributes are required, and the expression required to return the value to a workflow variable, are described below.

Table 6-6 ClientSetVarsResp Elements and Attributes

Element or Attribute | Description | Valid Values | Expression Required to Extract Value
--- | --- | --- | ---
variable | The response given by the client. | Any text string. | XPath("/set-variables/variable[@name="field_name"]/text()")
name | The name used to identify the entry field. | Should correspond to the name used in the request document.

Calling an Executable Program on the Client

You can use the ClientCallProgram DTDs to call a program on the Worklist client. The request document requires the following structure.

Listing 6-5 ClientCallProgramReq XML Document Structure

>     <call-program name="name" mode="{sync|async}">
>         <actionid>	provided by default	</actionid>
>         [<parm>parameter_1</parm>]
>         .
>         .
>         .
>         [<env-var name="name">environment variable
>           definition_1</env-var>]
>         .
>         .
>         .
>     </call-program>

All elements and attributes are required, except the <parm> and <env-var> elements, which are optional. You can specify zero or more <parm> or <env-var> elements.

Table 6-7 ClientCallProgramReq Elements and Attributes

Element or Attribute | Description | Valid Values
--- | --- | ---
name | The name of the program. | Text string.
mode | The mode in which the executable program is to run, in relation to the Worklist: | The default is async.
The program executes synchronously. The Worklist is blocked from continuing and its user interface is inaccessible until the called program has terminated. | sync
The program executes asynchronously, running in parallel with the Worklist, whose user interface remains accessible while the called program is executing. | async
parm | Parameter to be passed to the program. | Any text string.
env-var | The definition of an environment variable you want to associate with the called program. | Text string.
name | The symbolic name of the environment variable. | Text string.

The response DTD requires the following structure.

Listing 6-6 ClientCallProgramResp XML Document Structure

>     <call-program exit-value="value" />

The element and attribute are required, and are described below.

Table 6-8 ClientCallProgramResp Element

Element or Attribute | Description | Valid Values | Expression Required to Extract Value
--- | --- | --- | ---
exit- value | The called program's numeric exit code, as retrieved by the operating system. | Consult the appropriate program documentation for more information on valid exit codes. | XPath("/call-program/@exit-value")

Calling a Custom Worklist Extension on the Client

You can use the ClientCallAddIn DTDs to call a custom extension to the Worklist client. The request document requires the following structure.

Listing 6-7 ClientCallAddInReq XML Document Structure

>     <call-addin name="name" mode="{sync|async}">
>         <actionid>	provided by default	</actionid>
>         [<parm>parameter_1</parm>]
>         .
>         .
>         .
>     </call-addin>

All elements and attributes are required, except the <parm> element, which is optional. You can specify zero or more <parm> elements.

Table 6-9 ClientCallAddInReq Attributes and Elements

Element or Attribute | Description | Valid Values
--- | --- | ---
name | The name of a custom Java class that implements the com.bea.wlpi.client.worklist.WorklistAddIn interface | The fully qualified JNDI name of the Java class.
mode | The mode in which the program is to run, in relation to the Worklist: | The default is async.
The program executes synchronously. The Worklist is blocked from continuing, and its user interface is inaccessible, until the called program has terminated. | sync
The program executes asynchronously, running in parallel with the Worklist, whose user interface is accessible while the program is executing. | async
parm | A parameter to be passed to the extension. | Any text string.

The response document is optional. Elements are optional and can consist of any number of custom elements and attributes you define.

Listing 6-8 ClientCallAddInResp XML Document Structure

>     <call-addin>
>     	[<tag_name_1 attribute_name_1="attribute_value"
>              . . .>value</tag_name_1>]
>            .
>            .
>            .
>     </call-addin>

Elements are described below.

Table 6-10 ClientCallAddInResp Elements and Attributes

Element or Attribute | Description | Valid Values | Expression Required to Extract Value
--- | --- | --- | ---
Any element name | Can consist of any number of attributes. | Custom-defined. | XPath("/call-addin/path/text()")

Sending E-Mail Messages

You can use the Send E-Mail Message action to send an e-mail message to a user of the WebLogic Integration system or even to an outside party. Internet standard SMTP protocol is used to transmit the message.

You can compose an e-mail message in any character set that your operating system supports at design time, and specify the character set to be used by the server at run time to the send the message. In an English locale, the default character set used by the server is cp1252, the default character set used by the Java Virtual Machine, but you can specify any character set supported by the Java language. For a list of these, see http://java.sun.com/j2se/1.3/docs/guide/intl/encoding.doc.html.

Note: This action requires that your e-mail server be properly configured during or after the WebLogic Integration server installation process. For information on configuring mail server properties after installation, see "Customizing Mail Session Properties" in Customizing WebLogic Integration in Starting, Stopping, and Customizing BEA WebLogic Integration.

Figure 6-37 Send E-Mail Message Dialog Box

To send an e-mail message:

1. From the Miscellaneous Actions folder in the Add Action dialog box, select Send E-Mail Message and click OK to display the Send E-Mail Message dialog box.

2. In the Subject field, enter a valid workflow expression that will be evaluated at run time to produce the subject text of the e-mail. Your expression can consist of literals, variables, operators and functions. For more information on constructing expressions, see Using Workflow Expressions.

3. On the Message tab, in the text box, enter a valid workflow expression that will be evaluated at run time to produce the message text of the email.

4. Optionally, in the Mime Charset field, enter or select any MIME character set supported by the Java language in which you would like the server to send the message. For example, if you would like to send a message containing double-byte language characters, you can select UTF-8 (one of the Unicode standard formats). Note that the encoding you select must also be supported by the email client program used by your recipient in order for the message to be displayed correctly to him or her.

   Note: The encoding you use to input characters is independent of the setting in the Mime Charset field, and is determined by your operating system and locale.

5. Select the To tab, which displays the following information about recipients:

   Addressee | The e-mail address, user or role name, or expression defined to produce the e-mail address at run time.
   Via | Indicates whether the address is specified as a constant or an expression.
   Type | Address, user, or role.

   Figure 6-38 Send E-mail Message Dialog Box: To Tab

6. Click Add to add a recipient. The Mail Recipient dialog box is displayed.

   Figure 6-39 Mail Recipient Dialog Box

7. Specify an addressee by selecting one of the following options:

   - Address — enter an e-mail address in the field, or enable the Expression check box and enter a workflow expression that will produce the e-mail address at run time.

   - User — select this option to display a drop-down list, from which you select the appropriate user from among all users associated with the current organization. The e-mail address is obtained from the user's properties, as described in Creating a User. Alternatively, enable the Expression check box and enter a workflow expression, such as a CurrentUser(), WorkflowAttribute("Initiator") or TaskAttribute("Assignee") function, that will produce a user's email address at run time, or a specific e-mail address surrounded by quotation marks.

   - Role — select this option to a display a drop-down list, from which you select the appropriate role from among all roles defined in the current organization. The message will be sent to all users belonging to that role. Alternatively, enable the Expression check box and enter a workflow expression that will produce the role name at run time, such as a TaskAttribute() function that can return a role name at run time.

   For more information on workflow functions and constructing expressions, see Using Workflow Expressions.

8. Click OK. The new recipient is added to the list.

9. Repeat steps 6 to 8 to add more recipients. To update a recipient, select it in the list and click Update. To delete a recipient, select it in the list and click Delete. Confirm the deletion when prompted.

10. Optionally, on the CC or BCC tabs, repeat steps 5 to 8 to specify recipients who you want to carbon copy or blind carbon copy.

11. Click OK to add the Send E-mail Message action.

Invoking Components

You can call software components such as EJBs, Java classes, and executable programs, and pass input and output parameters between the workflow and the components directly, by using the following actions:

- Call Program—Calls an executable program on the server, which executes in parallel with the workflow. Described in Calling an Executable Program on the Server.

- Perform Business Operation—Calls a pre-configured business operation, representing a method on an EJB or Java class. Described in Calling a Business Operation.

Calling an Executable Program on the Server

You can use the Call Program action to call an executable program on the WebLogic Integration server. This action is always executed asynchronously, meaning that any actions following this action in the workflow are executed simultaneously, without waiting for the called program to complete.

Note: When using the Call Program action within a Send XML to Client action, you should be careful when granting access to a shell program, for example, cmd.exec. Doing so may compromise the security of the application by enabling full access to the client computer.

Figure 6-40 Call Program Dialog Box

To call an executable program on the server:

1. In the Add Action dialog box, expand the Integration Actions folder, select Call Program and click OK to display the Call Program dialog box.

2. In the Program field, enter the name of the executable file, including the extension.

   If you are running a DOS script file, such as a.cmd or .bat file that does not include any DOS shell-specific commands (e.g., echo), do one of the following:

   - If the WebLogic Integration server path, as set in your environment variables, includes the path for this file, enter the full name of the file including extension, for example: testscript.bat

   - If the WebLogic Integration server path, as set in your environment variables, does not include the path for this file, enter the fully qualified path and file name, for example: c:\mydirectory\myfiles\testscript.bat

   If you are running a DOS script file, such as a.cmd or .bat file that includes DOS shell-specific commands (e.g., echo), enter the following:

   c:\winnt\system32\cmd

3. In the Arguments field, enter a valid workflow expression, such as a variable name, that will be evaluated at run time to produce the argument to pass to the program.

   If you are running a DOS script file, such as a.cmd or .bat file that includes DOS shell-specific commands (e.g., echo), enter the following:

   "/c start c:\\path\\filename.extension expression"

4. Click OK to add the Call Program action.

Calling a Business Operation

You use the Perform Business Operation action to call a method on a Java component, such as an EJB or Java class, that performs a business activity.

The business operation you want to invoke must already be defined. Additionally, Java Object, Session EJB, and Entity EJB variables must already be defined to store references to the Java class or EJB instances whose methods are being called by the business operation. For details about defining business operations, see Configuring Business Operations. For details about defining variables, see Working with Variables.

Also note that before you can perform business operations that call methods on EJBs or non-static methods on Java classes, you must first call the business operation that serves to create an instance of the Java class or EJB on the WebLogic Integration server, according to the following rules:

- To call a business operation representing a static method on a Java class, you do not need to call a constructor method.

- To call a business operation representing a non-static method on a Java class, you must first call the business operation representing a constructor method for the class. This business operation only needs to be called a single time in the workflow.

- To call a business operation representing a method call on an Entity EJB, you must first call the business operation that creates the EJB instance. This business operation only needs to be called a single time in the workflow.

- To call a business operation representing a method call on a Session EJB—stateless or stateful—you must first call the business operation that creates the EJB instance. This business operation must be called once per transaction in which other methods are invoked on that EJB. For information on transactions and boundaries in a workflow, see Understanding the BPM Transaction Model in Programming BPM Client Applications.

When you perform the business operation that creates the instance, you assign a reference to the instance to a variable, called an instance variable. You then identify the instance variable that references the EJB or Java class instance when calling other business operations representing methods contained in the same EJB or class. More information is provided in the following sections.

Calling the Business Operation to Create an EJB or Java Class Instance

When you call a business operation that creates an EJB or Java class instance, you must assign a reference to the instance to a variable of the same data type, as follows:

- for a Java class, the instance variable must be a Java object type

- for a Session EJB, the instance variable must be a Session EJB type

- for an Entity EJB, the instance variable must be an Entity EJB type

Figure 6-41 Perform Business Operation Dialog Box

To call a business operation to create an EJB or Java class instance:

1. From the Integration Actions folder in the Add Action dialog box, select Perform Business Operation and click OK to display the Perform Business Operation dialog box.

2. From the Operation drop-down list, select the business operation that creates the Java class or EJB instance.

3. From the Assign Result drop-down list, select the instance variable for this business operation, or click Add to invoke the Create Variable dialog box and create the variable. The variable type must correspond to the type of component being created.

4. Click OK to add the Perform Business Operation action.

Calling Other Business Operations

Once the Perform Business Operation for the create() or constructor method of an EJB or Java class has been added to a node, you can add other business operations that invoke methods on the same class or EJB.

For methods that take parameters and return results, such as, for example, a calculated total price, you also need to create a variable that will store the value returned by the business operation. Be sure that this variable is of the same type as that specified by the method.

Figure 6-42 Perform Business Operation Dialog Box

To call other business operations:

1. From the Integration Actions folder in the Add Action dialog box, select Perform Business Operation and click OK to display the Perform Business Operation dialog box.

2. From the Operation drop-down list, select the business operation representing the business logic you want to execute. For business operations invoking methods on EJBs, or non-static Java class methods, the Instance Variable drop-down list is populated with Java Object, Session EJB or Entity EJB variables.

3. From the Instance Variable drop-down list, select the variable that you have designated to store the reference to the EJB or Java class, as specified in Calling the Business Operation to Create an EJB or Java Class Instance.

4. If the business operation displays parameters in the Parameters list, select a parameter from the list and click Update, and use the invoked Expression Builder dialog box to define this value. Typically this value will be provided by a workflow variable you have already defined.

5. If the business operation returns a result, from the Assign Result To drop-down list, select the variable to which the result will be assigned, or click Add to invoke the Create Variable dialog box and define the variable. The variable type must match that specified by the method.

6. Click OK to add the Perform Business Operation action.

Posting an XML Message to a JMS Topic or Queue

Use the Post XML Event action to send an XML message to a specified destination to trigger an event. This action can either create a new XML document, or use the content of an existing XML-type variable in the workflow; either way it embeds the XML content inside a JMS message that can be posted to an external JMS queue or topic for processing by an external application, or to an internal queue for processing by another workflow.

Note: If you are running WebLogic Integration in a clustered environment, posting an XML event to initiate another workflow is preferred over calling the workflow directly with a Start Workflow action, as this method provides better load balancing control.

You can compose the XML document to be sent, or import an existing XML document from the XML repository, a file on disk, or a URL. You can also specify the document to be sent as a variable in which the XML content can be specified at run-time.

In addition to XML message content, the Post XML Event action also inserts JMS headers and values into the message according to options that you specify in the action's properties. For information on standard JMS header fields in WebLogic Server, see "WebLogic JMS Fundamentals" in Programming WebLogic JMS at the following URL: http://edocs.bea.com/wls/docs70/jms/fund.html

JMS messaging options are described in the following sections.

Posting an Event Asynchronously or Synchronously

You can set up your XML event to function in an asynchronous or synchronous manner in relation to workflows or other components that are configured to consume outgoing messages. You do this using Event nodes in the workflow initiating the communication to receive confirmation messages back from the recipient workflows.

By default, the Post XML Event action is asynchronous in that it simply posts a message in a "fire and forget" fashion, while the workflow proceeds to the next action. Thus, if you would like to trigger another workflow or application to be executed in parallel, and the calling workflow does not need to receive any communication back from the called workflow or application, simply use the action as is.

If you would like the calling workflow and the called workflow or application to execute in parallel, but the calling workflow does expect to receive a message back from the called workflow or application, you can set up an Event node in the calling workflow that receives the message in a "just in time" fashion. That is, you can set up an Event node only at the point in the workflow where the data returned by the called workflow or application is required. These two scenarios are illustrated in the following figure.

Figure 6-43 Posting an XML Event Asynchronously

If you want to post the XML event in a purely synchronous fashion, that is, to force the calling workflow to wait until the called workflow or application has finished executing before it proceeds, you must set up the called workflow or application to send a message when it finishes executing, and place an Event node that listens for this message immediately after the Post XML Event action in the calling workflow. This design is illustrated in the following figure.

Figure 6-44 Posting an Event Synchronously

Understanding JMS Messaging Options

The following sections discuss the various JMS messaging options that are available from within the Post XML Event dialog box.

Destination

You can specify an internal JMS queue to trigger an Event node in the current workflow or in another one, or to start another workflow defined with an event-triggered Start. (For details about event triggers in Start and Event nodes, see Defining Event And Event-Triggered Start Properties.) The JNDI name of the internal JMS queue, to which messages are sent by default, is com.bea.wlpiEventQueue. If you have configured other queues in WebLogic Server, you can also specify an alternate queue name. (For more information on setting up alternate message queues for WebLogic Integration, see "Configuring a Custom Java Message Service Queue" in Customizing WebLogic Integration in Starting, Stopping, and Customizing BEA WebLogic Integration.)

You can also send the XML message to an external JMS topic or queue to communicate with an external application that subscribes to the JMS topic you specify, or with a specific application that is the JMS queue receiver.

Headers

JMS messages contain a standard set of header fields that are always transmitted with the message. In addition to the JMSDeliveryMode, JMSDestination, JMSPriority, and JMSExpiration (time to live) headers that are automatically inserted by the options available in the Post XML Event dialog box, you can also add property fields and values to your outgoing messages for application-specific information to specify information in the message that is not appropriate for the body of the message. For example, if you are using XML messaging to trigger another workflow, you may wish to use a property field to specify the name of the organization in which the workflow should start.

JMS message properties are name-value pairs. The name can be almost any string that is a valid identifier in the Java language. The value can be any one of the following types: Boolean, Byte, Short, Int, Long, Float, Double, or String.

For more information about JMS header and property fields, see "WebLogic JMS Fundamentals" in Programming WebLogic JMS at the following URL: http://edocs.bea.com/wls/docs70/jms/fund.html

If you use ordered or addressed messages, WebLogic Integration inserts property fields for an order key you specify, for ordered messages, and workflow instance IDs you specify, for addressed messages, based on the values you enter on the Addressing tab of the Post XML Event dialog box options. However, you can also manually insert two additional supported properties:

- WLPIInstanceIDs—a single variable, or a comma-separated list of variables containing workflow instance IDs determined at run time. For example, either of the following:

- $ParentID

- $Child1ID + "," + $Child2ID + "," + $Child3ID

- WLPITemplateNames—a single template name, or a comma-separated list of template names, or variables containing template names determined at run time

This feature can be useful when you need to consolidate a list of workflow instances or template names that have entered into a conversation with the current workflow and which you want to pass via a single message to an external application.

If you intend the message to be received by another workflow, the receiving workflow can use the EventAttribute() function in an event key expression or in a variable initialization in a Start or Event node to retrieve the information you specified in the property field. If multiple instance IDs or template names are specified, you must assign the result of the function to a variable defined as a Java object data type.

For more information on event key expressions, see Configuring Event Keys. For more information on initializing variables from event data, see Initializing Variables from Event Data. For details about the EventAttribute() function, see Extracting Run-Time Event Data.

Delivery Mode

You can specify whether a message is to be persistent or non-persistent. Persistent messages are written to a database table and are not lost even if the JMS server fails. The message is delivered again after the server recovers. Non-persistent messages can be lost if the JMS server fails. The message is not delivered again after the server recovers. The default delivery mode is persistent.

Time to live

Whether a message is persistent or non-persistent, you can specify an expiry time for your message. If the message is not delivered before the expiry time, it is discarded. This option is useful for messages that should not be delivered after a certain time, such as a stock bid. The time to live is expressed in milliseconds. For example, if you want the message to be available for 1 hour, you specify a value of 3600000 (1000 milliseconds x 60 seconds x 60 minutes). The default value of 0 (zero) indicates that the message will not expire.

If you specify an expiry time for an addressed message, the message is persisted until the message is successfully delivered to all specified recipients, or until it expires, whichever comes first.

Priority

You can assign a priority level from 0 to 9. Levels 0-4 are normal priority. Levels 5-9 are expedited priority. Messages with an expedited priority are delivered ahead of messages with a normal priority. You would typically use an expedited priority for an alarm or shutdown message. The default priority level is 4.

Note that priority overrides ordered messaging, so that you must specify the same priority level for all messages with the same order key. The recommended setting is to keep the default of 4.

To use other priority levels, you must first configure a destination key in WebLogic Server. For more information, see "Managing JMS" in the WebLogic Server Administration Guide at the following URL: http://edocs.bea.com/wls/docs70/adminguide/jms.html.

Transaction Mode

You can specify whether you want the message to be sent immediately, or when the current transaction containing the Post XML Event action commits. Sending the message immediately sends the message whether or not the transaction completes. Sending the message on commit ensures that the message is sent only if the transaction completes successfully and a commit is issued. If the transaction is unsuccessful and is rolled back, the message is not sent. The default is when the transaction commits. For more information on workflow transaction boundaries, see Understanding the BPM Transaction Model in Programming BPM Client Applications.

Addressed Messaging

You can use addressed messaging to guarantee that a response message is delivered to a particular workflow instance that has begun a conversation with the current workflow (either by calling it via the Start Workflow action, or by triggering a Start or Event node contained within it via a previously sent XML message) — even if the receiving Event node in the instantiated workflow has not yet been activated in the flow. (For information on node activation, see Understanding the BPM Transaction Model in Programming BPM Client Applications.)

When you use addressed messaging, you typically provide a list of workflow instance IDs to which the message should be delivered. These will have been sent from the originating workflows via a WorkflowAttribute("InstanceID") expression embedded in an XML message or as a parameter passed to the workflow via a Start Workflow action, and then extracted and stored in a variable by a previous node in the current workflow. The list of instance IDs, then, is typically a comma-separated list of variables containing the appropriate IDs. The message will only be delivered to the instances specified in this list.

Note: Workflow instance IDs are stored as strings, so if you want to create variables to hold instance ID values, be sure that these variables are created as string types. For more information on the workflow attribute functions, see Obtaining Run-time Workflow Data.

Note that if you specify a time to live, the message will persist until the message has been delivered to all specified recipients, or until the message expires, whichever comes first.

Ordered Messaging

You can specify an order key that guarantees that messages are processed sequentially by the same event listener in the order in which they are received. As an example, if an order processing system receives requests to create an order and to update or cancel an order, you may want to guarantee that create request messages are processed first.

An order key must be an integer value, and the value must be the same for each event that you want processed in the order in which it is received. For example, if two events are posted at the same time, and you want them processed in the order in which they are received, you would enter the same order key value, such as the integer value of 8, for each event. Ordered messages must also be sent to the same JMS queue.

Note that ordered messaging is incompatible with message priority, so that if you use an order key, you must set the same priority level for all messages with the same order key. The recommended setting is to keep the default of 4.

Defining the Post XML Event Action

To define the XML event:

1. From the Integration Actions folder in the Add Action dialog box, select Post XML Event and click OK to display the Post XML Event dialog box.

   Figure 6-45 Post XML Event Dialog Box: XML Message Tab

2. Select the XML Message tab to define the XML message you want this action to send, by doing one of the following:

   - If the XML document is stored in an XML type variable, select the variable from the From XML Variable drop-down list. For details about XML type variables, see Working with Variables.

   - If you want to compose or load an existing XML document, select the By Composing option. To create a new free-form document, click the Add Child button to begin adding nodes. To specify an existing XML document, click the Import button to load the document and edit as necessary. To create a new type-specified XML document, click the Set Content Type button to load a Schema document. For detailed procedures for all these options, see Composing and Editing XML Documents.

   The XML document you define is stored in the workflow template definition.

3. Under the Destination tab, in the Destination options, select one of the following:

   - Internal—sends the message to the default internal queue, wlpiEventQueue.

   - JMS Topic—posts the message to an external topic. In the field, enter the JNDI name of the topic surrounded in quotation marks, or enter an expression that will determine the topic name at run time.

   - JMS Queue—posts the message to an external queue, or an alternate internal queue that you have configured in WebLogic Server. In the field, enter the JNDI name of the queue surrounded in quotation marks, or enter an expression that will determine the queue name at run time.

   Note: For more information on constructing expressions, see Using Workflow Expressions.

   Figure 6-46 Post XML Event Dialog Box: Destination Tab

4. Optionally, from the Transaction Mode options, select one of the following:

   - When transaction commits — ensures that the message is sent only if the transaction completes successfully and a commit is issued. If the transaction is unsuccessful and is rolled back, the message is not sent.

   - Immediately — sends the message immediately without waiting for the transaction to complete.

5. Optionally, select the Message Header tab to specify any JMS message properties you want to add to the message. (For information on workflow-specific properties you can use, see Headers.) Click Add to display the Set JMS Properties dialog box. In the dialog box, specify the following:

   1. In the JMS Property field, specify the property name.

   2. In the JMS Property Value field, enter the property value. Enter the value directly, surrounded by quotation marks, or enter an expression that is evaluated at run time to produce the value.

   3. Click OK.

   Figure 6-47 Set JMS Properties Dialog Box

6. Optionally, on the Message Header tab, specify a delivery mode, by selecting from the following options:

   - Persistent—writes the message to a database table and ensures that the message will persist even in the event of a JMS server failure.

   - Nonpersistent—does not persist the message. The message may be lost if the JMS server fails.

   Figure 6-48 Post XML Event Dialog Box: Message Header Tab

7. Optionally, on the Message Header tab, in the Time to live field, specify an expiry time, in milliseconds, or select the Use expression check box and enter an expression in the field that will be evaluated at run time to produce the value. A value of 0 indicates that the message never expires.

8. Optionally, specify a message priority by selecting a value from 0 (lowest priority) to 9 (highest priority) from the drop-down list, or select the Use expression check box and enter an expression in the field that will be evaluated at run time to produce the value.

   Note: If you specify an order key for ordered messaging, leave the default value of 4.

9. Optionally, to send an addressed message, select the Addressing tab to indicate that you want to persist an XML message for one or more workflow instances. Select the Addressed Message check box, and in the Instance ID field, enter a single variable name, or a comma-separated list of variables, in which you have stored workflow instance IDs previously in the current workflow. (For more information, see Addressed Messaging.)

   Figure 6-49 Post XML Event Dialog Box: Addressing Tab

   Note: If you specify a Time to live in the Message Header area, the message persists only for the time you specified.

10. Optionally, to send an ordered message, on the Addressing tab, enter an order key for the message that is the same as all other messages which you would like to have processed sequentially. This value must be an integer, or an expression that will determine the integer value at run time.

    Note: If you specify an order key, leave the default value message priority value of 4.

11. Click OK to add the Post XML Event action.

Transforming XML Documents

Extensible Stylesheet Language Transformations (XSLT) define rules for translating an XML document into another XML or non-XML document. An XSL template document specifies which elements in the input XML document are to be transformed, and how they are to be transformed.

The XSL Transform action provides a way for you to specify an input XML document that is to be transformed, an XSL template document that specifies the details of the transformation, and an output variable that will contain the transformed document. The actual transformation occurs at run time, and is performed by the XSL transformation engine bundled with WebLogic Server.

The input document can contain workflow expressions. If it does, the process engine resolves the expressions, and replaces the expression with the result before the transformation occurs. Similarly, the XSL template document can contain references to workflow variables. If it does, the process engine resolves the references, and replaces the reference with the appropriate value before the transformation occurs.

Note that the input document is specified as an expression that identifies the location of the document at run time. This expression could include the name of a workflow variable in which you have stored an XML document. In this case, you will need to have created an XML-type variable (for information, see Working with Variables), and assigned an existing or incoming XML document to it previously in the workflow—one way of doing this is by using the Set Workflow Variable action; see Setting a Variable Value for procedures.

The XSL template document, or transform document, can be an entity stored in the repository (for more information, see Managing Entities in the Repository), or you can use an expression that locates the document at run time.If the XSL entity in the repository or the XSL document to be located at run time takes parameters, you can also specify expressions that will supply values for those parameters at run time.

The output document must be stored in an XML or string variable which you can create ahead of time. See Creating a Variable for procedures.

Figure 6-50 XSL Transform Dialog Box

To transform an XML document:

1. From the Integration Actions folder in the Add Action dialog box, select XSL Transform and click OK to display the XSL Transform dialog box.

2. In the Input Document field, enter an expression that represents the XML document you want to transform. The expression is evaluated at run time to obtain the XML document. The expression could contain the name of a variable in which you have previously stored the input document.

   Note: For more information on constructing expressions, see Using Workflow Expressions.

3. In one of the Transform Document fields, specify the XSL template document that is used to transform the input document. Select one of the following options:

   - Expression — Enter an expression to be evaluated at run time to obtain the XSL template document.

   - Repository — Enter the name of an XSL template document stored in the XML repository, or click the XML button to display the XML Finder dialog box, to select the desired XSL file from the repository or a location specified by a URL. For procedures on using the XML Finder to retrieve XML entities, see Retrieving XML Entities.

4. If you selected to enter an expression for the XSL document, or specified an XSL document that takes parameters, optionally, add parameters to be passed to the transform document at run time by clicking Add to display the XSL Parameters dialog box.

   Figure 6-51 XSL Parameters Dialog box

5. In the Parameter field, enter the name of the parameter.

6. In the Expression field, enter an expression that is evaluated at run time to produce the value of the parameter.

7. Click OK to add the parameter. The new parameter appears in the XSL Parameters list.

8. Repeat steps 4 to 7 to add more parameters, or click Update or Delete to update or delete existing parameters.

9. From the Output Variable drop-down list, select the variable that will contain the transformed XML document. The variable must be an XML type variable. You can also type the name of a variable. If it does not exist, you will be prompted to create it. For details about defining variables, see Working with Variables.

10. Click OK to add the action.

Handling Exceptions

All actions pertaining to exception handling are discussed in Handling Workflow Exceptions.