bea.com | products | dev2dev | support | askBEA

Download Docs | Site Map | Glossary
Search

Using the Studio

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

- Using Literals

- Using Variables

- Using Operators

- Using Functions

- Data Type Conversions for Variable Assignment

- Using the Expression Builder

- Creating XPath Expressions Using the XPath Wizard

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.

Table 8-1 Literal Usage

Literal Type | Format | Description | Example
--- | --- | --- | ---
String | "string" or `string' | A character string enclosed in single or double quotes. Use the following escape sequences to embed special characters in the string: \r carriage return character \n line feed character \' single quote character \" double quote character \f form-feed character \t tab character \\ back slash character \0 ASCII null character | "cancelled"
Integer | [+|-] digits | A 32-bit signed integer in the range -2,147,483,647 to +2,147,483,648 (approximately 9 digits or precision) | 5000
Double | [+|-]digits[.[digits]] | A 64-bit IEEE double in the range -253 x 10104 to + 253 x 10104 (approximately 15 digits of precision) | 5000.00
Date | "MM/dd/yyyy hh:mm:ss AM|PM GMT[+|-]hh:mm:ss" |  | "10/01/2001 12:11:11 AM GMT-04:00"

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:

- :variable

- :'variable'

- :"variable"

- $variable

- $'variable'

- $"variable"

Using Operators

The following table describes the available operator values.

Table 8-2 Operator Usage

Operator | Symbol | Syntax | Operand(s) | Result
--- | --- | --- | --- | ---
AND | AND | expr1 AND expr2 | Logical | True if expr1 and expr2 are both True; otherwise False
OR | OR | expr1 OR expr2 | Logical | True if either expr1 or both expr1 and expr2 are True; otherwise False
XOR | XOR | expr1 XOR expr2 | Logical | True if either but not both expr1 or expr2 are True; otherwise False
NOT | NOT | NOT expr | Logical | True if expr is False; otherwise False
(parentheses) | () | (expr) | Any expression | Evaluates expr first
Multiply | * | expr1 * expr2 | Numeric | Numeric product
Divide | / | expr1 / expr2 | Numeric | Numeric quotient
Modulo | % | expr1 % expr2 | Numeric | Numeric modulus (remainder when expr1 divided by expr2)
Plus | + | + expr expr1 + expr2 | Numeric String or numeric | Unary plus String concatenation or numeric addition
Minus | - | - expr expr1 - expr2 | Numeric Numeric | Unary minus (negates expr) Subtraction
Less than | < | expr1 < expr2 | String or numeric | Logical True if expr1 is less than expr2; otherwise False
Less than or equal to | <= | expr1 <= expr2 | String or numeric | Logical True if expr1 is less than or equal to expr2; otherwise False
Equal to | = | expr1 = expr2 | String or numeric | Logical True if expr1 is equal to expr2; otherwise False
Not equal to | <> | expr1 <> expr2 | String or numeric | Logical True if expr1 is not equal to expr2; otherwise False
Greater than | > | expr1 > expr2 | String or numeric | Logical True if expr1 is greater than expr2; otherwise False
Greater than or equal to | >= | expr1 >= expr2 | String or numeric | Logical True if expr1 is greater than or equal to expr2; otherwise False

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()

Date()

Description | Returns the current system date and time at the moment the expression is evaluated, such as the activation of a node, or the execution of an action.
Format | Date()
Return type | Java Date object To format the return value as a string, wrap the Date() function in a DateToString() function and specify the format. For information, see DateToString().

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()

EventAttribute()

Description | Obtains event properties from an incoming JMS message or plug-in-defined event.
Format | EventAttribute(expression) expression is an expression that returns the name of the JMS header or property field. For information about the JMS header and property fields, see "Message" in "WebLogic JMS Fundamentals" in Programming WebLogic JMS at the following URL: http://edocs.bea.com/wls/docs70/jms/fund.html Note: EventAttribute() should be used only in the following contexts, in which an incoming JMS message is consumed: Event nodes Event-triggered Start nodes Event Key Expression configurations
Example | EventAttribute("JMSDestination")
Return type | Java Object

EventData()

Description | Retrieve the actual message content of an incoming JMS message, or plug-in-defined event. The content could be an XML document. Note: EventData() should only be used in the following contexts, where an incoming JMS message is consumed: Event nodes Event-triggered Start nodes Event Key Expression configurations
Format | EventData()
Return type | Java Object

XPath()

Description | Extracts content from XML documents.
Format | XPath("xpathstring", [,xmldocument]) xpathstring is the XPath language expression xmldocument is an expression that yields the XML document against which the XPath expression is evaluated. This may be a string containing the source text of a valid XML document, or more typically, a reference to an XML or string variable containing the XML text. This parameter is optional. If it is not specified, the XML document is assumed to be the incoming XML event. Note: If you do not specify a variable containing an XML document, the XPath() function should only be used in the following contexts, where the identity of the incoming XML document is known: Event nodes Event-triggered Start nodes Event Key Expression configurations Send XML to Client action Exception Handler receiving an XML document from the Invoke Exception Handler action
Example | see below
Return type | DOM object Typically you will use the XPath language's text() function inside a workflow XPath function expression (see below for more information), which returns a Node List. Other XPath functions, however, can return Double, Boolean, String, and Integer types.

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()

- TaskAttribute()

- WorkflowAttribute()

- WorkflowVariable()

CurrentUser()

Description | Returns the ID (user name) of the user currently executing a task.
Format | CurrentUser()
Return type | String

TaskAttribute()

Description | Provides information about a workflow task.
Format | TaskAttribute("attribute" [,"taskname"]) attribute is the task attribute. The following attributes may be used.
Function Attribute | Information | Return Type
TaskId | System-defined task instance ID | String
Assignee | User or role ID of assignee | String
Priority | Priority set by the user | Integer
Due | Task overdue date | Date
Name | Name of task | String
Started | Task start date/time | Date
Completed | Completed date/time | Date
Comment | Task comment set by the user | String
| taskname may be used to specify a task other than the current one in which the expression is defined. Note: Only tasks in the same workflow may be specified.

Note: If you try to use an atrribute other than the ones listed in the above table, the server will throw an exception.

WorkflowAttribute()

Description | Provides information about the current workflow only.
Format | WorkflowAttribute("attribute" ) attribute is the workflow attribute. The following attributes may be used.
Function Attribute | Information | Return Type
InstanceId | System-defined workflow instance ID | String
TemplateId | System-define workflow template ID | String
TemplateDefinitionId | System-defined workflow template definition ID | String
Initiator | Workflow initiator | String
ParentId | System-defined workflow instance ID of a parent workflow instance for a called workflow instance | String
Name | Template name set by the user | String
Started | Start date/time | Date
Completed | Completed date/time | Date
Label Id | Template definition label set by the user | String
Comment | Workflow comment set by the user | String
ExceptionType ErrorType | Name of Java exception class that raised the error | String
ExceptionNumber ErrorNumber | Message number of the error being handled by the exception handler. For a list of workflow error messages by number and text, see System Error Messages. | Integer
ExceptionSeverity ErrorSeverity | Five integer values: 0: Unknown error type, internal use only 1: A fatal exception occurred while processing a user request 2: A fatal, illegal condition such as inconsistent workflow state 3: A non-fatal workflow condition that the user can rectify manually 4: A custom error raised either by an application calling WorkflowProcessor.invokeWorkfowErrorHandler, or by a workflow executing the Invoke Error handler action Note: Value is set to 4 when a workflow invokes an exception handler via the Invoke Error Handler action or via the API. | Integer
ExceptionText ErrorText | Message text of the error being handled by the exception handler For a list of workflow error messages by number and text, see System Error Messages. | String
ExceptionObject ErrorObject | The exception object being handled by the exception handler. | Exception Object

Note: If you try to use an atrribute other than the ones listed in the above table, the server will throw an exception.

WorkflowVariable()

Description | Returns the value of a workflow variable for a particular workflow instance.
Format | workflowVariable(instanceid, variable) instanceid is the workflow instance ID, which would normally be represented by a string-type variable which has been populated with a value provided by the WorkflowAttribute("InstanceID") function sent from another workflow. variable is the workflow variable. For formatting information, see Using Variables.
Example | workflowVariable($InstanceID), $ItemQuantity)
Return type | Object

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()

DateToString()

Description | Converts a date to a string.
Format | dateToString("date", "format") date is the date to be converted to the string value. The date must be expressed as a Java date object, so you must embed the following functions to specify the date: To specify the current run-time date and time at the moment the expression is evaluated, use Date(); see Date(). To specify the run-time date and time when the current workflow is started or completed, use WorkflowAttribute("Started") or WorkflowAttribute("Completed"). To specify the run-time date and time the current task is started or completed, use TaskAttribute("Started") or TaskAttribute("Completed"). format is a string specifying the format of the string. Possible values are listed below. Note: Format is case sensitive.
Format | Description | Example
yyyy | Year | 2000
MM | Numeric month of the year | January = 01, February = 02,
dd | Numeric day of the month | 02 or 28
DD | 3- digit day of the year based on the total number of days (365) in a year | October 18, 2000 = 292 (the 292nd day of the year)
hh | Hours in non-military time | 1 pm = 01, 2 pm = 02
HH | Hours in military time | 1 pm = 13, 2 pm = 14
mm | Minutes | 02
ss | Seconds | 35
SSS | Milliseconds | 370
The following separator characters are valid:- (dash); / (slash); : (colon); .(period); spaces
Example | DateToString(Date(), "yyyy-MM-dd HH:mm:ss.SSS") resulting in 2000-10-18 14:30:35.370
Return type | String

StringToDate()

Description | Converts a string to a date.
Format | StringToDate("string", "format") string is the string to be converted to the date value. The string must be formatted according to the format you specify in the second argument. format is a string specifying the format of the date. For available formats, see Date Function Formats.
Example | StringToDate("2001.09.10", "yyyy.MM.dd")
Return type | Date

ToInteger()

Description | Converts a string value to an integer. Note: The string must represent a valid integer value.
Format | ToInteger(expression) expression is the expression (or string enclosed in double quotes) to be converted to integer.
Example | ToInteger(ToString(XPath("/item/quantity/text()")))
Return type | Integer

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()

Abs()

Description | Returns the absolute value of an expression.
Format | Abs(expression) expression is a workflow expression for which the absolute value is to be calculated.
Example | Abs($ItemPrice * $ItemQuantity)
Return type | Integer, Double, or String, depending on input

DateAdd()

Description | Performs date arithmetic.
Format | DateAdd(date, "interval", number [,business calendar name]) date is the base date. The date must return a Java date object, so you must embed the following functions to specify the date: To specify the current run-time date and time at the moment the expression is evaluated, use Date(); see Date(). To specify the run-time date and time when the current workflow is started or completed, use WorkflowAttribute("Started") or WorkflowAttribute("Completed"). To specify the run-time date and time the current task is started or completed, use TaskAttribute("Started") or TaskAttribute("Completed"). To specify a constant base date, use StringToDate() function in the appropriate format; see StringToDate(). For formatting information, see Date Function Formats. interval is the unit of time to use. Possible values are listed below. Note: The interval is not case sensitive except for m and M.
Interval | Description
S | Seconds
m | Minutes
H | Hours
D | Days
W | Weeks
M | Months
BH | Business hours
BD | Business days
number is an integer (optionally signed) indicating the number of units to add or subtract. business calendar name is the name of the business calendar to be used for the business hours and business days calculation. If no calendar is specified, the default calendar is used.
Example | DateAdd(Date(), D, 7, mycalendar)
Return type | Date

StringLen()

Description | Returns the length of a string
Format | stringlen(expression) string is the string or expression for which a length will be provided.
Example | stringlen(TaskAttribute("Comment"))
Return type | Integer

SubString()

Description | Extracts a substring from a string.
Format | SubString(expression, start [,length]) string is the string from which the substring is to be extracted. start is the starting position in the string. (The first position is 0.) length is the length of the substring. This is an optional parameter. If it is not included, the substring extracted will be the rest of the string.
Example | SubString(TaskAttribute("Comment"), 0, 50)
Return type | String

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

Symbol | Description | Format | Example
--- | --- | --- | ---
G | era designator | text | AD
y | year | number | 1996
M | month in year | month name & 01 - 12 | July & 07
d | day in month | 01 - 31 | 10
h | hour in am/pm | 1 - 12 | 12
H | hour in day | 0 - 23 | 0
m | minute in hour | number | 30
s | second in minute | number | 55
S | millisecond | number | 978
E | day in week | day name | Tuesday
D | day in year | number | 189
F | day of week in month | number | 2 (2nd Wed in July)
w | week in year | number | 27
W | week in month | number | 2
a | am/pm marker | AM or PM | PM
k | hour in day | 1 - 24 | 24
K | hour in am/pm | 0 - 11 | 0
z | time zone | abbreviated text | PST
' | escape for text |  | `at'
'' | single quote | ' | `Wednesday''s'

Format Guidelines

The count of pattern letters determine the format.

- for text: for 4 or more pattern letters, use the full form. For less than 4, use the short or abbreviated form, if one exists.

- for number: the minimum number of digits. Shorter numbers are zero-padded to this amount. Year is handled specially; that is, if the count of `y' is 2, the year will be truncated to 2 digits.

- for text or number: for 3 or more pattern letters, use text; otherwise, use a number.

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

Format Pattern | Result
--- | ---
"yyyy.MM.dd G 'at' hh:mm:ss z" | 1996.07.10 AD at 15:08:56 PDT
"EEE, MMM d, ''yy" | Wed, July 10, '96
"h:mm a" | 12:08 PM
"hh 'o''''clock' a, zzzz" | 12 o'clock PM, Pacific Daylight Time
"K:mm a, z" | 0:00 PM, PST
"yyyyy.MMMMM.dd GGG hh:mm aaa" | 1996.July.10 AD 12:08 PM

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

Source Expression Evaluates to: | Target Variable Type:
--- | ---
String | Integer | Double | Date | Boolean | XML
String | String | Integer* | Double* | Date* | Boolean** | See Note *****.
Integer | String | Integer | Integer's Double value | NS | False if Integer value is 0, true if any other value | NS
Double | String | Double's Integer value | Double | NS | False if Double value is 0.0, true if any other value | NS
Date | String | NS | NS | Date | NS | NS
Boolean | "True" or "False" | 1 if true, 0 if false | 1.0 if true, 0.0 if false | NS | Boolean true or false | NS
XML | DOM serialized to String | Integer*** | Double*** | Date*** | Boolean**** | XML
Node List | DOM serialized to String | Integer*** | Double*** | Date*** | Boolean**** | XML node***

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:

1. Do any of the following:

   - Type the expression or an expression component directly in the Expression field.

   - Select from the Functions, Operators, Literals, and Variables options, and double-click a component from the scrollable list to the right to place the selected expression text in the Expression field. In some cases, the inserted item contains placeholders. You can either replace the placeholders by typing the correct information or by inserting additional components from the component lists.

   - For the XPath function, optionally click XPath Wizard to open the XPath Wizard to automatically generate XPath function expressions from sample XML documents. For details about using the wizard, see Creating XPath Expressions Using the XPath Wizard.

2. When the expression in the Expression field is complete, click OK to return the expression to the source dialog box field.

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

Message | Possible Cause(s)
--- | ---
Invalid operator operand | One or both of the operand(s) to an AND, OR, XOR, NOT,*,/,%,+,-,<,<=,=,<>,>=,> operator was not valid. For example, attempted arithmetic on a non-numeric string: "Name: " * 25.4
Mismatched operand types in operator comparison | Attempting to compare values of different types. For example, comparing a string to a number: "mystring" <= 56.9.
NumberFormatException | A string representation of a number did not have the required format for the type of number. For example: 1.23ZX
Invalid function name | The expression calls an undefined function. For example: "Name: " + somefunc() is not a valid function name.
Incomplete escape sequence | The last character in a quoted string was a backslash character that was not followed with one of the following characters: r, n, f, t, \, ', ",0.
Invalid escape sequence | A quoted string contained a backslash character that was not followed with one of the following characters: r, n, f, t, \, ', ",0.
Fatal error | An internal error occurred in the expression evaluator. The expression probably contains a syntax error.
Unclosed string | A string literal did not have a matching quote at the end. In the following example, a double quote is not matched by a single quote: "This is an unclosed string'
Illegal character | The expression contains a character that violates the syntax of the expression language. In the following example, ! is the invalid character: 7 * $wks + " days" !
Error: unmatched input | The evaluator could not interpret the expression. The expression probably contains a syntax error.
Unrecoverable syntax error | The expression contains an invalid token. In this example, name is invalid because the + operator was omitted: "Name: " $name The Expression should have been: "Name: " + $name

The Expression Builder does not check the validity of the following:

- The data type of a workflow variable referenced by the expression.

- The correct number of parameters being passed to a function.

- Type matching. If there is a type mismatch in the expression (for example, performing arithmetic on a non-numeric string), a run-time error results when the expression is evaluated.

- Function attributes. If you use an attribute that is not valid for a function, a run-time exception results.

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

The XPath Wizard contains three tabs: Workspace, Sample, and Test, which you use to do the following:

- Workspace tab—View all the XPath location expressions and functions you create during a Studio session and select them one by one to test on the Test tab, or to return them to the Expression Builder. See Viewing XPath Expressions.

- Sample tab—Generate XPath expressions for sample XML, DTD, MFL, and Schema documents. Procedures are given in Generating XPath Location Expressions from XML Entities.

- Test tab—Test XPath expressions by applying them to XML documents. See Testing XPath Expressions.

All three tabs display a toolbar and two common read-only fields:

- Document Type—indicates whether the currently loaded document is associated with a type definition or not. If the loaded file is a DTD or XSD, the path and filename are given. For other documents, no type or identification is given.

- Document Location—indicates whether the currently loaded document is a system-generated sample document or not. If the loaded document is an XML, MFL or XSL document, the path and filename are given.

Toolbar buttons are described in the following table.

Table 8-7 XPath Wizard Toolbar Buttons

Button | Description
--- | ---
| Load an XML entity into the XPath Wizard. For more information, see Generating XPath Location Expressions from XML Entities.
| Pin an XML expression to the Workspace. For more information, see Generating XPath Location Expressions from XML Entities.
| Test a selected XML expression against an XML entity. For more information, see Testing XPath Expressions.
| Display information about the XPath wizard.

Generating XPath Location Expressions from XML Entities

Using the XPath wizard, you can generate XPath location expressions that target:

- Element content

- Attribute content

- Nodes

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:

1. From the Expression Builder dialog box, click XPath Wizard to display the XPath Wizard.

2. In the XPath Wizard, select the Sample tab to open the Sample area where you can create XPath expressions.

3. Click the 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

4. Select the markup or content for an element, attribute, or node that you want to be the target of the XPath expression. The wizard generates an XPath expression based on your selection, and displays it in the XPath Expression field.

5. Put the XPath expression you created in the Workspace by clicking the button.

6. To view the expressions you create, select the Workspace tab. For details, see Viewing XPath Expressions.

7. To test the expressions you create, select the Test tab. For details, see Testing XPath Expressions.

8. Click OK to return the expression to the Expression Builder.

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:

XPath Expression | The XPath location expression generated on the Sample tab or entered on the Test tab.
Target | The element or attribute in the XML document that is the target of the XPath expression.
Document | The source document from which the XPath expression was generated.

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:

- To test a location expression you have built in the Expression Builder or that you have generated from a sample document. After you have generated XPath location expressions from one document, you may want to test them against other sample documents to be sure that they still return the content you expect.

- To validate other types of XPath expressions, including XPath language functions, that you create yourself, against a sample document. You can pass expressions that you have built in the Expression Builder directly to the Wizard, you can append an XPath function to a location previously generated by the Sample feature, or you can create the expression from scratch in the Wizard. All of the functions of the XPath language are supported by the testing feature of the XPath Wizard, including:

- String functions that perform operations on the string contents of nodes and attributes, such as accessing, extracting, and combining

- Boolean functions that perform Boolean tests or operations on their arguments, and that return a value based on the test or operation

- Number functions that return numeric results, such as a count of nodes in an document, or the sum of numeric content

- Node set functions that return information about individual nodes or node sets

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:

1. Optionally, from the Expression Builder, enter the XPath expression you want to test, and click XPath Wizard. The XPath expression appears as the first item in the XPath Expression list in the Workspace.

2. Select the Sample tab, and click the Open button to open the XML Finder dialog box. Use the XML Finder dialog box to retrieve an XML, DTD, XSL, XSD, or MFL document that you will use to test 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.

3. If you did not pass an expression from the Expression Builder as in step 1, generate an XPath location expression from the sample document, as described in Generating XPath Location Expressions from XML Entities.

4. In the Workspace, select the expression you want to test.

5. Select the Test tab. The Test area shows you the XML document with the target of the XPath expression highlighted.

   Figure 8-6 XPath Wizard: Test Tab

6. If desired, modify the XPath expression by editing it in the XPath Expression field.

7. To test the expression again, so that the value is highlighted in the document, click the button. The new result of the expression is highlighted in the XML document.

8. To return the expression to the Expression Builder, click OK.

Testing Expressions That Contain Functions

To test an XPath expression containing a function:

1. Optionally, from the Expression Builder, enter the XPath expression you want to test, and click XPath Wizard. The XPath expression appears as the first item in the XPath Expression list in the Workspace.

2. Select the Sample tab, and click the Open button to open the XML Finder dialog box. Use the XML Finder dialog box to retrieve an XML, DTD, or Schema (XSD) document that you will use to test the XPath expression. For details, see Retrieving XML Entities.

   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.

3. Optionally, generate an XPath location expression from the sample document, as described in Generating XPath Location Expressions from XML Entities.

4. Select the Test tab.

5. In the XPath Expression field, enter your expression, or edit or append a function to an expression you have placed there from the workspace.

6. Click the button. The return value of the function is displayed in the Test area.

   Figure 8-7 Result of an XPath Function

7. If necessary, modify the XPath function by editing it in the XPath Expression field.

8. To test the function again, click the button. The return value of the function is displayed in the Test area.

9. To return the function to the Expression Builder, click OK.