Defining Actions

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

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

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.

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:

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:

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:

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:

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

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

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

Figure 6-4 Synchronous Execution of Workflow Actions

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

Placing Actions in Task Nodes

Using the Activated and Executed Tabs

The only ways a task can be executed are:

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

Marking Tasks Done

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.

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

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.

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

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:

Working with Actions

Adding an Action

To add an action:

Updating an Action

To update an action:

Deleting an Action

To delete an action:

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:

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

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.

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

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:

Marking a Task Done

Figure 6-10 Mark Task as Done Dialog Box

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.

Figure 6-11 Unmark Task Done Dialog Box

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

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

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

Executing a Task Automatically

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

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

Using Timed Operations

The following actions allow you to set up timed operations:

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:

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

To define a timed event:

Using Sub-Workflows

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

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.

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.

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

Figure 6-19 Start Workflow Dialog Box

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

Monitoring Run-Time Status

You can use two actions for workflow monitoring purposes:

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.

Figure 6-23 Make Audit Entry Dialog Box

Setting Up a Workflow Comment

Figure 6-24 Set Workflow Comment Dialog Box

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.

Guidelines for Placement of Task Actions

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

Assigning a Task to a User

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

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

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.

Figure 6-27 Assign Task Using Routing Table Dialog Box

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

Setting a Task Comment

Figure 6-30 Set Task Comment Dialog Box

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

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

Sending an XML Message to a Client Application

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

Defining the Send XML to Client Action

Figure 6-33 Send XML to Client Dialog Box

Sending an XML Message to the Worklist Application

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:

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.

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

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

Figure 6-37 Send E-Mail Message Dialog Box

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:

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

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.

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:

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:

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

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

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.

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

Figure 6-44 Posting an Event Synchronously

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

Destination

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.

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:

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.

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.

Transaction Mode

Addressed Messaging

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 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:

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.

Figure 6-50 XSL Transform Dialog Box

Handling Exceptions