Associate and Manipulate Data
After you define business types and objects to store your application’s data, you need to manage their use within flow elements.
Work with Expressions
Use expressions to evaluate and perform calculations on data stored in data objects, using standard operators and functions.
-
Human tasks: Use an expression to dynamically determine assignees
-
Conditional sequence flows: Use an expression to define its condition
-
Timer catch events: Use an expression to configure its time condition
-
Notification tasks: Use expressions to define dynamic e-mail notification
-
Sub-process tasks: Use an expression to conditionally call a subprocess
To create an expression, click the Expression Editor icon or Expressions Mode field during data association or from the flow element’s properties. The Expression Editor dialog box opens.
![Description of expression_editor.png follows Description of expression_editor.png follows](img/expression_editor.png)
Description of the illustration expression_editor.png
-
In most cases, the Expression Mode field is set to Simple, but for some flow elements, Plain Text and XML Literal options are listed. The field below it displays the expression as you configure it.
-
Create an expression by selecting the Data Objects or Operators tab, and selecting data objects and operators for your expression. Click Insert Into Expression to add a selected object or operator, or manually enter them.
-
In the expressions field, enter a . (period) after a data object to view options available for its type (trigger a completion action).
-
Click Validate, and results display in the expression field. The Error tab lists any errors found.
Using Functions
You can include the following functions in expressions, depending on data type. For example, you might use the string function to pass an integer value.
-
String — text
-
int — whole numbers
-
double — decimal numbers
-
Boolean — true or false
-
char — single characters
-
byte — eight bits, the smallest unit of data
-
short — small whole numbers
-
long — large whole numbers
-
float — large decimal numbers
-
Date — dates only
-
Time — times only
-
DateTime — dates and times
Function Guidelines and Examples
-
If the field name is inputDataObject, and the type must be string, enter string(inputDataObject).
-
A field with a data type of
int
can contain integers only, or whole numbers. A field of typedouble
orfloat
can contain decimal numbers. -
In data association, if the input type is
int
, the output type can be any numeric data type, such asint, double
, orfloat
. However, if the output type isint
, the input type must also beint
, or an error occurs. Depending on needs, use the round(), int(), floor(), or ceil() functions. -
If the field name is loanAppDataObject.form.income, for basic forms, change it to round(loanAppDataObject.form.income) or loanAppDataObject.form.income.round() and for web forms, change it to round(loanAppDataObject.income) or loanAppDataObject.income.round().
About Simple Expressions
Simple expressions are defined using a basic expression language and support. You can use these operators to write expressions and conditions to define your process flow. Generally these expressions perform their calculations based on the data objects in your business process. You can write expressions and conditions using the value of the data objects, but you can’t explicitly modify the value within the data object.
Here are some examples of expressions using operators:
-
totalAmount - discount
-
activationCount > 3
-
unitsSold <= 1200
Operator Precedence
Operator precedence defines the order in which the compiler evaluates operators. You can change operator precedence in an expression by using parentheses. In Process, the operator precedence is:
-
Addition, Subtraction
-
Multiplication, Division, Remainder
-
Plus, Minus
-
Less than, Greater than, Less than or equal to, Greater than or equal to
-
Equals, Not equals
-
Not
-
Conditional And
-
Conditional Or
Arithmetic Operators
Operator | Name | Description |
---|---|---|
+ | Addition | Adds numeric data types; also concatenates strings |
- | Subtraction | Subtracts numeric data types |
* | Multiplication | Multiplies numeric data types |
/ | Division | Divides numeric data types |
% | Remainder | Calculates the remainder of a division in which the divisor doesn't exactly divide the dividend |
() | Precedence | Indicates the order of evaluation of an arithmetic expression |
Unary Operators
Operator | Name | Description |
---|---|---|
+ | Plus | Has no effect on the value of the numeric operand. Use it to explicitly indicate that a certain value is positive. |
- | Minus | Negates an arithmetic expression. |
! | Not | Logical complement operator. Negates the value of a Boolean expression. |
Equality and Relational Operators
Operator | Name | Description |
---|---|---|
= or == | Equal to | Returns true if the first operand is equal to the second operand |
!= | Not equal to | Returns true if the first operand isn't 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 |
Conditional Operators
Operator | Name | Description |
---|---|---|
and | Conditional And | Returns true if both operands evaluate to true |
or | Conditional Or | Returns true if either operand evaluates to true |
String Operators
Operator | Description | Usage Expression | Usage Result |
---|---|---|---|
+ | String concatenation | “pine” + “apple” | “pineapple” |
== | Equals | “apples” == “apples” | true |
!= | Not equals | “apples” != “oranges” | true |
> | Greater than | “word” > “work” | false |
>= | Greater than or equals | “work” >= “work” | true |
< | Less than | “word” < “work” | true |
<= | Less than or equals | “work” <= “work” | true |
contains | Returns true if the first argument string contains the second argument string; otherwise returns false | “caramel”.contains(“ram”) | true |
endsWith | Returns true if the first argument string ends with the second argument string; otherwise returns false | “immutable”.endsWith(“table”) | true |
length | Returns the number of characters in a string | “house”.length() | 5 |
lowerCase | Returns a string with all the characters in the argument converted to lower-case representation | “Example”.lowerCase() | “example” |
startsWith | Returns true if the first argument string starts with the second argument string, otherwise returns false | “caramel”.startsWith(“car”) | true |
substring | Returns the substring of the first argument starting at the position specified in the second argument and continuing to the end of the string | “care”.substring(1) | “are” |
substring | Returns the substring of the first argument starting at the position specified in the second argument with length specified in the third argument | “care”.substring(0,3) | “car” |
upperCase | Returns a string with all the characters in the argument converted to upper-case representation | “Example”.upperCase() | EXAMPLE |
Integer Operators
Operator | Description | Usage Expression | Usage Result |
---|---|---|---|
+ | Addition | 2 + 8 | 10 |
- | Subtraction | 7 – 4 | 3 |
* | Multiplication | 3 * 4 | 12 |
/ | Division | 3 / 2 | 1.5 |
% | Remainder | 3 % 2 | 1 |
== | Equals | 12 == 13 | false |
!= | Not equals | 12 != 13 | true |
> | Greater than | 15 > 16 | false |
>= | Greater than or equals | 15 >= 15 | true |
< | Less than | 12 < 10 | false |
<= | Less than or equals | 12 <= 12 | true |
abs | Returns the absolute value of a number | - 6 | 6 |
Non-integer Operators
Operator | Description | Usage Expression | Usage Result |
---|---|---|---|
floor | Returns the largest (closest to positive infinity) number that isn't greater than the argument and is an integer | floor(5.60) | 5 |
ceil | Returns the smallest (closest to negative infinity) number that isn't less than the argument and is an integer | ceil(5.60) | 6 |
round | Returns the number that is closest to the argument and is an integer | round(5.60) | 6 |
Date and Time Operators
Operator | Description |
---|---|
+ | Addition (valid only when the second argument is a duration) |
- | Subtraction (valid only when the second argument is a duration) |
== | Equals |
!= | Not equals |
> | Greater than |
>= | Greater than or equals |
< | Less than |
<= | Less than or equals |
format | Returns the formatted string of date-time using the provided format picture |
year | Returns a number representing the year component of the date-time argument |
month | Returns a number representing the month component of the date-time argument |
day | Returns a number representing the day component of the date-time argument |
hours | Returns a number between 0 and 23, both inclusive, representing the hours component of the date-time argument |
minutes | Returns a number between 0 and 59, both inclusive, representing the minutes component of the date-time argument |
seconds | Returns a number between 0 and 59, both inclusive, representing the seconds component of the date-time argument |
timezone | Returns an interval value, representing the time offset from UTC |
Boolean Operators
Operator | Description | Usage Expression | Usage Result |
---|---|---|---|
== | Equals | true == true | true |
!= | Not equals | true != false | true |
and | Conditional — And | true and false | false |
or | Conditional — Or | true or false | true |
not | Logical complement operator, inverts the value of a Boolean expression. | not true | false |
Duration Operators
Operator | Description |
---|---|
== | Equals |
!= | Not equals |
> | Greater than |
>= | Greater than or equals |
< | Less than |
<= | Less than or equals |
Base64Binary Operators
Operator | Description |
---|---|
== | Equals |
!= | Not equals |
Array Operators
Operator | Description |
---|---|
[ ] | Access a particular element into the array |
== | Equals |
!= | Not equals |
length | Returns the number of elements contained within the array |
Other Operators
Operator | Description |
---|---|
== | Equals |
!= | Not equals |
Special Constants
Constants | Description |
---|---|
null | Null value |
true | Logical true |
false | Logical false |
‘now’ | Current dateTime |
Casting
In some cases, it could be desirable to bypass the type validation in order to assign types that aren't necessarily compatible. For example, you may want to assign an 'int' value to a 'string' one and in order to do that you can use the conversion operation like this:
<conversionTypeName> ( <valueToConvert> )
where the 'conversionTypeName' is the type you want to see as the value.
Here are some conversion examples:
-
string(myIntDO)
-
int(myStringDO)
-
duration(mystringDO)
Note:
You can only cast to primitive types, so the 'conversionTypeName' will only accept those that have a valid value.
Assigning two values that are incompatible will result in a runtime error.
Identity Service
Function | Description | Available | Usage Function Prototype | Usage Example |
---|---|---|---|---|
getManager | Returns a string containing the manager of the specific user | Process wide | IdentityService.getManager(<userName:string>): string | IdentityService.getManager("wfaulkner") |
getManager | Returns a string containing the manager of a certain user in the realm specified | Process wide | IdentityService.getManager(<userName: string>,<realm:string>): string | IdentityService.getManager("wfaulkner", "myRealm") |
Human Task
Function | Description | Available | Usage Function Prototype | Usage Example |
---|---|---|---|---|
getPerformer | Assignee Selection | HumanTask.getPerformer(): string | HumanTask.getPerformer() | |
getLastPerformer | Assignee Selection | HumanTask.getLastPerformer(): string | HumanTask.getLastPerformer() |
Form
Function | Description | Available | Usage Function Prototype | Usage Example |
---|---|---|---|---|
getWebform | Returns a base64 encoded value representing the PDF image of the specified webform data object | Process wide | Form.getWebform(<webFormDataObject:catalogObject>): base64 | Form.getWebform(myWebformDO) |
getWebform | Returns a base64 encoded value representing the image of the specified webform data object in the format passed as the second argument (valid values are "PDF" or "PNG") | Process wide | Form.getWebform(<webFormDataObject:catalogObject>,<format:string>): base64 | Form.getWebform(myWebformDO, "PNG") |
getWebform | Returns a base64 encoded value representing the image of the specified webform data object having the name determined in the third argument in the format passed as the second argument (valid values are "PDF" or "PNG") | Process wide | Form.getWebform(<webFormDataObject:catalogObject>,<format:string>,<webFormName:string>): base64 | Form.getWebform(myWebformDO, "PNG","MyWebformDO") |
Document Service
Function | Description | Available | Usage Function Prototype | Usage Example |
---|---|---|---|---|
getDocumentAssetProperty | Get some property for a specific document asset, which can be one of the following: Id, Type | Process wide | DocumentService.getDocumentAssetProperty(<propertyName:string>,<documentAssetName:string>): string | DocumentService.getDocumentAssetProperty("Id","myFolder") |
Get or Else
Function | Description | Available | Usage Function Prototype | Usage Example |
---|---|---|---|---|
boolean | Request an object property along with a backup value. The backup value is used if the first argument corresponds to a missing node or an uninitialized value. This function set is useful while dealing with an untrustworthy data source, where initialization isn’t guaranteed. | Process wide | GetOrElse.boolean(<expression:boolean>,<fallbackValue:boolean>): boolean | GetOrElse.boolean(myDO.boolAtt, true) |
string | Process wide | GetOrElse.string(<expression:string>,<fallbackValue:string>): string | GetOrElse.string(myDO.stringAtt, "User") | |
decimal | Process wide | GetOrElse.decimal(<expression:decimal>,<fallbackValue:decimal>): decimal | GetOrElse.decimal(myDO.decimalAtt, 25.9) | |
byte | Process wide | GetOrElse.byte(<expression:byte>,<fallbackValue:byte>): byte | GetOrElse.byte(myDO.byteAtt, byteVar) | |
short | Process wide | GetOrElse.short(<expression:short>,<fallbackValue:short>): short | GetOrElse.short(myDO.shortAtt, shortVar) | |
int | Process wide | GetOrElse.int(<expression:int>,<fallbackValue:int>): int | GetOrElse.int(myDO.intAtt, 12) | |
long | Process wide | GetOrElse.long(<expression:long>,<fallbackValue:long>): long | GetOrElse.long(myDO.longAtt, 1000) | |
double | Process wide | GetOrElse.double(<expression:double>,<fallbackValue:double>): double | GetOrElse.double(myDO.doubleAtt, 25.3d) | |
float | Process wide | GetOrElse.float(<expression:float>,<fallbackValue:float>): float | GetOrElse.float(myDO.floatAtt, floatVar) | |
binary | Process wide | GetOrElse.binary(<expression:base64Binary>,<fallbackValue:base64Binary>): base64Binary | GetOrElse.binary(myDO.binaryAtt, binaryVar) | |
integer | Process wide | GetOrElse.integer(<expression:integer>,<fallbackValue:integer>): integer | GetOrElse.integer(myDO.integerAtt, 12) | |
time | Process wide | GetOrElse.time(<expression:time>,<fallbackValue:time>): time | GetOrElse.time(myDO.timeAtt, '9:20') | |
date | Process wide | GetOrElse.date(<expression:date>,<fallbackValue:date>): date | GetOrElse.date(myDO.dateAtt, '1988/08/08') | |
dateTime | Process wide | GetOrElse.dateTime(<expression:dateTime>,<fallbackValue:dateTime>): dateTime | GetOrElse.dateTime(myDO.dateTimeAtt, '1988/08/08 9:20') | |
duration | Process wide | GetOrElse.duration(<expression:duration>,<fallbackValue:duration>): duration | GetOrElse.duration(myDO.durationAtt, '5s') |
Note:
The Get or Else function set is available only for regular data associations within a structured process. It isn’t available either for data transformations or dynamic processes.Append to Array
An array is a series or list of data elements of the same type. You can add a single data element to an array with the Append action available in the Data mapper.
Append is available in the Data Association editor for both structured and dynamic processes.
-
The target expression type must be always an array.
-
The source expression type must be of the same data type as the target array.
The only exception is when the source data type can be assigned to the target array. For example, you can append an integer to an array of type double since you can assign an integer to a double.
-
Both the source and target expressions have to be valid.
Suppose you have a list of colors: blue, green, and black in a form. Now you want to add another color red to the list. Let’s append “red” (string) to the list of colors (string of type array) in design time, validate and test the application, and finally check if the append action is successful in runtime.
You have successfully appended a string to an array in this example.
Filter Array Data Objects
While defining data associations between process components, you can selectively filter elements from a source array object and assign them to a target array.
- The target expression type is an array.
- The source expression type is an array. The base type of the source is assignable to the base type of the target (for example, integer to double assignments).
- Both the source and target expressions are valid.
To define a new filter:
- Click the Data Association icon and select Filter.
- Select the Create action in the resulting window and provide a suitable name for the filter, for example, MyStringFilter, and click Create again. A window to define the filter condition appears.
Note:
If a suitable filter already exists, you can select or edit it from the Create Filter window. - Based on the type of your array, define a filter condition using the available operators. For a simple array object (of the type integer, string, or double), an element named VALUE is present in the window, which represents each element of the source array.
- Drag and drop the VALUE element into the Condition field to define an expression. If needed, click the fx (Expression) icon and use the Expression editor. The following figure shows a filter condition defined for a string array:
Description of the illustration filter-condition.pngIn this case, only the elements of the source array of length 5 are assigned to the target array.
- For a complex array object, you can define a condition comprising all attributes it contains:
Description of the illustration filter-condition-complex.pngNote:
Currently, while defining a filter condition for a complex array object, you must type in each array element and its associated condition into the Condition field. Drag and drop functionality is supported only for a single object or element.
- Drag and drop the VALUE element into the Condition field to define an expression. If needed, click the fx (Expression) icon and use the Expression editor. The following figure shows a filter condition defined for a string array:
- Save the filter condition.
- To view or edit any filter defined within the process, click Actions in the Data Association editor.
- Finally, click Apply to save all data associations and filters.
In runtime, target arrays are populated according to the filter conditions you’ve defined.
Define Conditions for Data Associations
There may be a business scenario where you want a data association to execute in runtime only when a particular condition fulfills. Control the execution of data associations in runtime by adding conditions to them in the Data Association editor.
A data association that has been configured with conditional mapping executes in runtime only when the defined condition fulfills. Otherwise, it fails to execute. All other data associations that do not have conditional mapping defined execute normally in runtime.
Note that you can set conditions for data mapping in both structured and dynamic processes.
To define a new condition: