Using Expressions and Conditions

The following sections explain how to use the WebLogic Process Integrator Expression Builder and expression components:

Workflow Expression Functionality

A workflow expression is an algebraic expression that defines a calculation that the WebLogic Process Integrator system performs at run time. You build workflow expressions using the WebLogic Process Integrator expression syntax, which is comparable to that of Structured Query Language (SQL). You also use XPath function syntax to extract values from XML documents. The WebLogic Process Integrator expression syntax makes it easy to manipulate strings, test for relationships and conditions, and perform arithmetic calculations involving workflow variables, database fields, and literal values (constants).

The result of an expression may be a string, a string representation of an integer, double, date/time value, or either of the Boolean (logical) values True and False. Expressions that yield a Boolean result are variously referred to as conditional expressions or conditions.

You can use workflow expressions, as described in the following sections.

Generate a String That Uniquely Identifies a Workflow Instance

Consider a workflow named "Registration of Invoice," concerned with the process of registering invoices. Instances of the workflow can be uniquely identified by appending the invoice number and date to this workflow name. The following expression yields a string that, when appended to the workflow name, provides an informative description of the workflow instance:

"#" + :'Invoice #' + ", dated " + :'Invoice Date'

where 'Invoice #' and 'Invoice Date' are the names of workflow fields.

This expression might yield the following workflow instance name:

"Registration of Invoice # 12345, dated May 16, 2001"

Determine Whether a Particular Event Should Trigger a Workflow

Consider a customer credit review workflow that should be initiated if the current balance due exceeds 75 percent of the customer's credit limit. The workflow is triggered by the arrival of an XML document indicating that a customer record in the underlying Accounts Receivable application has changed.

If the XML document "customer" contains elements called balance_due and credit_limit_amount, the expression required to detect this condition in the XML document is:

ToInteger(XPath("/customer/balance_due/text()")) > ToInteger(XPath("/customer/_credit_limit_amount/text()")) * .75

Using the Expression Builder

The Properties dialog boxes for workflow components have an Expression Builder button, shown in the following figure. You click the button to display the Expression Builder dialog box.

Figure 6-1 Expression Builder Button

If the expression is valid, the message "Expression is valid" appears in the Expression Builder dialog box; otherwise, an error message is presented in a dialog box. Note that validation does not check the validity of workflow variable referenced by the expression, nor does it check for the correct number of parameters being passed to a function, nor does it attempt to do type checking. 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.

Using Expression Components

Expressions are made up of functions, operators, literals, and variables.

Functions

WebLogic Process Integrator provides the following functions, which can be used by the workflow developer to construct conditions.

Abs

Returns the absolute value of the expression.

Abs(expression)

expression is a workflow expression for which the absolute value is to be calculated.

CurrentUser

Returns the ID of the user currently executing a task.

CurrentUser

Date

Returns current system date.

Date()

DateAdd

Performs date arithmetic.

DateAdd(date, interval, number [, buscal])

date is the base date.

The interval is not case sensitive except for "m" and "M".

number is the number of units to add (or subtract).

buscal 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.

DateToString

Converts a date to a string.

dateToString(date, format)

date is the date to be converted to the string value.

Note: Format is case sensitive.

The following separator characters are valid:

For example, given the following date and time: October 18, 2000, 2:30 pm, 35.370 seconds, the format result can be entered as follows:

DateToString(Date(), "yyyy-MM-dd HH:mm:ss.SSS") resulting in 2000-10-18 14:30:35.370

DateToString(Date(), "yyyy/MM-DD hh:mm:ss.SSS") resulting in 2000/10-292 02:30:35.370

StringLen

Provides the string length.

stringlen(string)

string is the string for which a length will be provided.

StringToDate

Converts a string to a date.

stringToDate(string, format)

string is the string to be converted to the date value.

format is a string specifying the format of the string.

SubString

Extracts a substring from a string.

SubString(string, 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.

TaskAttribute

Provides the task attribute.

TaskAttribute(attribute [,taskname])

attribute is the task attribute.

ToInteger

Converts a string value to an integer.

ToInteger(expression)

expression is the string (enclosed in double quotes) to be converted to integer.

ToString

Converts any data type value to a string.

ToString(expression)

expression is the integer to be converted to string.

WorkflowAttribute

Provides the workflow attribute.

attribute is the workflow attribute.

WorkflowVariable

Returns the value of a workflow variable for a particular workflow instance.

workflowVariable(instanceid, variable)

instanceid is the workflow instance ID.

variable is the workflow variable.

XPath

XPath(xpathstring, xmldocument)

xpathstring is the XPath expression

xmldocument is the name of the variable that contains the XML document on which the expression is evaluated. This parameter can either be of XML type or string type. This parameter is optional. If it is not specified, the XML document is assumed to be the incoming XML event.

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 subtrees, selecting nodes by attribute value and so on from an XML document. Consider the XML document in the following listing:

Listing 6-1 Common Uses of XPath

<?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")

Date Function Format

To specify the date format, use a time pattern string to describe dates and times. For example, the following time pattern string:

"yyyy.MM.dd G 'at' hh:mm:ss z"

results in the following formatting:

2000.07.31 AD at 13:10:35 PDT

This section describes pattern letters, provides formatting guidelines, and shows examples.

Pattern Letter Definitions

In this pattern, all ASCII letters are reserved as pattern letters, which are defined as the following.

Listing 6 Pattern Letter Definitions

Symbol   Meaning               Presentation     Example

------   -------               ------------     -------

 G        era designator        (Text)           AD

 y        year                  (Number)         1996

 M        month in year         (Text & Number)  July & 07

 d        day in month          (Number)         10

 h        hour in am/pm (1~12)  (Number)         12

 H        hour in day (0~23)    (Number)         0

 m        minute in hour        (Number)         30

 s        second in minute      (Number)         55

 S        millisecond           (Number)         978

 E        day in week           (Text)           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          (Text)           PM

 k        hour in day (1~24)    (Number)         24

 K        hour in am/pm (0~11)  (Number)         0

 z        time zone             (Text)           Pacific Standard Time

 '       escape for text

 ''      single quote                              '

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

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

Operators

Logical operators AND, OR, XOR, and NOT are valid only when the Expression Builder is constructing a logical condition (for example, a conditional action).

Literals

Variables

An expression can contain references to any workflow variable defined in the associated workflow and to any system-defined variable.

A workflow variable reference can use any one of the following syntaxes:

It is better to use the $ notation for consistency with the XPath function.