Understanding WebLogic Process Integrator Events and XML Documents

 

The following sections discuss XML (extensible markup language) events and XML document handling within WebLogic Process Integrator:

• XML Overview

• Processing Events and Handling XML Documents

• Defining a Workflow Event Trigger

• Using the XML Notification: The WebLogic Process Integrator Event

• Using XML Actions

• Understanding Workflow Interaction

 

---

XML Overview

XML is a system for defining, validating, and sharing document formats. Like HTML, XML is a markup language derived from SGML (Standard Generalized Markup Language). However, unlike HTML, which was created to allow cross-platform formatting of information for display, XML is best suited for organizing data. While HTML specifies how a document should be displayed, it does not describe what type of information is contained in the document or how it is organized. XML fills this void, allowing document authors to organize information in a standard manner.

The development of XML is a public project headed by the World Wide Web Consortium and is not owned by any one company. In a recommendation on February 10, 1998, the World Wide Web Consortium (W3C) accepted version 1.0 of the XML specification. However, XML is still evolving. Specifics on the XML standard and syntax can be found at the W3C site (http://www.w3.org/xml).

XML allows information exchange across different and potentially incompatible systems and platforms. Because XML is a text based, non-binary format and uses syntax rather than binary markers to organize data, it can be deployed on just about any platform.

Although XML specific editors are now available, because XML is just text, any editor or program that can generate text files can be used to create XML documents.

XML is license-free, platform independent, and well-supported. It is rapidly being adopted by software companies as a standard means of sending and receiving data.

XML Elements and Attributes

XML uses tags to distinguish document structures and uses attributes to encode extra document information.

XML tags usually surround an identified object in the data stream. A start-tag and an end-tag, together with the data enclosed by them, constitute an element. For example:

<OrderType>New</OrderType>

The element OrderType is assigned the value "New".

XML elements can contain other, embedded elements, and the entire document must be enclosed by a single document element. The following example shows an XML document with a root element Order and three subelements: OrderId, OrderType, and WorkflowStatus.

<Order>

<OrderId>1</OrderId>

<OrderType>New</OrderType>

<WorkflowStatus>New</WorkflowStatus>

</Order>

It is possible for an element to hold information about its content beyond just its name. This "information about information," or metadata, is stored in an attribute. When a document type definition (DTD) is not in use, the attribute value is simply considered to be a unit of text and no type distinction is made. But when a DTD is in use, more control can be exerted over the range of values allowed for each attribute. An attribute is associated with a particular element by the DTD, and is assigned an attribute type.

Document Type Definition (DTD)

It is possible to predefine which elements are allowed within other elements. An optional document type definition (DTD) contains rules for each element allowed within a specific class of documents so that the placement of elements and their attributes can be controlled and validated.

The DTD establishes formal document structure rules. It defines the elements that can be used and the relationships between them. In a way, the DTD defines a document structure tree.

Some XML editors can read the DTD and use it to build the document model. The editor can then identify errors in the XML document if the data contained in the document does not conform to the DTD structure.

The WebLogic Process Integrator DTDs are provided on the documentation CD at:

Drive:/docs/wlpi/v1_2/classdocs/com/bea/wlpi/common/doc-files

 

---

Processing Events and Handling XML Documents

The following diagram illustrates the XML event processing scheme within the WebLogic Process Integrator server.

Figure 9-1 XML Event Processing Scheme

 

Notifications to the WebLogic Process Integrator server and automatic workflow triggering are event driven. You can set up workflow events to wait for a notification and perform actions or start workflows upon the event being triggered. You define events in XML format by using the Start node for workflow triggering. Event definitions are then registered automatically in the Event Watch table.

Events are triggered and processed upon receipt of XML messages that match the criteria stored in the event definitions. These XML documents can either be internal to the WebLogic Process Integrator environment (raised by the Post XML Event action within tasks of workflows), or they can be received from applications or other external sources. In the latter case, the XML documents are received from the Java Message Service (JMS) and placed in the event handler request queue for processing.

The Post XML Event action can be used to raise external events (for processing by other applications) by posting the XML message to a Java Message Service (JMS) topic.

 

---

Defining a Workflow Event Trigger

A workflow can be triggered automatically, in which case it responds to a particular action or condition taking place. Custom triggers such as database events can be defined in order to start workflows. The workflow event trigger is already defined in WebLogic Process Integrator and is delivered as part of the standard software. When this trigger is set up, the workflow is responding to an incoming XML document.

A workflow event trigger is defined in the Start Properties dialog box. See the section entitled Defining Start in Working with Workflow Components, for instructions on accessing this dialog box. The Start dialog box allows you to specify the root element of the XML field, the condition under which the trigger should activate, and the variable assignments, if any.

To define a workflow event trigger:

1. In the Start Properties dialog box, select the Event option.

2. In the Root Element field, enter the XML document root element to serve as the event trigger.

3. In the Key Value Expression field, define a key value for the XML document. For more information, see Setting Up a Key Value for Each XML Root.

4. In the Condition field, define the condition under which the event is to be triggered. The workflow will be triggered by the XML document, provided that this defined condition is verified.

5. Select a Start Organization from the drop-down list containing those organizations already defined within WebLogic Process Integrator. When the Start node is the Event type, you must specify the organization for which the workflow instance will be started, because you can start the same workflow template definition for different organizations.

6. If you want to define the Start Organization using an expression, select the Workflow Expression option. The Expression Builder is displayed; use this to enter an expression that will be evaluated at run time and become the name of an organization. The expression can be either a string that specifies the organization (case sensitive) or an expression using information passed in the XML document.

   Note: Expressions are built using WebLogic Process Integrator expression syntax and typically use the syntax of XPath function to extract values out of XML documents. If you know the syntax of the expression you want to use, you can type the expression directly in the field. Alternatively, click the A+B button to display the Expression Builder dialog box. The Expression Builder helps you construct an expression, which is made up of functions, operators, literals, and variables. For more information on constructing expressions, see Using Expressions and Conditions.

   Figure 9-2 Start Properties Dialog Box

   

    

7. Select the Variables tab to assign values to workflow variables from the information contained in the XML document. Click Add to display the Workflow Variable Assignment dialog box, where each variable can be assigned an XML expression.

   Note: Expressions are built using WebLogic Process Integrator expression syntax and typically use the syntax of XPath function to extract values out of XML documents. If you know the syntax of the expression you want to use, you can type the expression directly in the field. Alternatively, click the A+B button to display the Expression Builder dialog box. The Expression Builder helps you construct an expression, which is made up of functions, operators, literals, and variables. For more information on constructing expressions, see Using Expressions and Conditions.

8. Select the Next tab to display a list of all task, decision, join, and done nodes in the current workflow. An event can have one or more successors. Select a node (or nodes) in the list to be activated next in the workflow when the Start node is instantiated.

9. Select the Actions tab to display a list of all actions to be performed when the Start node is initiated. Click Add to display a the list of available actions. Refer to Using Actions, for more details.

   Figure 9-3 Add Action Dialog Box

   

    

   Figure 9-4 Workflow Variable Assignment Dialog Box

   

    

10. Use the Variable drop-down list to select an existing variable or enter a new variable.

11. Use the XML Expression field to define the XML Expression for this variable.

    Note: Expressions are built using WebLogic Process Integrator expression syntax and typically use the syntax of XPath function to extract values out of XML documents. If you know the syntax of the expression you want to use, you can type the expression directly in the field. Alternatively, click the A+B button to display the Expression Builder dialog box. The Expression Builder helps you construct an expression, which is made up of functions, operators, literals, and variables. For more information on constructing expressions, see Using Expressions and Conditions.

12. Click OK to confirm your changes.

13. Click OK in the Start Properties dialog box to confirm your changes.

Workflow Examples

The following example shows a workflow that is triggered by the XML document containing the root element order if the workflowstatus element of the XML document is "new".

The following workflow variables are populated with the values contained in the XML document:

• OrderId

• QuoteId

• CustomerName

  Figure 9-5 Start Properties Dialog Box

  

   

The corresponding XML document is as follows:

Listing 9-1 XML Document

<Order>

   <OrderId>1</OrderId> 

   <OrderType>New</OrderType> 

   <WorkflowStatus>New</WorkflowStatus> 

   <Status /> 

 <LEC>

   <VendorId>ABC</VendorId> 

   </LEC>

 <SalesPerson>

   <UserId>Mark</UserId> 

   <Email>Mark@ABC</Email> 

   </SalesPerson>

 <Quote>

   <Id>1</Id> 

   </Quote>

 <Customer>

   <FirstName>Joe</FirstName> 

   <LastName>Customer</LastName> 

 <Address>

   <Street>123 Main Street</Street> 

   <City>Boston</City> 

   <State>MA</State> 

   </Address>

   </Customer>

   </Order>

The root element is order.

The XML expression is XPath("/Order/Customer/FirstName/text()") + XPath("/Order/Customer/LastName/text()")

The customer element has three subelements: FirstName, LastName, and Address. Values from the XML document are extracted using the XPath language.

Figure 9-6 Workflow Variable Assignment Dialog Box

 

 

---

Using the XML Notification: The WebLogic Process Integrator Event

A workflow event represents a notification node. Any time an event is defined, the workflow waits for an XML message to trigger the event. Upon that trigger, various subactions defined within the event can be executed and/or workflow variables can be set.

To define a WebLogic Process Integrator notification event:

1. Open the Event Properties dialog box as described in Defining Events in Working with Workflow Components, for instructions on accessing this dialog box.

   Figure 9-7 Event Properties Dialog Box

   

    

2. In the Description field, enter a meaningful name for the event you will define. The name will be displayed in the workflow drawing area.

3. In the Root Element field, enter the XML document root element to serve as the event trigger.

4. In the Key Value Expression field, define a key value for the XML document.

   Note: It is possible to define a key value for each XML root in order to speed up the search for a specific XML trigger. For instructions, see Setting Up a Key Value for Each XML Root.

5. In the Condition field, define the condition under which the event is to be triggered. The workflow will be triggered by the XML document, provided that this defined condition is verified.

6. Use the Variables tab to assign values by way of the XML document. Click Add to display the following dialog box where each variable can be assigned an XML Expression.

   Note: Expressions are built using WebLogic Process Integrator expression syntax and typically use the syntax of XPath function to extract values out of XML documents. If you know the syntax of the expression you want to use, you can type the expression directly in the field. Alternatively, click the A+B button to display the Expression Builder dialog box. The Expression Builder helps you construct an expression, which is made up of functions, operators, literals, and variables. For more information on constructing expressions, see Using Expressions and Conditions.

   Figure 9-8 Workflow Variable Assignment Dialog Box

   

    

7. Use the Variable drop-down list to select an existing variable or enter a new variable.

8. Use the XML Expression field to define the XML Expression for this variable.

   Note: Expressions are built using WebLogic Process Integrator expression syntax and typically use the syntax of XPath function to extract values out of XML documents. If you know the syntax of the expression you want to use, you can type the expression directly in the field. Alternatively, click the A+B button to display the Expression Builder dialog box. The Expression Builder helps you construct an expression, which is made up of functions, operators, literals, and variables. For more information on constructing expressions, see Using Expressions and Conditions.

9. Click OK to confirm your changes.

10. Select the Next tab of the Event Properties dialog box to display a list of all task, decision, join, and done nodes in the current workflow.

11. Select the node to succeed the event. An event can have one or more successors. The indicated items in this list will be the next activated in the flow after the event is triggered.

12. Select the Actions tab to display the list of all actions to be performed upon the triggering of the event.

13. Click Add to display the list of available actions. Refer to Working with Actions in Using Actions, for action procedures.

    Figure 9-9 Add Action Dialog Box

    

     

14. Use the Notes tab to record notes about the event.

Setting Up a Key Value for Each XML Root

A key value acts as a filter for locating the correct trigger position to a specific root element. A key value can be set to a variable, for instance OrderId. At run time, the XML processor looks for a trigger with the root element Order and the specified OrderId that will be the value of that variable at the time the workflow is run. This avoids a sequential search of all triggers in order to find the right one.

To set up a key value for each XML root, proceed as follows:

1. From the WebLogic Process Integrator Configuration menu, select Events to display the Event Key Expression dialog box.

   Figure 9-10 Event Key Expressions Dialog Box

   

    

2. In the XML Root field, enter the XML document root.

3. In the Expression field, set up a key value for the XML root.

   Note: Expressions are built using WebLogic Process Integrator expression syntax and typically use the syntax of XPath function to extract values out of XML documents. If you know the syntax of the expression you want to use, you can type the expression directly in the field. Alternatively, click the A+B button to display the Expression Builder dialog box. The Expression Builder helps you construct an expression, which is made up of functions, operators, literals, and variables. For more information on constructing expressions, see Using Expressions and Conditions.

4. Click OK to confirm your entries.

 

---

Using XML Actions

This section introduces you to the following XML-related actions within WebLogic Process Integrator:

• Post XML Event

• Send XML to Client

• XML Root Element Names

Post XML Event

Post an XML event from the current workflow that can be used to trigger another workflow or an event that is contained within this workflow or another workflow. You can post the XML document as either an external document or as internal messages to the WebLogic Process Integrator server.

To post an XML event, proceed as follows:

1. Access the Add Action dialog box. This dialog box can be accessed from the various Properties dialog boxes in WebLogic Process Integrator. For example, in the workflow drawing area, right-click a task and choose Properties. This displays the Task Properties dialog box.

   Figure 9-11 Task Properties Dialog Box

   

    

2. Click Add to display the Add Action dialog box.

   Figure 9-12 Add Action Dialog Box

   

    

3. Under Integration Actions, select Post XML Event and click OK to display the Post XML Event dialog box.

   Figure 9-13 Post XML Event Dialog Box

   

    

4. Select the destination where the XML document will be posted; if External is checked, the created XML document is posted on a specified JMS topic. The filed JMS topic is displayed, allowing you to enter the name of the topic. If Internal is checked, the XML message is used to trigger another workflow or an WebLogic Process Integrator event defined within a workflow.

5. If external, the XML document will be posted on a specified JMS topic. The filed JMS topic will open-up for the user to type the in the name of the topic.

6. If the XML document to be posted is stored in a variable of type XML, select this variable from the From XML Variable drop-down list. (The XML type variable is defined in the Set Variable action in Timed Event in Using Actions.)

7. If you select an External destination, in the JMS Topic field, enter the name of the JMS topic to which the XML document will be posted. Normally, this is defined for the external client that is listening to receive the message.

8. Use the remaining portion of the Post XML Event dialog box to create an XML structure containing elements and attributes, as follows:

   1. Select either the Element or Attribute radio button, depending on what you are adding to the XML document structure.

   2. In the Name field, enter the name of the element or attribute, and click Add to add it to the XML document.

   3. Use the directional arrows to the right to move the element or attribute forward or backwards, up or down, depending on where you need to position it in the structure. Moving an element or attribute forward will make it a subelement of the previous main node.

      Figure 9-14 Subelement

      

       

   4. Use the Value Expression field to define the value of an element or attribute. The value can be either a string, typed in quotes, or an expression containing workflow variables and functions. For example, in the following figure, the attribute ID is being assigned the value of the workflow variable: OrderId.

      Note: Expressions are built using WebLogic Process Integrator expression syntax and typically use the syntax of XPath function to extract values out of XML documents. If you know the syntax of the expression you want to use, you can type the expression directly in the field. Alternatively, click the A+B button to display the Expression Builder dialog box. The Expression Builder helps you construct an expression, which is made up of functions, operators, literals, and variables. For more information on constructing expressions, see Using Expressions and Conditions.

      Figure 9-15 Post XML Event Dialog Box

      

       

   5. Click OK to post the XML event.

Send XML to Client

This action allows communication between the WebLogic Process Integrator server and a client program by way of an XML message. The Send XML to Client action expects a response back from the client. The WebLogic Process Integrator Worklist client application is a good example of use for this action.

To send an XML document to a client, proceed as follows:

1. Access the Add Action dialog box. This dialog box can be accessed from the various Properties dialog boxes in WebLogic Process Integrator. For example, from the workflow drawing area, right-click a task and choose Properties. This displays the Task Properties dialog box.

   Figure 9-16 Task Properties Dialog Box

   

    

2. Click Add to display the Add Action dialog box.

   Figure 9-17 Add Action Dialog Box

   

    

3. Under Integration Actions, select Send XML to Client and click OK to display the Send XML to Client dialog box. The Send XML to Client dialog box contains the following:

   • XML Document Structure — create an XML structure with elements, subelements, and attributes. Values can be entered for each element or attribute of the XML document. Refer to XML Root Element Names.

     Note: The instructions for creating an XML document structure in Post XML Event can be applied here.

   • Name — name of the XML Element or Attribute.

   • Value Expression — expression to be evaluated at run time for the XML event.

     Note: Expressions are built using WebLogic Process Integrator expression syntax and typically use the syntax of XPath function to extract values out of XML documents. If you know the syntax of the expression you want to use, you can type the expression directly in the field. Alternatively, click the A+B button to display the Expression Builder dialog box. The Expression Builder helps you construct an expression, which is made up of functions, operators, literals, and variables. For more information on constructing expressions, see Using Expressions and Conditions.

   • Callback Variables — retrieves callback information, such as user input or information from a database. Provides a method for placing data into an existing workflow variable.

   • Callback Actions — relates to the Callback Variables feature. When information is returned (based on the callback variable), tells the system to perform certain actions. Normally, you use the Mark Task as Done action here for synchronous messaging.

   • Notes — a free-form text box for notes about the action.

     Figure 9-18 Send XML to Client Dialog Box

     

      

XML Root Element Names

The name of the root element in the XML message format defines the processing performed by the client as follows:

Table 9-1 XML Root Elements

XML Root Element Name	Function Performed by Client
message-box	A message-box pop-up is displayed. Reply = ok/yes/no/cancel
set-variables	A query-box pop-up is displayed. Reply = name/value pairs
call-addin	Invokes a custom extension to the Worklist client application.
call-program	Spawns a process on the client machine.

Default Settings for Send XML to Client Action

For users who are using the WebLogic Process Integrator Worklist application, you can set up two default settings, which allow you to:

• Prompt for a value upon execution of a task in the WebLogic Process Integrator worklist (displays a prompt dialog box where values can be entered).

• Display a text box upon execution of a task in the WebLogic Process Integrator worklist (displays a text box where values can be entered).

Dialog Box Prompt

Set up the dialog box prompt default setting shown in the following dialog box and procedure.

Figure 9-19 Send XML to Client Dialog Box

 

To set up the dialog box prompt default setting:

1. Enter the following name for the root element of the XML document: set-variables (all in lowercase).

2. Set up title as an attribute; title takes the title value of the dialog box to be displayed.

   Note: actionid cannot be edited.

3. For each variable, create an element root with two attribute as follows:

   Variable

   Name

   Prompt

   Variable

   Name

   Prompt

This configuration displays the Enter Your Name dialog box upon execution of a task in the WebLogic Process Integrator Worklist.

Figure 9-20 Enter Your Name Dialog Box

 

 

After the user enters the values for the first name and last name, the two variables (set up in step 3) are populated by the callback XML document.

Display Message-Box

The default message-box can be set up as one of the following:

• Plain

• Information — provides information to the user.

• Question — asks the user a question.

• Warning — displays a warning to the user.

• Error — indicates an error to the user.

  Figure 9-21 Send XML to Client Dialog Box

  

   

1. Enter the following name for the root element of the XML document: message-box (all in lowercase, include the hyphen).

2. Set up title as an attribute; title takes the title value of the message-box to be displayed.

3. Set up style as an attribute; selections are plain, information, question, warning, or error.

4. Set up options as an attribute; selections are ok, ok_cancel, yes_no, yes_no_cancel.

To display a message-box, send the following XML:

Listing 9-2 Message-Box XML

<message-box title="title" style="style" options="options">message 

<actionid>959395846210</actionid> 

</message-box>

where 

style ::= { plain | information | question | warning | error } 

options :: { ok | ok_cancel | yes_no | yes_no_cancel }

The message-box returns the following XML: 

<message-box option="option"></message-box>

where 

"option" is one of: "ok", "cancel", "yes", "no"

Use the XPath function to extract the value: 

XPath("/message-box/attribute::option")

The following is an example of a resulting message-box:

Figure 9-22 Example Message-Box

 

Invoke Exception Handler

Use this action to allow the invocation of a specific exception handler within the workflow. Upon execution of the Invoke Exception Handler action, WebLogic Process Integrator sends the user-defined XML document to the exception processor and invokes the specified exception handler.

To invoke an exception handler, proceed as follows:

1. Access the Add Action dialog box. This dialog box can be accessed from the various Properties dialog boxes in WebLogic Process Integrator. For example, from the workflow drawing area, right-click a task and choose Properties. This displays the Task Properties dialog box.

2. Click Add to display the Add Action dialog box.

   Figure 9-23 Add Action Dialog Box

   

    

3. Under Exception Handling Actions, select Invoke Exception Handler and click OK to display the Invoke Exception Handler dialog box.

   Note: You cannot invoke an exception handler from within another exception handler. Therefore, if you access the Add Action dialog box from within an exception handler, the Invoke Exception Handler action is not available.

   Figure 9-24 Invoke Exception Handler Dialog Box

   

    

4. The Invoke Exception Handler dialog box contains the following:

   • Exception Handler — specify the exception handler to invoke. If no custom-defined exception handlers exist, the system exception handler, by default is used and invoked whenever an exception occurs. The system exception handler is available for use at all times, even if custom handlers are defined.

   • XML Document Structure — create an XML document with elements, subelements, and attributes. Values can be entered for each element or attribute of the XML document. Refer to XML Root Element Names. Creating an XML document within this action is optional. This action can be used just to invoke an exception handler and not necessarily send information through XML.

     Note: The instructions for creating an XML document structure in Post XML Event can be applied here.

   • Name — name of the XML Element or Attribute.

   • Value Expression — expression to be evaluated at run time for the XML document.

     Note: Expressions are built using WebLogic Process Integrator expression syntax and typically use the syntax of XPath function to extract values out of XML documents. If you know the syntax of the expression you want to use, you can type the expression directly in the field. Alternatively, click the A+B button to display the Expression Builder dialog box. The Expression Builder helps you construct an expression, which is made up of functions, operators, literals, and variables. For more information on constructing expressions, see Using Expressions and Conditions.

   • Notes — a free-form text box for notes about the action.

 

---

Understanding Workflow Interaction

To better understand workflows and how the various components defined within workflows interact, refer to the WebLogic Process Integrator Tutorial.