|
|
|
|
|
|
Using Workflow Expressions
The following sections explain the workflow expression language, and how to use the Expression Builder and XPath Wizard to generate workflow expressions:
About Workflow Expressions
Wherever you see the Expression button 
next to a field in a Studio dialog box, this indicates that the field requires an entry formulated in the workflow expression language. Expressions are used throughout the Studio to create template definition labels, define conditions in decision nodes and events, configure event keys, and to specify information that will be provided at run time.
A workflow expression is an algebraic expression that defines a calculation that the system performs at run time, and is made up of literals, such as strings, integers and other constants, workflow variables, operators, and workflow functions. Workflow expression syntax allows you to manipulate strings, test for relationships and conditions, perform arithmetic calculations, use functions that obtain run-time information from workflows or XML messages, and so on.
The result of an expression may be a string, integer, double, date/time value, or Boolean values. Expressions that yield a Boolean result are referred to as conditional expressions or conditions.
The Studio also provides two tools to help you construct expressions: the Expression Builder, which provides syntax checking and error information (described in Using the Expression Builder), and the XPath Wizard, which you use to generate XPath expressions from sample XML documents (described in Creating XPath Expressions Using the XPath Wizard).
The following sections provide the syntax for literals, operators, and workflow variables, and introduce the use and syntax of built-in functions.
Using Literals
Expressions can contain literal values or constants. The following table describes the available literals.
Note: Date literals can only be used to set date-type variables. They cannot be used in functions or expressions used in any other contexts.
Using Variables
An expression can contain references to any workflow variable defined in a current workflow.
A workflow variable reference can use any one of the following syntaxes:
Using Operators
The following table describes the available operator values.
Using Functions
Functions are built-in expressions you can use to get run-time data. You can use functions for various purposes, such as typecasting variables, identifying workflow information, and performing operations on data. Many functions also allow you to specify built-in attributes that return specific workflow and system data at run time.
The following sections group workflow functions by category. In the listings, typical function attributes are given in parentheses. Note, however, that functions can contain other functions and expressions, and attributes can also be expressed as embedded expressions.
Note: In addition to the default functions listed in this section, there may also be plug-in functions that you can use.
If you want to assign the results of functions to variables or compare the results of two functions, you will need to ensure that the data types match. Thus, return types are also listed in the following function descriptions.
Obtaining Run-time System Data
Use the functions listed in this section to obtain system information at run-time:
Date()
Extracting Run-Time Event Data
You can use the following functions for obtaining properties and extracting content from the header or XML body of JMS messages destined for workflows:
EventAttribute()
EventData()
XPath()
XPath is a language for addressing parts of an XML document. It provides basic facilities for the manipulation of strings, numbers, and Booleans. XPath gets its name from its use of a path notation as in URLs for navigating through the hierarchical structure of an XML document. To obtain the official specifications of the XPath language, refer to the following Internet site: http://www.w3.org/TR/xpath.html
To obtain a quick reference guide to XPath notations and functions, refer to the following Internet site: http://www.mulberrytech.com/quickref/XSLTquickref.pdf
The following are examples of the most common uses of XPath for retrieving text values from nodes, attribute values, selecting sub-trees, selecting nodes by attribute value and so on from an XML document. Consider the XML document in the following listing:
Listing 8-1 Sample XML Document
<?xml version="1.0"?>
<a>
<b name="bill">This is the first value</b>
<c>
<d id="d1">This is the second value</d>
<d id="d2">This is the third value</d>
<d id="d3">This is the fourth value</d>
<d id="d4">This is the fifth value</d>
</c>
</a>
To select the textual value of the <b> element (i.e., "This is the first value"):
XPath("/a/b/text()")To select the textual value of the <d> element whose ID attribute has the
value "d3" (i.e., "This is the fourth value"):
XPath("/a/c/d[@id=\"d3\"]/text()")To select the textual value of the second <d> element (i.e., "This is the third value"):
XPath("/a/c/d[2]/text()")To select the value of the name attribute of the <b> element (i.e., "bill"):
XPath("/a/b/@name")To select the entire <c> subtree:
<c>
<d id="d1">This is the second value</d>
<d id="d2">This is the third value</d>
<d id="d3">This is the fourth value</d>
<d id="d4">This is the fifth value</d>
</c>)
XPath("/a/c")
Note: To create XPath expressions, you can either type them yourself, or you can use the XPath Wizard. For details about using the wizard, see Creating XPath Expressions Using the XPath Wizard.
XML Element Dot Notation
For variable initialization purposes, in Start or Event Properties, Exception Handler Properties, and Send XML to Client, you can also use a simpler dot notation to obtain element data from an XML document, with the following syntax:
root_element.subelement1.subelement2.subelement3 . . .
Consider the following sample XML document:
Listing 8-2 Sample XML Document
<account>
<number>847365</number>
<customer>John Doe</customer>
<balance>
<status>past due</status>
<date_due>7-11-2001</date_due>
<amount_due>5670.85</amount_due>
</balance>
<credit_limit>7500.00</credit_limit>
</account>
In this example, to retrieve the value past due, you would use the following expression:
account.balance.status
Note that you cannot use this notation to obtain attribute values, and that the root element must begin the expression. You cannot begin the expression with a sub-element.
Note also that this notation always returns a string, and not be used with typecasting functions to return any other data type.
Obtaining Run-time Workflow Data
Use the functions listed in this section to obtain run-time data from workflows:
CurrentUser()
|
Description |
Returns the ID (user name) of the user currently executing a task. |
|
Format |
CurrentUser() |
|
Return type |
String |
TaskAttribute()
Note: If you try to use an atrribute other than the ones listed in the above table, the server will throw an exception.
WorkflowAttribute()
Note: If you try to use an atrribute other than the ones listed in the above table, the server will throw an exception.
WorkflowVariable()
Converting Data Types
You can use several functions to convert the return type of one expression to another. For information on workflow type conversion rules, see Data Type Conversions for Variable Assignment.
DateToString()
StringToDate()
ToInteger()
ToString()
|
Description |
Converts any data type value to a string. |
|
Format |
ToString(expression) expression is the expression to be converted to string. |
|
Example |
ToString($TotalPrice) |
|
Return type |
String |
Manipulating Data
You can use functions listed in this section to perform various operations on data:
Abs()
DateAdd()
StringLen()
SubString()
Date Function Formats
To specify a date format for any of the date functions, use a time pattern string to describe dates and times. For example, the following time pattern string used in a DateToString() function:
"yyyy.MM.dd G 'at' hh:mm:ss z"
results in the following formatting:
2000.07.31 AD at 13:10:35 PDT
Similarly, if you use the StringToDate() function, you must format a date literal according to the format you specify.
This section describes pattern letters, provides formatting guidelines, and shows examples.
Table 8-3 Pattern Letter Definitions
Format Guidelines
The count of pattern letters determine the format.
Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '@' will appear in the resulting time text even though they are not within single quotes.
A pattern containing any invalid pattern letter will result in a thrown exception during formatting or parsing.
Examples of Time Patterns
Table 8-4 Examples Using the U.S. Locale
Data Type Conversions for Variable Assignment
Often you will want to assign the resulting value of an expression to a workflow variable. For example, you may want use the data returned by an XPath expression from an XML document to initialize variables when a workflow starts. Or you may wish to assign the value of one variable type to another.
Where the return type of an expression is different from the type of variable to which you want to assign the expression's resulting value, the server automatically performs a type conversion. In some cases, however, a conversion cannot be performed, and an exception will occur. The following table shows how conversions are handled. Numbers in the table correspond to notes following the table.
Note: The conversion rules presented in the following table apply to the default settings for data types. For conversion rules used for null value support, see "Configuring BPM to Support Null Variables" in Customizing WebLogic Integration in Starting, Stopping, and Customizing BEA WebLogic Integration.
Table 8-5 Data Type Conversion Rules
NS = Not supported. If the conversion is attempted, an error message is displayed indicating that the conversion is illegal.
Node List = the object returned by an XPath text() function.
* If the source value is not a valid input for the target data type, an error message is displayed indicating that the conversion is illegal.
** True if string value is "true", "t", or "1"; false if string value is "false", "f", "0". Any other string value will cause an error message to be displayed indicating that the conversion is illegal.
*** DOM object serialized to string, and then converted to the target data type. If the source value is not a valid input for the target data type, an error message is displayed indicating that the conversion is illegal.
**** DOM object serialized to string. True if string value is "true", "t", or "1"; false if string value is "false", "f", "0". Any other string value will cause an error message to be displayed indicating that the conversion is illegal.
***** DOM parsing to an XML document element, not simply a node. This means that if it is reconverted to a String, the string will contain an XML header similar to the following: <?xml version="1.0" encoding="UTF-8"?>. If the source value is not valid for DOM parsing, an error message is displayed indicating that the conversion is illegal.
Note that these conversion rules are not fully supported for calculations in expressions. For example, assume you have the following expression:
XPath("your_expression") + 2
The result of this statement cannot be calculated because the data type of your_expression is not known. To make this statement valid, you need to use a typecasting function to convert the result to the data type you want.
For example, assuming your_expression evaluates to a value of 3, and you want the result to be an string data type. You need to use the following statement:
ToString(XPath("your_expression") + 2
In this case, the expression will evaluate to a string value of 52.
Now let us assume that your_expression evaluates to a value of 3, and you want the result to be an integer. You need to use the following statement:
ToInteger(ToString(XPath("your_expression")) + 2
In this case, the expression will evaluate to an integer value of 7.
Using the Expression Builder
The Expression Builder helps you to build expressions, that consist of functions, operators, literals, and variables. Throughout the Studio, dialog box fields have an Expression Builder button, shown in the following figure.
Figure 8-1 Expression Builder Button
You click the button to display the Expression Builder dialog box. Figure 8-2 Expression Builder Dialog Box
Note: If a plug-in is defined for functions that are part of expressions, this dialog box contains the new function. To build an expression:
If you enter an invalid expression, the system displays a message that attempts to explain why the expression is invalid. The following table lists the messages that may be encountered, together with possible causes.
Table 8-6 Invalid Expression Messages
The Expression Builder does not check the validity of the following:
Creating XPath Expressions Using the XPath Wizard
The XPath wizard provides a graphical interface that you can use to generate XPath expressions automatically from actual XML entities, or define and test XPath expressions that define and validate against XML entities. Once you have generated and tested an XPath expression, you can return it to the Expression Builder which appends any additional arguments required to conform to workflow syntax.
The XPath Wizard can sample XML documents, or Document Type Definition (DTD), XML Schema document (XSD), Extensible Stylesheet Language (XSL) or Message Format Language (MFL) files. If you load a DTD, Schema, XSL, or MFL file into the wizard, it automatically generates a sample XML document based on the specifications in the file you selected. You use the generated XML document to create the XPath expression.
To open the XPath Wizard, from the Expression Builder, click XPath Wizard.
Figure 8-3 XPath Wizard
All three tabs display a toolbar and two common read-only fields:
Toolbar buttons are described in the following table.
Table 8-7 XPath Wizard Toolbar Buttons
Generating XPath Location Expressions from XML Entities
Using the XPath wizard, you can generate XPath location expressions that target:
You can load XML, MFL, XSL, DTD or XSD documents for sampling, If you open a DTD or XSD document, the wizard generates a sample XML document from the DTD or Schema you selected. You use the generated XML document to create the XPath expression.
To generate an XPath location expression:
button to open the XML Finder dialog box. Use the XML Finder dialog box to retrieve an XML, DTD, XSD, MFL, or XSL document that you can use the create the XPath expression. For details, see Retrieving XML Entities.After you retrieve the document using the XML Finder, the content of the document appears in the XPath wizard. If you open a DTD or XSD document, the wizard generates a sample XML document from the DTD or Schema you selected.
Figure 8-4 XPath Wizard: Sample Tab with Sample XML Document
button.Viewing XPath Expressions
The Workspace is the area in the XPath Wizard where you can hold all the XPath expressions you create during a session of the Studio. Every time you create an XPath expression, you can pin it to the Workspace. This way, you can create multiple expressions for a single XML document, and then test them later to ensure they return the correct result.
Figure 8-5 XPath Wizard: Workspace Tab
The Workspace shows you the following information for each XPath Expression: To test an expression, select the expression in the list, click the Test tab, and follow the procedures in Testing XPath Expressions. To return an expression to the Expression Builder, select the expression in the list, and click OK. This closes the XPath Wizard window and places the selected expression in the Expression Builder. Testing XPath Expressions You can use the testing feature of the XPath Wizard for several purposes:
For a full list of functions specified by the XPath language, see http://www.w3.org/TR/xpath.html.
After you have built your expression, the XPath Wizard returns the value that is calculated.
Testing Location Expressions
To test an XPath location expression:
After you retrieve the document using the XML Finder, the content of the document appears in the XPath wizard. If you open a DTD or XSD document, the wizard generates a sample XML document from the DTD or Schema you selected.
Figure 8-6 XPath Wizard: Test Tab
button. The new result of the expression is highlighted in the XML document.
Testing Expressions That Contain Functions
To test an XPath expression containing a function:
If you open a DTD or XSD document, the wizard generates a sample XML document from the DTD or Schema you selected. You use the generated XML document to test your XPath expression against.
button. The return value of the function is displayed in the Test area.Figure 8-7 Result of an XPath Function
button. The return value of the function is displayed in the Test area.
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|
