Modeling and Implementation Guide for Oracle Business Process Management
View PDF

21 Writing Expressions

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 necessities of different users. This chapter describes the expression language used by each of these expression builders and the operations you can use in the expression you write.

This chapter includes the following sections:

21.1 Introduction to Expressions in Oracle BPM

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:

The simple expression builder uses dot notation and its syntax is very similar to Java. The XPATH expression builder uses standard XPATH language.

Oracle BPM uses expressions to configure the following BPMN elements:

The result of the expression vary according to the type of element you are configuring. Table 21-1 describes the expression required by each of the BPM elements.

Table 21-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.


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.

21.2 Writing Conditions in Conditional Sequence Flows

To implement a conditional sequence flow you must provide a condition. When the tokens 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 editor prompts an error.

21.2.1 How to Implement a Conditional Sequence Flow

To implement a conditional sequence flow:

  1. Right-click the conditional sequence flow.

  2. Select Properties.

  3. Click the Implementation tab.

  4. From the Type List, select Condition.

  5. In the Expression section, select the type of expression builder that you want to use to write your condition.

  6. 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. The Expression Builder where you can write the expression appears.

  7. Click OK.

21.3 Writing Expressions in Complex Gateways

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 21-1 shows a condition that configures the gateway to release the tokens that arrived to it after two tokens arrive to the merge gateway.

Example 21-1 Condition in a Complex Gateway

activationCount >= 2

21.3.1 How to Implement a Complex Gateway

To implement a complex gateway:

  1. Right-click the conditional complex gateway.

  2. Select Properties.

  3. Click the Implementation tab.

  4. In the Expression section, select the type of expression builder that you want to use to write your condition.

  5. 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. The Expression Builder where you can write the expression appears.

  6. Click OK.

21.4 Writing Expressions in Timer Events

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:

The following examples show expressions that you can use in a timer event to express an interval:

21.4.1 How to Use an Expression in a Timer Event

To use an expression in a timer event:

  1. Right-click the timer event.

  2. Select Properties.

  3. Click the Implementation tab.

  4. Select Use Expression.

  5. In the Expression section, select the type of expression builder that you want to use to write your condition.

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

  7. Click OK.

21.5 Writing Expressions in Data Associations

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:

21.5.1 How to Use an Expression in a Data Association

To use an expression in a data association:

  1. Right-click the activity whose data association you want to modify.

  2. Select Properties.

  3. Click the Implementation tab.

  4. In the Data Associations section, select Use Associations.

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

  6. Click the Edit button next to the Type list.

    The Data Associations dialog appears.

  7. Locate the input or output argument you want to modify using an expression.

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

  9. Click OK.

21.6 Writing Expressions and Conditions Using the Simple Expression Builder

The simple expression editor 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:

Figure 21-1 show the simple expression builder dialog.

Figure 21-1 Simple Expression Builder

This image shows the simple expression builder.

21.6.1 How to Use a Data Object in an Expression

To use a data object in an expression:

  1. Open the Simple Expression Builder.

  2. Place the cursor where you want to insert the data object.

  3. From the variables section, select a data object.

  4. Click Insert Into Expression.

    The selected data object appears in the Expression text area.

21.6.2 How to Use a Function in an Expression

To use a function in an expression, type the function name in the Expression text area. If you write part of the name and press Crtl+Space, the expression builder completes the name of the function.

21.7 Simple Expression Editor Supported Operators

The simple expression builder allows you to create expressions using the following operator types:

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:

Table 21-1, Table 21-2, Table 21-3, Table 21-4 and Table 21-5 describe the supported operator in the simple expression builder.

Table 21-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 and 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 21-3 Unary Operators

Operator Name Description

+


Plus

Has no effect in 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 21-4 Equality and Relational Operators

Operator Name Description

=


Equal

Returns true is the first operand is equal to the second operand.

!=

Not Equal

Returns true is 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 21-5 Conditional Operators

Operator Name Description

and

Conditional And

Returns true if both operands evaluate to true.

or

Conditional Or

Returns true if one of the operands evaluates to true.


21.7.1 Operators Precedence

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:

21.8 Simple Expression Editor Supported Functions

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:

21.8.1 String Functions

These functions enable you to manipulate String variables and literals, and perform calculations based on them.

21.8.1.1 length

Returns the number of characters in this String.

Signature:

Int length(String stringToMeasure)

Arguments:

-

Examples:

name.length()

length(name)

name.length

21.8.1.2 concatenation

Concatenates one or more Strings.

Examples:

name + " " + lastName

"Oracle " + "BPM"

21.8.1.3 contains

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

21.8.1.4 startsWith

Returns true if the String starts with the specified String.

Signature:

Bool startsWith(String mainString, String subString)

Arguments:

subString - The String to find at the beginning of the String.

Example:

productId.startsWith("ABC")

startsWith(productId, "ABC")

21.8.2 Numeric Functions

These functions enable you to perform calculations using numeric data types. The available numeric data types are Real, Decimal and Int.

21.8.2.1 floor

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

21.8.2.2 ceil

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

21.8.2.3 round

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

21.8.2.4 abs

Returns the absolute value of this number. You can use this function with Int, Real and Decimal data types.

Signature:

Int abs(Int number)

Real abs(Real number)

Decimal abs(Decimal number)

Arguments:

-

Examples:

number.abs()

abs(number)

number.abs

21.8.3 DateTime and Interval Functions

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.

21.8.3.1 now

Special notation for the system current date and time.

Examples:

setReceivedDate('now')

21.8.3.2 addition

Adds an interval to a DateTime variable or value.

Examples:

today + '1d3h'

now + 3d

vacationStartingDate + '1M'

21.8.3.3 subtraction

Subtracts and interval to a DateTime variable or value.

Examples:

today - '2d3h25m'

now - age

expirationDate - '7d'

21.8.3.4 year

Returns the year of this DateTime variable.

Signature:

Int year(DateTime date)

Arguments:

-

Examples:

today.year()

year(today)

today.year

21.8.3.5 month

Returns the month of this DateTime variable.

Signature:

Int month(DateTime date)

Arguments:

-

Examples:

today.month()

month(today)

today.month

21.8.3.6 day

Returns the day of this DateTime variable.

Signature:

Int day(DateTime date)

Arguments:

-

Examples:

today.day()

day(today)

today.day

21.8.3.7 hours

Returns the hour of this DateTime variable.

Signature:

Int hours(DateTime date)

Arguments:

-

Examples:

today.hours()

hours(today)

today.hours

21.8.3.8 minutes

Returns the minutes of this DateTime variable.

Signature:

Int minutes(DateTime date)

Arguments:

-

Examples:

today.minutes()

minutes(today)

today.minutes

21.8.3.9 seconds

Returns the seconds of this DateTime variable.

Signature:

Int seconds(DateTime date)

Arguments:

-

Examples:

today.seconds()

seconds(today)

today.seconds

21.8.3.10 timezone

Returns an Interval value that represents the offset from UTC.

Signature:

Interval timezone()

Arguments:

-

Examples:

'1995-02-03 23:30:23-3:30'.timezone()

timezone('1995-02-03 23:30:23-3:30')

'1995-02-03 23:30:23-3:30'.timezone

The result of this example is '-3h30m'.

21.9 Writing Expressions Using the XPath Expression Builder

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 21-2 shows XPath expression builder.

Figure 21-2 XPath Expression Builder

This image shows the XPath expression builder.

21.9.1 How to Add a Variable to an XPath Expression

To add a variable to an XPath expression:

  1. Launch the XPath Expression Builder.

  2. Place the cursor where you want to insert the variable.

  3. From the variables list, select a variable.

  4. Click Insert Into Expression.

    The selected variable appears in the expression text area.

21.9.2 How to Use a Function in an XPath Expression

To use a function in an XPath expression:

  1. Launch the XPath Expression Builder.

  2. Place the cursor where you want to insert the expression.

  3. From the Functions list select a function category.

    The list of available functions for the selected category appears below the Function list.

  4. From the list of available functions, select a function.

  5. Click Insert Into Expression.

    The selected function appears in the expression text area.

21.10 XPath BPM Extension Functions

The BPM Extension Functions enable you to access the following elements using XPath:

In XPath this is the only way of accessing the value of the described elements in your BPMN process.

21.10.1 getActivityInstanceAttribute

Returns the value of a specific predefined variable of an activity.

Signature:

bpmn:getActivityInstanceAttribute(activityName, attributeName)

Arguments:

activity name - The name of the activity that contains the predefined variable.

attributeName - The name of the predefined variable for which you want to find out the value.

Examples:

bpmn:getActivityInstanceAttribute(userTask, priority)

bpmn:getActivityInstanceAttribute(userTask, title)

21.10.2 getDataInput

Returns the value of a specific input.

Signature:

bpmn:getDataInput(dataInputName)

Arguments:

dataInputName - String that contains the name of the data input.

Examples:

21.10.3 getDataObject

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)

21.10.4 getDataOutput

Returns the value of a specific output.

Signature:

pmn:getDataOutput(dataOutputName)

Arguments:

dataOutputName - String that contains the name of the output.

Examples:

21.10.5 getGatewayInstanceAttribute

Returns value of a specific predefined variable name.

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:

21.10.6 getProcessInstanceAttribute

Returns value that corresponds to the submitted process attribute name.

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)