Oracle® Fusion Middleware Modeling and Implementation Guide for Oracle Business Process Management 11g Release 1 (11.1.1.7) Part Number E15176-10 |
|
|
PDF · Mobi · ePub |
This chapter describes how to write expressions and conditions for the BPMN elements that require them. Oracle BPM provides you with two different types of expressions editors that adjust to requirements of different users. This chapter describes the expression language used by each of these expression builders and the operations you can use in the expressions you write.
This chapter includes the following sections:
Section 24.2, "Writing Conditions in Conditional Sequence Flows"
Section 24.6, "Writing Conditions in Loop and Multi-Instance Markers in Subprocesses"
Section 24.7, "Writing Expressions and Conditions Using the Simple Expression Builder"
Section 24.8, "Simple Expression Builder Supported Operators"
Section 24.9, "Simple Expression Builder Supported Functions"
Section 24.10, "Writing Expressions Using the XPath Expression Builder"
Some BPM elements require you to write a condition or an expression that defines their behavior. For example, you might want to control the flow of your process using a conditional sequence flow that ensures that all expenses above 500 dollars are approved by a manager.
Oracle BPM provides you two ways of writing these expressions and conditions:
Using the Simple Expression Builder
Using the XPATH expression builder
The Simple Expression Builder uses dot notation and its syntax is very similar to Java. The XPATH Expression Builder uses standard XPATH language.
After writing an expression in simple expression language you can convert it to XPath and vice versa. When you convert an expression from one language to another, the expression editor removes any operators and parenthesis that do not affect the meaning of the expression.
Oracle BPM uses expressions to configure the following BPMN elements:
Conditional Sequence Flows
Complex Gateways
Timer Events
Data Associations
Loop Markers
Multi-Instance Markers
User Task Advanced Properties
The results of the expression vary according to the type of element you are configuring. Table 24-1 describes the expression required by each of the BPM elements.
Table 24-1 Expression Types
BPMN Element | Expression Type |
---|---|
Conditional Sequence Flow |
Condition that when evaluated results in a boolean value. |
Complex Gateway |
Condition that when evaluated results in a boolean value. |
Timer Event |
Time Date: expression that when evaluated results in a DateTime value. Cycle: expression that when evaluated results in an Interval value. |
Data Associations |
Expression that when evaluated results in a value of the same type as the argument in the data association. |
User Task Advanced Properties |
Expression that when evaluated results in a String value. |
Loop Marker |
Condition that when evaluated results in a boolean value. |
Multi-Instance Marker |
Loop Cardinality: expression that when evaluated results in an Int value. Completion Condition: Condition that when evaluated results in a boolean value. |
The configuration dialogs of the BPM elements that support expressions contain an embedded expression editor and a button to launch the expression builder. The latter is more suitable when you are working with long expressions. Both expression builders enable you to browse the available variables. The XPATH expression builder also enables you to browse the available functions.
To implement a conditional sequence flow you must provide a condition. When the token arrives to the conditional sequence flow, the BPMN Server Engine evaluates the condition in the conditional sequence flow to determine which sequence flow the token should follow.
Generally the condition is based on the values of the project and process data object, but this is not a requirement. The condition must result in a boolean value when the compiler evaluates it. If you write a condition that does not result in a boolean value, then the Simple Expression Builder prompts an error.
You must define an expression to implement a conditional sequence flow.
To implement a conditional sequence flow:
Right-click the conditional sequence flow.
Select Properties.
Click the Implementation tab.
From the Type List, select Condition.
In the Expression section, select the type of expression builder to use to write your condition.
If your condition is simple, then you can write it in the provided text area.
If you are working with complex conditions, then you can launch the expression builder by clicking the Launch Expression Builder button next to the text area.
Click OK.
To implement a complex gateway you must provide a condition that specifies when the gateway releases the tokens that arrive to it. Each time a new token arrives to the complex gateway the BPMN Service Engine evaluates this condition. If the condition evaluates to true, then the complex gateway releases all the tokens that arrived until that moment.
Generally the condition is based on the number of tokens that arrived to the complex gateway. For example you might want the gateway to release the tokens after two tokens arrive to the merge gateway.
Example 24-1 shows a condition that configures the gateway to release the tokens that arrived to it after two tokens arrive to the merge gateway.
You must define an expression to implement a gateway.
To implement a complex gateway:
Right-click the conditional complex gateway.
Select Properties.
Click the Implementation tab.
In the Expression section, select the type of expression builder to use to write your condition.
If your condition is simple, then you can write it in the provided text area.
If you are working with complex conditions, then you can launch the expression builder by clicking the Launch Expression Builder button next to the text area.
Click OK.
To implement a timer event you can choose to specify a date or an interval, or to write an expression that calculates the date or the interval.
Generally you use expressions in those cases where the date or the interval are not fixed.
The following examples show expressions that you can use in a timer event to express a date:
'now' + '30m'
deadline - '1day'
arrivalDate.dateTime + '1h'
The following examples show expressions that you can use in a timer event to express an interval:
waitToRetry.interval()
period(deadline)
You can use an expression to calculate a date or an interval in the implementation of a timer event.
To use an expression in a timer event:
Right-click the timer event.
Select Properties.
Click the Implementation tab.
Select Use Expression.
In the Expression section, select the type of expression builder to use to write your condition.
If your expression is simple, then you can write it in the provided text area.
If you are working with complex expressions, then you can launch the expression builder by clicking the Launch Expression Builder button next to the text area. The Expression Builder where you can write the expression appears.
Click OK.
You can use expressions in data associations to modify the input and output values before associating them with the activity implementation arguments.
Generally you use expressions when there is a mismatch between the data objects and the activity implementation arguments. The following examples describe situations where you can use expressions in a data association:
A mismatch between the value of the data object and the argument the service requires.
For example, the service your activity invokes uses a different product ID than the one you use in the process. In this case you can use an expression to adapt the content of the product ID data object to the value your services require.
A mismatch between the data type of the data object and the data type of the argument the service requires.
For example, the service your activity invokes uses a String to store the state of the order and your service requires you to specify the state of the order with an Int value. In this case you use an expression that calculates the Int value that corresponds to the state the String specifies.
You can use expressions in data associations to modify the values of the arguments or data objects before mapping them.
To use an expression in a data association:
Right-click the activity whose data association you want to modify.
Select Properties.
Click the Implementation tab.
In the Data Associations section, select Use Associations.
From the Type list select the type of data association.
The type of expression you can use depends on the type of data association you select.
Click the Edit button next to the Type list.
The Data Associations dialog appears.
Locate the input or output argument you want to modify using an expression.
If your expression is simple, then you can write it in the provided text area.
If you are working with complex expressions, then you can launch the expression builder by clicking the Expression Builder button next to the input or output text area. The Expression Builder where you can write the expression appears.
Click OK.
You can configure subprocesses to run multiple times using loop and multi-instance markers.
To configure loop and multi-instance makers you must define expressions and conditions that specify how to repeat the subprocess.
Loop Markers
Loop markers enable you to run a subprocess multiple times based on condition. You can configure the loop marker to evaluate the condition before or after running the subprocess. You can also configure the loop marker to stop after a certain number of repetitions.
To configure a loop maker you must write a Loop Condition that determines if the BPMN Service Engine must continue to repeat the subprocess.
Multi-Instance Markers
Multi-Instance markers enable you to run a subprocess for each of the elements on a set of data. When the BPMN Service Engine runs a subprocess with a multi-instance loop marker it creates a set of instances, one for each element on the set of data. You can configure the multi-instance marker to process these instances in parallel or sequentially.
The following fields in a multi-instance loop marker require you to write an expression:
Loop Cardinality
This expression defines the number of tokens to create in the subprocess.
Completion Condition
This expression determines when to stop repeating the subprocess. The BPM Service Engine evaluates this condition every time a token completes the subprocess. If the condition evaluates to true, it considers the subprocess completed and the instance moves to the next flow object in the process.
You can configure a loop marker to run a subprocess multiple times.
To configure loop markers:
Right-click the subprocess.
Select Properties.
Click the Loop Characteristics tab.
Select Loop.
Specify the Loop Condition:
Select the expression language.
Possible options are Simple or XPath.
In the text area below, write the condition that drives the loop.
Optionally you can write the condition using the Expression Builder. To launch the Expression Builder click the Expression Builder button next to the text area.
Optionally, you can specify a maximum number of times for the loop to run:
Select Loop Maximum.
Specify a number.
Select before to evaluate the condition before running the flow object, or deselect it to evaluate the condition after running the flow object.
Click OK.
You can configure a multi-instance marker to run subprocess multiple times based on a set of data.
To configure multi-instance markers:
Right-click the subprocess.
Select Properties.
Click the Loop Characteristics tab.
Select MultiInstance.
Specify the Loop Cardinality:
Select the expression language.
Possible options are Simple or XPath.
In the text area below, write the specifies the loop cardinality.
Optionally you can write the condition using the Expression Builder. To launch the Expression Builder click the Expression Builder button next to the text area.
Optionally, you can specify the Completion Condition:
Select the expression language.
Possible options are Simple or XPath.
In the text area below, write the condition that determines if the loop is completed.
Optionally you can write the condition using the Expression Builder. To launch the Expression Builder click the Expression Builder button next to the text area.
Click the Browse button next to the Loop Data Output field, to specify the data output.
You can select a data object or an attribute in a complex data object to pass to the subprocess. Generally the selected data object is a collection of items.
Click the Browse button next to the Loop Data Input field, to specify the data input.
Select a data object or an attribute in a complex data object to assign the result of the subprocess.
Optionally, check the Is Sequential check box to specify that the each token must complete the subprocess before the next token starts to run the subprocess.
Click OK.
The Simple Expression Builder contains a text area for you to type the expression and a list of variables that you can use.
The Simple Expression Builder supports the following features:
Syntax Highlighting
The Simple Expression Builder highlights the syntax in your expressions to make them easier to read and understand. It uses different colors for the different data type values.
Automatic Code Completion
If you wait a few seconds after you type the dot to invoke a method, then the Simple Expression Builder shows a list with the available functions that you can invoke over that data object. If you want the Simple Expression Builder to complete the expression for you, then you can press Ctrl + Space
.
On-the-fly Error Checking
The Simple Expression Builder checks the expressions as you write. It underlines with a red waved line those expressions that do not compile. To find out the cause of the error place the cursor over the red wavy line and wait for a tooltip with the error description to appear.
Figure 24-1 show the Simple Expression Builder dialog.
You can use a data objects in your expressions to perform calculations based on them.
To use a data object in an expression:
Open the Simple Expression Builder.
Place the cursor where you want to insert the data object.
From the variables section, select a data object.
Click Insert Into Expression.
The selected data object appears in the Expression text area.
To use a function in an expression, you can select the expression from the expression list in the simple expression builder, or you can type the function name in the Expression text area. If you write part of the name and press Crtl+Space
, then the expression builder completes the name of the function.
To use a function in an expression using the simple expression builder:
Open the Simple Expression Builder.
Place the cursor where you want to insert the function.
From the Functions section, select a type of function.
From the Functions list, select a function.
The Description field shows a description of the function.
Click Insert Into Expression.
The selected function appears in the Expression text area.
The Simple Expression Builder enables you to create expressions using the following operator types:
Arithmetic Operators
Unary Operators
Equality and Relational Operators
Conditional Operators
You can use these operators to write expressions and conditions to drive your process flow. Generally these expressions perform their calculations based on the data objects in your process. You can write expressions and conditions using the value of the data objects, but you cannot modify their value.
The following examples of expressions use operators:
totalAmount - discount
deadlineExpired and orderStatus !=complete
activationCount > 3
unitsSold <= 1200
'now' + '2m'
deadline - '1h'
not formComplete
Table 24-1, Table 24-2, Table 24-3, Table 24-4 and Table 24-5 describe the supported operators in the Simple Expression Builder.
Table 24-2 Arithmetic Operators
Operator | Name | Description |
---|---|---|
+ |
Addition |
Adds numeric data types. Concatenates Strings. Add an interval value to a DateTime value. |
- |
Subtraction |
Subtracts numeric data types. Subtracts an interval value from a DateTime value. |
* |
Multiplication |
Multiplies numeric data types. |
/ |
Division |
Divides numeric data types. |
rem |
Remainder |
Calculates the remainder of a division in which the divisor does not exactly divide the dividend. |
( ) |
Precedence |
Indicates the order of evaluation of an arithmetic expression. |
Table 24-3 Unary Operators
Operator | Name | Description |
---|---|---|
+ |
Plus |
Has no effect on the value of the numeric operand. Use it to indicate explicitly that a certain value is positive. |
- |
Minus |
Negates an arithmetic expression. Inverts the sign of a number. |
not |
Not |
Logical complement operator. Negates the value of a boolean expression. |
Table 24-4 Equality and Relational Operators
Operator | Name | Description |
---|---|---|
= |
Equal |
Returns true if the first operand equals the second operand. |
!= |
Not Equal |
Returns true if the first operand is not equal to the second operand. |
> |
Greater Than |
Returns true if the first operand is greater than the second operand. |
>= |
Greater Than or Equal to |
Returns true if the first operand is greater than or equal to the second operand. |
< |
Less Than |
Returns true if the first operand is less than the second operand. |
<= |
Less Than or Equal to |
Returns true if the first operand is less than or equal to the second operand. |
Table 24-5 Conditional Operators
Operator | Name | Description |
---|---|---|
and |
Conditional And |
Returns true if both operands evaluate to true. |
or |
Conditional Or |
Returns true if one operand evaluates to true. |
The precedence of the operators indicates the order in which the compiler evaluates them. You can change the precedence of the operators in an expression by using parenthesis.
The precedence of the operators in the Simple Expression Builder is:
Unary Plus and Unary Minus
Multiplication, Division, Remainder
Addition and Subtraction
Less than, Greater Than, Less Than or Equal to, Greater Than or Equal to
Equal, Not Equal
Not
Conditional And
Conditional Or
The Simple Expression Builder supports functions that you can use to calculate and manipulate your expressions and conditions.
The following sections describe the functions the Simple Expression Builder supports:
These functions enable you to manipulate String variables and literals, and perform calculations based on them.
Returns the number of characters in this String.
Signature:
Int length(String stringToMeasure)
Arguments:
-
Examples:
name.length()
length(name)
name.length
Concatenates one or more Strings.
Examples:
name + " " + lastName
"Oracle " + "BPM"
Returns true if the String contains the specified String.
Signature:
Bool contains(String mainString, String subString)
Arguments:
subString
- The String to find.
Examples:
productName.contains("book")
contains(productName, "book")
These functions enable you to perform calculations using numeric data types. The available numeric data types are Real, Decimal, and Int.
Returns the largest Int value that is smaller than the numeric value used for invoking this function. You can use this function with Real and Decimal data types.
Signature:
Int floor(Real number)
Int floor(Decimal number)
Arguments:
-
Examples:
number.floor()
floor(number)
number.floor
floor(totalAmount/3)
temperature.floor()
Returns the smallest Int value that is greater than the numeric value used for invoking this function. You can use this function with Real and Decimal data types.
Signature:
Int ceil(Real number)
Int ceil(Decimal number)
Arguments:
-
Examples:
number.ceil()
ceil(number)
number.ceil
Returns the closest Int value to this number. If there are two Int values that are equally close, then it returns the greater one. You can use this function with Real and Decimal data types.
Signature:
Int round(Real number)
Int round(Decimal number)
Arguments:
-
Examples:
number.round()
round(number)
number.round
These functions enable you to manipulate time variables and literals, and perform calculations based on them. The available time data types are DateTime and Interval.
Special notation for the system current date and time.
Examples:
setReceivedDate('now'
)
Adds an interval to a DateTime variable or value.
Examples:
today + '1d3h'
now + 3d
vacationStartingDate + '1M'
Subtracts an interval to a DateTime variable or value.
Examples:
today - '2d3h25m'
now - age
expirationDate - '7d'
Returns the year of this DateTime variable.
Signature:
Int year(DateTime date)
Arguments:
-
Examples:
today.year()
year(today)
today.year
Returns the month of this DateTime variable.
Signature:
Int month(DateTime date)
Arguments:
-
Examples:
today.month()
month(today)
today.month
Returns the day of this DateTime variable.
Signature:
Int day(DateTime date)
Arguments:
-
Examples:
today.day()
day(today)
today.day
Returns the hour of this DateTime variable.
Signature:
Int hours(DateTime date)
Arguments:
-
Examples:
today.hours()
hours(today)
today.hours
Returns the minutes of this DateTime variable.
Signature:
Int minutes(DateTime date)
Arguments:
-
Examples:
today.minutes()
minutes(today)
today.minutes
Returns the seconds of this DateTime variable.
Signature:
Int seconds(DateTime date)
Arguments:
-
Examples:
today.seconds()
seconds(today)
today.seconds
Oracle BPM enables you to write expressions using SOA XPath Expression Builder. This expression builder supports standard XPath language.
The XPath Expression Builder displays a list of the available variables that you can use in your expression. It also displays a list with the functions you can use in your expressions. When you select a function you can preview its syntax and description before adding it to your expression.
For more information about the functions supported for XPath see "Appendix B XPath Extension Functions" in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Additionally Oracle BPM supports a group of BPM Extension Functions.
Figure 24-2 shows XPath Expression Builder.
You can add variables to an XPath expression to perform calculations based on them.
To add a variable to an XPath expression:
Launch the XPath Expression Builder.
Place the cursor where you want to insert the variable.
From the variables list, select a variable.
Click Insert Into Expression.
The selected variable appears in the expression text area.
You can invoke a function in an XPath expression. The XPath Expression Builder enables you to brow a list of functions grouped by functionality.
To use a function in an XPath expression:
Launch the XPath Expression Builder.
Place the cursor where you want to insert the expression.
From the Functions list select a function category.
The list of available functions for the selected category appears below the Function list.
From the list of available functions, select a function.
Click Insert Into Expression.
The selected function appears in the expression text area.
Some service operations may require or return arguments of type array. These arrays can be collections simple types or complex types.
To provide a parameter of type array to a service operation, you can:
Invoke an operation that returns an array
Define an array using array literals
For more information about defining array literals, see Section 24.12.4, "Using Array Literals".
Generally when a process operation returns an argument of type array you assign one of the elements of the array or an attribute of one of the elements to a data object using data association. For more information about data associations, see Section 5.13.1, "Introduction to the Data Association Editor".
Example 24-2 shows an expression that accesses an element of an array. In this example the name of the array is persons and the element to access is the third element in the array.
Note that The index of the first element in the array is 1. For example to access the first element in the persons array you must write the following expression: persons[1]
Simple expression language also enables you to access the attribute of the elements within the array. For example you could invoke a service operation that returns an array of persons and access the name attribute of the first element in the array to a process data object, using data associations.
Example 24-3 shows an expression that accesses an attribute of an element of an array. In this example the name of the array is persons, the element to access is the third element in the array and the attribute to access is the name of the person
Simple expression language enables you to obtain the length of an array to use it in your process logic. This is typical when defining the loop cardinality of multi-instance markers. For more information about multi-instance markers, see Section 24.6, "Writing Conditions in Loop and Multi-Instance Markers in Subprocesses".
To obtain the length of an array you must invoke the length function.
Example 24-3 shows an expression that obtains the length of an array. In this example the name of the array is persons. Note that even if the example uses parentheses after the function name but, you can omit them because this function does not require any parameters.
Literals enable you to express a certain value. You can use literals to assign a value to data object or to pass a parameter to a method you are invoking. To assign a value to a data object you can use data associations or a script task.
Simple expression language supports the following types of literals:
String literals
Time literals
Interval literals
Array literals
You can assign a value to data object of type String using literals. You can also use String literals to provide a parameter of type String to a method.
To define a String literal you must write a word or a set of words enclosed by double quotes. A String can also contain numbers.
The following list shows examples of String literals:
"Wednesday"
"marie@oracle.com"
"500 Oracle Parkway"
"+1.650.506.7000"
You can assign a value to a data object of type Time using literals. You can also use time literals to provide a parameter of type time to a method.
Time literals enable you to define a date using different levels of precision.
The following list uses an example date to show the different time literals that you can use to specify a variable of type Time:
'13:30'
'13:30:23'
'13:30:23.001023'
'13:30:23.001023Z
'
'13:30:23.001023-05'
'13:30:23.001023-3:30'
'1979-02-19'
'1979-02-19 13:30'
'1979-02-19 13:30:23'
'1979-02-19 13:30:23.001023'
'1979-02-19 13:30:23.001023Z'
'1979-02-19 13:30:23.001023-05'
'1979-02-19 13:30:23.001023-3:30'
'1979-02-19T13:30'
'1979-02-19T13:30:23'
'1979-02-19T13:30:23.001023'
'1979-02-19T13:30:23.001023Z'
'1979-02-19T13:30:23.001023-05'
'1979-02-19T13:30:23.001023-3:30'
'19790219T'
'19790219T133023.001023-330'
You can assign a value to a data object of type Interval using literals. You can also use interval literals to provide a parameter of type interval to a method.
Interval literals enable you to define a date using different levels of precision.
To define a time literal you must use a combination of values and followed by their time unit enclosed by single quotes.
Table 24-6 shows the available time unit fields.
Table 24-6 Time Unit Suffixes
Time Unit Suffix | Description |
---|---|
Y |
Year |
M |
Month |
d or D |
Day |
h or H |
Hour |
m |
Minutes |
s or S |
Seconds |
x |
Microseconds |
Table 24-7 shows examples of interval literals:
You can assign a value to a data object of type Interval using literals. You can also use interval literals to provide a parameter of type interval to a method.
To define an array literal you must provide a list of values separated by comas and enclosed by brackets. You can also specify the values using literals or attributes from data objects.
The following list shows examples of array literals:
[ "One", "Two", "Three" ]
[ 1, 2, 3 ]
[ customer.firstName, customr.lastName ]
The BPM Extension Functions enable you to access the following elements using XPath:
Process and Project Data Objects
Arguments
Activity Instance Attributes
In XPath this is the only way of accessing the value of the described elements in your BPMN process.
You can also use the XPath extension functions that Oracle SOA Suite provides. For more information see appendix XPath Extension Functions, in Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Returns the value of a specific activity instance attribute. See Section 5.4, "Introduction to Activity Instance Attributes" for more information about the supported activity instance attributes.
Signature:
bpmn:getActivityInstanceAttribute(activityName, attributeName)
Arguments:
activity name
- The name of the activity that contains the activity instance attribute.
attributeName
- The name of the activity instance attribute for which you want to find out the value.
Examples:
bpmn:getActivityInstanceAttribute(userTask, priority)
bpmn:getActivityInstanceAttribute(userTask, title)
Returns the value of a specific input argument in a data association.
Signature:
bpmn:getDataInput(dataInputName)
Arguments:
dataInputName
- String that contains the name of the data input argument.
Examples:
Returns the value of a specific data object.
Signature:
bpmn:getDataObject(dataObjectName)
Arguments:
dataObjectName
- String that contains the name of the data object whose value you want to obtain.
Examples:
bpmn:getDataObject(discount)
bpmn:getDataObject(approveTermsOutcome)
Returns the value of a specific data output argument in a data association.
Signature:
pmn:getDataOutput(dataOutputName)
Arguments:
dataOutputName
- String that contains the name of the data output argument.
Examples:
Returns value of a specific activity instance attribute in a gateway. See Section 5.4, "Introduction to Activity Instance Attributes" for more information about the supported activity instance attributes for gateways.
Signature:
bpmn:getGatewayInstanceAttribute(gatewayName, attributeName)
Arguments:
gatewayName
- String that contains the name of the gateway that contains the attribute whose value you want to obtain.
attributeName
- String that contains the name of the attribute whose value you want to obtain.
Examples:
Returns value that corresponds to a process activity instance attribute. See Section 5.4, "Introduction to Activity Instance Attributes" for more information about the supported activity instance attributes.
Signature:
bpmn:getProcessInstanceAttribute(attributeName)
Arguments:
attributeName
- String that contains the name of the process instance attribute whose value you want to find out.
Examples:
bpmn:getProcessInstanceAttribute(owner)