|
|
|
|
|
|
Using Expressions and Conditions
The following sections explain how to use the BEA WebLogic Process Integrator Expression Builder and expression components:
Workflow Expression Functionality
A workflow expression is an algebraic expression that defines a calculation that the BEA 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, 2000"
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 Expression Builder enables you to build expressions to be executed in BEA WebLogic Process Integrator at run time. Expressions are made up of functions, operators, literals, and variables. These expression components are discussed in Using Expression Components.
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 8-1 Expression Builder Button
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. For more information about plug-ins, see Working with Plug-Ins. To build an expression, either type it directly in the Expression field or use the functions, operators, literals, and variables options to build the expression. Selecting a component from the scrollable list to the right and clicking OK places the appropriate expression text in the Expression field. To create XPath expressions, you can either type them yourself, or you can use the XPath wizard. To open the XPath wizard, clickXPath Wizard. For details about using the wizard, see Creating XPath Expressions and Functions Using the XPath Wizard. 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. 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.
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.
Note: If a plug-in has been defined for functions that are part of expressions, you can select the new functions in addition to the following ones. For more information about plug-ins, see Working with Plug-Ins.
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.
interval is the unit of time to use. Possible values are listed in the following table.
Interval
Description
S
Seconds
m
Minutes
H
Hours
D
Days
W
Weeks
M
Months
BH
Business hours
BD
Business days
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.
format is a string specifying the format of the string. Possible values are listed in the following table.
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
EventAttribute
Obtain event properties from an incoming EventData object, such as a JMS message property.
EventAttribute(attribute)
attribute is the value to extract from the JMS properties.
For example, you can set JMS message property values using the Post XML Event dialog box, and then send the values to another workflow. The receiving workflow then retrieves the property information using the EventAttribute function in an event key expression.
For details about using the Post XML Event action, see Post XML Event. For details about defining an event key expression, see Defining an Event Key.
EventData
Retrieve the actual message content of the incoming JMS message. The content could be an XML document.
EventData()
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.
The following table identifies the construction for inserting system maintained workflow information into an expression.
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.
The following table identifies the construction for inserting system maintained workflow information into an expression.
Note: For a list of WebLogic Process Integrator error messages, see WebLogic Process Integrator Error Messages.
WorkflowVariable
Returns the value of a workflow variable for a particular workflow instance.
workflowVariable(instanceid, variable)
instanceid is the workflow instance ID. For details, see Start Workflow.
variable is the workflow variable.
XPath
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 and Functions Using the XPath Wizard.
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 8-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 8-2 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 8-3 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
The following table describes the available operator values.
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
Expressions can contain literal values, or constants. The following table describes the available 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.
Creating XPath Expressions and Functions Using the XPath Wizard
The XPath wizard provides a graphical interface that you can use to define, edit, and test XPath location expressions and XPath functions. Specifically, you can:
The following sections provide details about these tasks. You can also view information about using the XPath wizard by clicking the Show Information button in the wizard menu bar.
Creating XPath Location Expressions
Using the XPath wizard, you can create XPath location expressions that target:
To create an XPath location expression:
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.
After you retrieve the document using the XML Finder, the content of the document appears in the XPath wizard.
Figure 8-3 Sample XML Document
The Document Type field shows you the type of the currently open document, and the Document Location field shows you the path of the document. The wizard generates an XPath expression based on your selection, and displays it in the XPath Expression field. The Workspace provides a convenient area 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.
Viewing XPath Location Expressions
After you create your XPath location expressions and pin them to the Workspace, you can view them in the Workspace.
To view the XPath expressions you created, select the Workspace tab.
Figure 8-4 XPath Expressions in the Workspace
The Workspace shows you the following information:
In the Workspace, you can select an expression to test. For details, see Testing XPath Location Expressions.
Testing XPath Location Expressions
After you create your XPath location expressions, you can test them against a target XML document.
To test an XPath expression:
The Test area shows you the XML document with the target of the XPath expression highlighted.
Figure 8-5 Target of the XPath Expression
If you need to, you can modify the XPath expression by editing it in the XPath Expression field.
To test the expression again, click the Checkmark button. The new result of the expression is highlighted in the XML document.
Creating and Testing XPath Functions
The XPath function library provides functions that you can use to perform operations on the function arguments. Using the XPath wizard, you can create the following types of XPath functions:
To create an XPath function:
Alternatively, after you open the document for which you want to create the XPath function, you can select the Test tab and enter the entire XPath function in the XPath Expression field.
To test the function:
Figure 8-6 Result of an XPath Function
To view all the functions you create and pin during a Studio session, select the Workspace tab.
To return the function to the Expression Builder, click OK.
Using XPath Expressions and Functions From the Expression Builder
If you have an XPath location expression or function in the Expression Builder, you can pass it to the XPath wizard, and then use all the functions in the wizard to edit and test the expression or function.
To pass an expression or function from the Expression Builder to the XPath wizard:
The XPath expression or function is passed to the XPath wizard, and appears as the first item in the XPath Expression list in the Workspace.
|
|
|
|
|
|
Copyright © 2001 BEA Systems, Inc. All rights reserved.
|