QPR ProcessAnalyzer Expressions

Expression and Evaluation Context

An expression is a representation of a piece of text to be evaluated that has a result. Result can be any of the supported object types or empty. An expression may consist of multiple expressions (sub-expressions).

Expression evaluation is always performed within some context. This context and its type defines which kind of functionalities are available. Current context is implicitly accessible in all the expressions. Whenever a function or property is called, functions and properties accessible in the current context are searched first. If function or property is not found in the current context, then more generic context is tried. Error is returned only if the requested functionality is not available in the current context or a generic context. Current context can always be accessed explicitly by using variable named: _ (underscore).

Expression Chaining and Hierarchies

Expressions can be chained together using . (dot) or : (colon) character between the expressions:

• Contextless chaining: When . character is used to chain expressions together, only the result of the latter evaluation will be returned.
• Hierarchical chaining: When : character is used to chain expressions together, only the result of the whole chained expression will consist of hierarchical arrays where all the values in the first expression will be bound to the arrays those values generated. If the second expression does not return an array, the result will be changed to be an array.

The second expression chained to the first one will be evaluated using the following rules:

• If the result of the first expression is not an array, the second expression will be evaluated with the result of the first expression as its context object.
• If the result of the first expression is an array, for every element in the array, the second expression will be evaluated with the array element as its context object. The result of the evaluation will be an array of evaluation results. One for each element in the array.
• If any of the second expression evaluations returns an array, the resulting object will be an array of arrays. If the first expression evaluation returns a typed array, the result will be hierarchic in a way that first level results are objects that contain the information about the actual object as well as the results generated by the second level expressions.

These rules apply also when chaining more than two expressions together. For example, it is possible to generate three level hierarchy with nodes of type: event log -> case -> event: EventLogById(1).Cases.Events or EventLogById(1):Cases:Events.

Examples:

[1,2].("" + _ + "*foo").([_+"bar", _+"bob"])
Returns:
[["1*foobar","1*foobob"], ["2*foobar","2*foobob"]]

[1,2].("" + _ + "*foo"):([_+"bar", _+"bob"])
Returns:
[HierarchicalArray("1*foo", ["1*foobar","1*foobob"]), HierarchicalArray("2*foo", ["2*foobar","2*foobob"])]

[1,2]:("" + _ + "*foo"):([_+"bar", _+"bob"])
Returns:
[
HierarchicalArray(1, [
  HierarchicalArray("1*foo", ["1*foobar","1*foobob"])
]), 
HierarchicalArray(2, [
  HierarchicalArray("2*foo", ["2*foobar","2*foobob"])
])
]

GetValueOfContext("bar", ["foo":1, "bar":2])
Returns:
[2]

• Hierarchical arrays: Whenever traversing 1-to-N cardinality relation in expression language that starts from a ProcessAnalyzer object (such as Case), a hierarchical array will be returned. Hierarchical array is an object which behaves just like a normal array except it stores also context/root/key/label object which usually represents the object from which the array originated from (e.g., the original case object when querying events of a case), or a key using which the actual value needs to be accessed by.

• Hierarchical objects: Arrays where at least one object in the array is itself an array is considered to be a hierarchical object. Also known as multi dimensional arrays or array of arrays. Hierarchical arrays are treated in similar way as normal arrays in hierarchical objects.

Leaf, Depth, Level

Leaf level consists of all the nodes which are at depth equal to the depth of the whole hierarchical object.

Examples:

Objects at leaf level for hierarchical object: [[[3, 4, 5], 6], [1, 2]] are: 
Level 5: 3, 4, 5

Objects at leaf level for hierarchical object: [[1, 2], [[3, 4, 5], 6]] are: 
Level 4: 1, 2, [3, 4, 5], 6

Depth of a hierarchical object is the number of arrays that need to be traversed before a leaf node is found when traversing using depth first search using always the first object in each traversed array. Depth of the hierarchical object is not necessarily the maximum depth that could be achieved when traversing from object root to leaves. See the example below:

Examples:

Depth of hierarchical object [[1, 2], [[3, 4, 5], 6]] is: 2

NOTE!: 
Depth of hierarchical object [[[3, 4, 5], 6], [1, 2]] is: 3

Level in hierarchical object consists of all the nodes that are at specific depth in object's internal array hierarchy. 0 is the level at the root of the object (consisting only of the object itself as single item). Levels increase when moving towards leaves.

Examples:

Objects levels in hierarchical object: [[[3, 4, 5], 6], [1, 2]] are: 
Level 0: [[[3, 4, 5], 6], [1, 2]]
Level 1: [[3, 4, 5], 6], [1, 2]
Level 2: [3, 4, 5], 6, 1, 2
Level 3: 3, 4, 5 (Leaf Level)

Objects at leaf level for hierarchical object: [[1, 2], [[3, 4, 5], 6]] are: 
Level 0: [[1, 2], [[3, 4, 5], 6]]
Level 1: [1, 2], [[3, 4, 5], 6]
Level 2: 1, 2, [3, 4, 5], 6 (= Leaf Level #29303#)
Level 3: 3, 4, 5

Scopes

Scope defines the region of a expression where a specific variable or function name-value binding is valid. In expressions, a variable or function is valid in the following scopes:

• Scope the variable or function was created.
• All the child scopes created from the scope in which the variable or function was created.

A new scope is created based on the previous one in the following cases:

• When starting to evaluate a expression.
• When recursing the chain of expressions and the type of the current calculation context object is not the same as the previously used one.
• When evaluating user defined function and its parameters.
• When evaluating KPI analysis dimensions.
• When evaluating KPI analysis column names in dynamic values.

User Defined Variables

Variables are properties originating from the current variable scope. Variables can be defined by user into the current scope using Let function. Variables defined in parent scope are available also in all the child scopes. Variables can't be used to override properties. Properties are always checked first before checking scope for variables. For example, you can't override Models property by specifying Models variable.

Aggregation Functions

When using aggregation functions (such as Count, Sum, ...) or functions that modify the contents of leaf arrays (OrderBy, Distinct, ...) on hierarchical objects, the operations will be performed by default separately for every array at level that equals to the depth of the object (leaf level) or some specific number of levels up from that.

There are following aggregation functions available: Average, Count, Min, Max and Sum.

Examples:

Count([[1, 2], [3, 4]])
Returns: [2, 2]

OrderByValue([[4, 3], [2, 1]])
Returns: [[3, 4], [1, 2]]

NOTE:
OrderByValue([[4, 3], [2, 1], [[6, 5]]])
Returns: [[3, 4], [1, 2], [[6, 5]]]

Type Independent Properties and Functions

Type Independent Property	Description
_
_empty
_remove
CalcId (string)
Models (Model*)	Models in the QPR ProcessAnalyzer server.
Now (DateTime)	Timestamp of representing the current date and time.
Null
Projects (Project*)	Projects in the QPR ProcessAnalyzer server.

Type Independent Function	Parameters	Description
Ceiling
Floor
Round
Array	object*: Any number of objects to be added into the created array. Objects are added in the same order as they are given.	Create a new array object. Equivalent of using [] expression. Returns the created array. Examples: Array() Returns: An empty array. Array(1) Returns: An array having one element which is 1. Array(1, 2, 3) Returns: An array having three elements which are 1, 2 and 3. Array(1, "Foo", DateTime(2017)) Returns: An array having three elements which are of different types. Objects are 1 (number), "Foo" (string) and a date time object representing year 2017.
DateTime	year (Integer) month: (Integer) day: (Integer) hour (Integer) minute (Integer) second (Integer) millisecond (Integer)	Creates a new date time object. Only the first (year) parameter is mandatory. Parameters: year month: Value between 1 and 12. 1 is the default. day: Starting from 1. 1 is the default. hour: 0 is the default. minute: 0 is the default. second: 0 is the default. millisecond: 0 is the default. Examples: DateTime(2017) Returns: A date time object for 1st January 2017 at 0:00:00. DateTime(2017, 5) Returns: A date time object for 5th January 2017 at 0:00:00. DateTime(2017, 5, 6, 13, 34, 56, 123) Returns: A date time object for 6th May 2017 at 13:34:56.123.
TimeSpan	days (Integer) hours (Integer) minutes (Integer) seconds (Integer) milliseconds (Integer)	Create a new time span object. Only the first (days) parameter is mandatory. Others are assumed to be zero. Examples: TimeSpan(1) Returns: Time span for the duration of 1 day. TimeSpan(12,3,4,5,6) Returns: Time span for the duration of 12 days, 3 hours, 4 minutes, 5 seconds and 6 milliseconds.
Box
Unbox
Catch	Expression to evaluate (Expression) Result if exception (Object)	Calculate given expression and if any exceptions are thrown during the evaluation of the expression, catch that exception and return given value. Note that this function does not catch any syntactical errors. Examples: Catch(1, 1234) Returns: 1 Catch(undefined, 1234) Returns: 1234 Catch([1,2].undefined, 1234) Returns: 1234 Catch(EventLogById(-1), 1234) Returns: 1234
Coalesce	Object to coalesce result If Null	Returns the second parameter only if the first parameter evaluates to null or empty. If given a hierarchical object, applies the function at the level that is equal to the leaf level. If the the given object is a hierarchical object, all its leaf level values are coalesced separately. Examples: Coalesce(0, 1) Returns: 0 Coalesce(null, 1) Coalesce(_empty, 1) Coalesce(_remove, 1) All return: 1 Coalesce([[null, 1], [null, null]], 3) Returns: [[3, 1], [3, 3]] Coalesce([[null, 1], 2], 3) Returns: [[3, 1], null] Coalesce([1, [null, 2], null], 3) Returns: [1, [null, 2], 3]
Def	Function name (String) Name of the variable to set (String) ... Function expression	Creates a new user defined function. The created function is valid only within the current scope and all its child scopes. The first parameter is the function name. Parameters starting from the second are the names of the parameters that the user gives when calling this function. The order of the names is the same as the order used when giving the parameters. Thus there can be any number of parameters defined for a function. The last parameter is the expression to evaluate when the function is called. Examples: Def("Inc", "a", a + 1); Inc(2); Returns: 3 Def("Add", "a", "b", a + b); [1, 2, 3].Add(_, 2); Returns: [3, 4, 5] Def("AddSelf", "b", _ + b); [1, 2, 3].AddSelf(2); Returns: [3, 4, 5] Def("Fib", "a", If(a < 2, 1, Fib(a - 1) + Fib(a - 2))); Fib(10); Returns: 89
Distinct	Array or hierarchical object	Modify given array by filtering out all repeated values leaving only distinct values in the input array into the result. If given a hierarchical object, applies the function at the level that is one level up from the leaf level. Examples: Distinct([1]) Returns: [1] Distinct([1, 1]) Returns: [1] Distinct([1, 1, 2, 2]) Returns: [1, 2] Distinct([1, 1, 2, 2, "a", DateTime(2017), DateTime(2017), "b", DateTime(2016), "a"]) Returns: [1, 2, "a", DateTime(2017), "b", DateTime(2016)]
EventLogById
ModelById
FindRepeats
Repeat
Flatten	Array or hierarchical object	Collects all the actual leaf values from given array, array of arrays or hierarchical object and returns them in a single array. If given a hierarchical object, this function collects actual leaf values instead of leaf level values. Elements in the returned array are in the same order they were found when traversing the input object using depth first search. Examples: Flatten(1) Returns: 1 Flatten([1, 2]) Returns: [1,2] Flatten([[[1, 2],[3, 4]],[[5, 6]]]) Returns: [1, 2, 3, 4, 5, 6] Flatten([[1, 2], 3]) Returns: [1, 2, 3] Flatten([[1,2,3,4], null, [5], [1, null]]) Returns: [1, 2, 3, 4, null, 5, 1, null]
For	propertyName initialValue condition iterationStep expression	Iterates given expression until given condition is met, and returns the results of the iterated expressions for every iteration as an array. Parameters: propertyName: Name of the property to use in the iteration. initialValue: Initial value for the iterated property. condition: Condition which returns true as long as the iteration should continue. iterationStep: Expression evaluated after every iteration. expression: Expression evaluated for every iteration. Examples: For("i", 0, i < 4, i + 1, i) Returns: [0, 1, 2, 3] For("x", 0, x < 3, x + 1, For("y", 0, y < 3, y + 1, StringJoin(",", [x, y])) Returns: [["0,0", "0,1", "0,2"], ["1,0", "1,1", "1,2"], ["2,0", "2,1", "2,2"]] For("i", 0, i < 4, i + 1, DateTime(2010 + i)) Returns: [DateTime(2010), DateTime(2011), DateTime(2012), DateTime(2013)] For("str", "a", str != "aaaaa", str + "a", str) Returns: ["a", "aa", "aaa", "aaaa"]
ForEach
GetAt	Index (Integer) Array	Returns element at given index from the beginning of the array of given array object. The first item index is zero. If given a hierarchical object, returns the element at given index of the root level array. Throws a calculation exception if the given index does not exist in given object. Throws a calculation exception if given object is not an array. Examples: GetAt(0, [1,2,3]) Returns: 1 GetAt(1, [[1, 2], [3, 4]]) Returns: [3, 4] GetAt(1, [[[5, 6]], [[1, 2], [3, 4]]]) Returns: [[1, 2], [3, 4]] GetAt(1, GetAt(1, [[[5, 6]], [[1, 2], [3, 4]]])) Returns: [3, 4]
GetAtReverse
GetValueOfContext
If	condition trueExpression falseExpression	Returns the value of the second parameter if the first parameter is true. Otherwise returns the value of the third parameter. Always evaluates only either the second or the third parameter, never both ("short circuiting"). Parameters: condition: Boolean expression to test. trueExpression: Expression to evaluate if the condition evaluates to true. falseExpression: Expression to evaluate if the condition evaluates to false. Examples: If(Now.Second % 2 == 0, "Even second", "Odd second") Returns: "Event second" or "Odd second" depending on the time of the evaluation. For("i", 0, i < 10, i + 1, i).If(_ % 2 == 0, _, _remove) Returns: [0, 2, 4, 6, 8] NOTE: Is equivalent to: For("i", 0, i < 10, i + 1, i).Where(_ % 2 == 0)
In
Include
IsNull
Let	Variable name Variable value	Set a value for a named variable. Can also be used to set several variable values at once. The variable binding is valid only within the current scope and all its child scopes. Parameters: variable name*: Name of the variable to set. variable value*: New value to set for the given variable. There can be any number of variable name and variable value pairs as long as the last parameter is the expression to evaluate.
OrderBy		1. Orders given array by the value of given expression. 1.1. Supports all atomic (=not collection) primitive value types. 2. Parameters: 2.1. array: Array to sort. 2,2, orderExpression: Expression evaluated in the context of each array item whose value determines the order of that item. 3. Returns the given array ordered by given expression. Examples: Both: OrderBy(["a", "x", "b", "z", "n", "l", "a"], _) OrderByValue(["a", "x", "b", "z", "n", "l", "a"]) Return: ["a", "a", "b", "l", "n", "x", "z"] OrderBy([9,8,7,6,5,4,3,2,1], _%3) Returns: [9,6,3,7,4,1,8,5,2] OrderBy([9,8,7,6,5,4,3,2,1], _%3 + _/30) Returns: [3,6,9,1,4,7,2,5,8]
OrderByDescending
OrderByValue
OrderByValueDescending
RemoveLeaves
ReplaceLeafValues	object varName (String) expression level (Integer)	Replace all leaf values of given hierarchical object at given levels up from the leaf level with results of given expression. Parameters: object: Array or hierarchical object. varName: Name of the variable used in the iteration. expression: Expression to evaluate to get the result of each iterated object. level: At which level of the hierarchical object are we operating (number of levels up from the leaf level). Examples: ReplaceLeafValues([1,2, null], "x", If(IsNull(x), null, x+1), 0) Result: [2, 4, null] ReplaceLeafValues([[[1,2],[2,3]],[[3,4],[4,5]]], "x", Flatten(x), 0) Result: [[[[1],[2]],[[2],[3]]],[[[3],[4]],[[4],[5]]]] ReplaceLeafValues([[[1,2],[2,3]],[[3,4],[4,5]]], "x", Flatten(x), 1) Result: [[[1,2],[2,3]],[[3,4],[4,5]]] ReplaceLeafValues([[[1,2],[2,3]],[[3,4],[4,5]]], "x", Flatten(x), 2) Result: [[1,2,2,3],[3,4,4,5]] ReplaceLeafValues([[[1,2],[2,3]],[[3,4],[4,5]]], "x", Flatten(x), 3) Result: [1,2,2,3,3,4,4,5]
SliceMiddle
StopOnNull
StringJoin	Separator (String) Array to join (Array)	Joins given array of values (converted to strings) by using given separator into a single string. If given a hierarchical object, applies the function as described in at the level that is one level up from the leaf level. The depth of the result is one level less than the object that was given as parameter. Null values will be converted into empty string. Examples: StringJoin(", ", [1,null,"foo",DateTime(2017)]) Returns: 1, , foo, 01/01/2017 00:00:00 StringJoin(", ", [[1,2], [3,4]]) Returns: ["1, 2", "3, 4"]
TimeRange
Variable
Where	condition (Boolean) false Expression	Returns the context object if the given expression evaluates to true. Otherwise returns the second parameter which defaults to _empty. Parameters: condition: Boolean expression to test. falseExpression: Expression to evaluate and return if the condition evaluates to false. Default value is _empty. Examples: [1,2,3,4].Where(_>2) Returns: [3,4] [1,2,3,4].Where(_>2, _+100) Returns: [101, 102, 3,4] [1,2,3].[_,_+1] Returns: [[1, 2], [2, 3], [3, 4]] [1,2,3].[_,_+1].Where(_>=3) Returns: [[], [3], [3, 4]] [1,2,3].[_,_+1].Where(_>=3, _remove) Returns: [[3], [3, 4]]

Properties and Functions by Object Types

Arrays

Array functions	Parameters	Description
IndexOfSubArray (integer)	Sub-array to search(array) Array from where to search the sub-array (array)	Returns the indexes of given sub-array (1. parameter) within the given array (2. parameter). If not given, the array in the current context object is used. Returns starting indexes of all the occurrences of given sub-array within given array. Examples: [[1,2,3,4,1,2,5]].IndexOfSubArray([1,2]) IndexOfSubArray([1,2], [1,2,3,4,1,2,5]) Return: [0, 4] [[1,2,3,4,1,2,5]].IndexOfSubArray([1,2,3,4,5]) Returns: [] [[1,2,3,4,1,2,5],[3,4],[0,1,2,3]]:IndexOfSubArray([1,2]) Returns: [ HierarchicalArray([1,2,3,4,1,2,5], [0,4]), HierarchicalArray([0,1,2,3], [1]) ]

AttributeType

Case properties	Description
Id (Integer)	AttributeType Id.
Name (String)	Attribute name.

Case

Case properties	Description
Duration (TimeSpan)	Case duration, i.e. duration between case start and case end time.
EndTime (DateTime)	Case end time, i.e. timestamp of the last event.
Events (Event)	All events of the case.
FlowOccurrences (FlowOccurrency)	All flow occurrences the case contains.
Flows (Flow)	All flows the case goes through.
Id (String)	Case Id.
Name (String)	Case name
StartTime (DateTime)	Case start time, i.e. timestamp of the first event.
Variation (Variation)	Variation the case belongs to.

Case functions	Parameters	Description
Attribute (Object)	attribute name (string)	Case attribute value. Case attribute name is provided as a parameter.

Event

Event properties	Description
Case (Case)	Case the event belongs to.
Id (Integer)	Event id.
IndexInCase (Integer)	Index (running) number of the event in the case (ordered temporally). The first event has index number 0.
Model (Model)	Model the event belongs to.
NextInCase (Event)	Temporally next event in the case. For the last event, return EMPTY.
PreviousInCase (Event)	Temporally previous event in the case. For the first event, return EMPTY.
TimeStamp (DateTime)	Timestamp of the event.
Type (EvenType)	Event type of the event.

For future: OutgoingFlow, IncomingFlow, OutgoingFlowOccurrence, IncomingFlowOccurrence, Variations

Event functions	Parameters	Description
Attribute (object)	attribute name (string)	Event attribute value. Event attribute name is provided as a parameter.

EventLog

Event properties	Description
CaseAttributes (AttributeType*)	Used case attribute in the EventLog.
Cases (Case*)	Cases that belong to the EventLog.
EventAttributes (AttributeType*)	Used event attributes in the EventLog.
Events (Event*)	Events that belong to the EventLog.
EventTypes (EventType*)	EventTypes in the EventLog.
Flows (Flow*)	Flows that the part of the EventLog.
Id	EventLog Id.
Model (Model)	Model where the EventLog belongs.
Name	EventLog name.
Variations (Variation*)	Variations that are in the EventLog

EventType

EventType properties	Description
Cases (Case*)	Cases that contain the EventType.
Count (Integer)	Event count that have this EventType.
Events (Event*)	Events of that EventType.
Id (Integer)	EventType Id.
Name (string)	EventType name.

For future: OutgoingFlow, IncomingFlow, Variations

Flow

Flow is a combination of two EventTypes where there are FlowOccurrences between them. Unlike FlowOccurrencies, a Flow is not related to a single case. Flowchart shows Flows and EventTypes (not FlowOccurences or Events). In a Case, the may be several FlowOccurrences of a single Flow.

Variation properties	Description
Cases (Case*)	Cases that contain the flow, i.e. there is a flow occurrence between Flow's starting and ending events.
FlowOccurrences (FlowOccurrence*)	Flow occurrences the flow belongs to.
Id (Integer)	Flow Id.
Name (string)	Identifying name of the Flow.

For future: FromEventType, ToEventType

FlowOccurrence

FlowOccurrence represents a transition from an event to another event in a case. Thus, FlowOccurrence is related to a single case. There is also a FlowOccurrence from the "start" of the case to the first event of the case, and a FlowOccurrence from the last event of the case to the "end" of the case. Corresponding flow is visible in BPMN kind of flowcharts showing separate start and event icons. Thus, there are one more FlowOccurrences in a case than the number of events.

Variation properties	Description
Case (Case)	Case the FlowOccurrence belongs to.
Flow (Flow)	Corresponding Flow of the FlowOccurrence.
Id (Integer)	FlowOccurrence Id.
Name (String)	Identifying name of the FlowOccurrence.
OccurrenceIndex (Integer)	Number tells how many times the FlowOccurrence has occurred in the case until that point.

For future: FromEvent, ToEvent, Duration

TimeSpan

TimeSpan represents a temporal duration (for example: 5 hours or 8 days). TimeSpan is not bound to calendar time. Difference between two TimeStamps is TimeSpan. TimeStamp added by TimeSpan is TimeStamp.

TimeSpan properties	Description
TotalDays (Float)	Timespan value in days (one day is 24 hours) (both whole and fractional).
TotalHours (Float)	Timespan value in hours (both whole and fractional).
TotalMilliseconds (Float)	Timespan value in milliseconds(both whole and fractional).
TotalMinutes (Float)	Timespan value in minutes (both whole and fractional).
TotalSeconds (Float)	Timespan value in seconds (both whole and fractional).

Variation

Variation properties	Description
CaseCount (Integer)	Number of cases in the variation.
Cases (Case*)	Cases that belong to the variation.
EventTypeCount (Integer)	Number of events in the variation.
EventTypes (EventType*)	Event types belonging to the variation.
Id (Integer)	Variation Id.
UniqueEventTypeCount (Integer)	Number of different (unique) event types in the variation.

DateTime

Properties: Day, Hour, Millisecond, Minute, Month, Second, Year