ECExpressions

ECExpressions is a very basic language that allows customizing presentation rules' behavior.

Symbols that can be used depend on current context. Example:

this.GetContextB().ContextC.DoSomething()

Here, symbol this returns a context which has a function symbol GetContextB(). This function returns a context which has a property symbol ContextC. And the property value is a context that contains a function symbol DoSomething(). The latter function might return some value or return nothing, but instead do some action - it all depends on the symbol.

ECExpression syntax

Data types

ECExpressions contain values of primitive types or data type of ECClass or ECArray.

Primitive value types

Type	Description	Example
Boolean	Boolean (true/false) value	True, False
DateTime	Date and time in ticks	@1549278124937
Integer (Long)	32-bit (64-bit) number	1
Double	Floating point number	6.84
String	String of characters	"" ,"Dog and Cat"
Null	Null value	Null

Other primitive types

Type	Description
Binary	Array of bytes
Point2d	2D point containing X and Y components as double values
Point3d	3D point containing X, Y and Z components as double values
IGeometry	A common geometry value of any type

ECClass data type

ECClass data types define ECInstances. ECClasses contain ECProperties and Methods which can be accessed via dot (.) operator.

ECArray data type

ECArray data types define arrays of values. Each value can be accessed via [] operator.

Expression components

In addition to values of primitive types ECExpressions may contain symbols and operators

Symbols

Symbols are used to supply values to expression evaluator. Symbols can be supplied from ECInstance via an access string, from an application defined value or from application defined method. Access string is a limited expression that holds no blanks, no operators, and no variable portions. It may contain array indexing and member selection using [] or dot . operators, but no part of the expression can be variable, and the access string cannot contain embedded blanks.

Property symbols

ECInstance Property symbols supply Property values of some ECInstance when the symbol is being evaluated.

this.PropertyName
this.StructPropertyName.PropertyName
this.StructArray[5].Struct.PropertyName

Value symbols

Value symbols supply some named predefined value in a context.

System.Math.PI

Method symbols

Method symbols supply a named method in a context.

System.Math.Sin(1.57)
this.IsOfClass("ClassName", "SchemaName")

Value lists

Value lists in ECExpressions are iterable containers and can be handled with lambdas. Currently presentation rules engine supports only a single simple lambda for value lists, AnyMatches, which checks if any of the items in the value list passes given condition. Examples:

value_list.AnyMatches(x => x = this.PropertyValue)
value_list.AnyMatches(x => this.PropertyValue = x)
value_list.AnyMatches(x => this.IsOfClass(x.PropertyValue))

Operators

Parentheses (,)

(2 * (3 + 4))

Logical operators

Description	Operator
Conjunction	And*, AndAlso
Disjunction	Or*, OrElse
Exclusive disjunction	Xor
Negation	Not

Note: *Checks right side of expression even if result value can be deducted from the left side.

False And True OrElse True

Comparison operators

Description	Operator
Less than	<
Less than or equal to	<=
Greater than	>
Greater than or equal to	>=
Equal to	=
Not equal to	<>

20 < 10 ==> False

Arithmetic operators

Description	Operator
Exponentation	^
Multiplication	*
Double division	/
Integer division	\
Modular division	Mod
Addition	+
Subtraction	-

1 + "4"   ==> 5
2.2 * 3   ==> 6.6
12 / 5    ==> 2.4
12 \ 5    ==> 2
25 Mod 3  ==> 1

Bit shift operators

Description	Operator
Signed shift left	<<
Signed shift right	>>
Unsigned shift right	>>>

5 << 1      ==>  10
24 >> 2     ==>  6
-105 >> 1   ==>  -53
-105 >>> 1  ==>  75

Conditional operator

IIf (condition, true-result, false-result)

Returns result based on given condition. If condition evaluates to true, returns true-result. Otherwise returns false-result.

IIf (500>200, "Math ok", "Math wrong") ==> "Math ok"
IIf (500<200, "Math ok", "Math wrong") ==> "Math wrong"

Concatenation operator

"Dog" & " and " & "Cat" ==> "Dog and Cat"
"1" & 4                 ==> "14"
1 & "4"                 ==> "14"

Lambda operator

Lambda operator => creates a callback expression for a given symbol.

MyArray.Find(item => item.IntProperty = 5)

Combined expressions

System.Math.Cos (System.Math.PI * 45.0 / 180.0) ==> 0.707
System.String.Length ("Dog" & " and " & "Cat") ==> 11

Evaluating if property is Null

Method IsNull (value) evaluates if given value is Null.

Method IfNull (value, value-if-null) evaluates to value if it is not null, otherwise evaluates to value-if-null.

In case this.MiddleName is null:

IfNull (this.MiddleName, "") ==> ""
IIf (Not IsNull(this.MiddleName), " " & this.MiddleName & " ", "") ==> ""

In case this.MiddleName is set to "Harvey"

IfNull (this.MiddleName, "") ==> "Harvey"
IIf (Not IsNull (this.MiddleName), " " & this.MiddleName & " ", "") ==> " Harvey "

Checking to see if a this.MiddleName is Null or empty

IIf (IsNull (this.MiddleName) or this.MiddleName = "", "Is null or empty", "Has a value")

ECExpression contexts

NavNode

Symbol	Type	Value
IsNull	bool	Is this context null
Type	string	Type of the node
Label	string	Node label
Description	string	Node description
ClassName	string	ECClass name if its an EC-related node
ClassLabel	string	ECClass display label if its an EC-related node
SchemaName	string	ECSchema name if its an EC-related node
SchemaLabel	string	ECSchema display label if its an EC-related node
SchemaMajorVersion	number	ECSchema major version if its an EC-related node
SchemaMinorVersion	number	ECSchema minor version if its an EC-related node
InstanceId	number	ECInstance ID if its an ECInstance node
IsInstanceNode	bool	Is this an ECInstance node
IsClassGroupingNode	bool	Is this an ECClass grouping node
IsPropertyGroupingNode	bool	Is this an ECProperty grouping node
GroupedInstancesCount	number	Count of grouped ECInstances (only available for ECClass and ECProperty grouping nodes)
ECInstance	ECInstance context	ECInstance symbol context if its an ECInstance node
HasChildren	bool	Does this node have any children
ChildrenArtifacts	object[]	A value list of objects generated using the NodeArtifacts customization rule on child nodes. Child nodes in this case are immediate child nodes that are not necessarily visible.

ECInstance

ECInstance expression context provides access to ECInstance property values. Example:

this.PropertyName
this.StructPropertyName.PropertyName
this.StructArray[1].Struct.PropertyName

Additionally, when evaluating ECInstance contexts, the below symbols are available:

Symbol	Type	Value
GetRelatedDisplayLabel("RelationshipSchemaName:RelationshipName", "Forward|Backward", "RelatedClassSchemaName:RelatedClassName")	string	Returns display label of the related instance
GetRelatedInstancesCount("RelationshipSchemaName:RelationshipName", "Forward|Backward", "RelatedClassSchemaName:RelatedClassName")	number	Number of related instances following the specified relationship
GetRelatedInstancesCount("RelatedClassSchemaName:RelatedClassName", lambda_for_filtering_related_instances)	number	Number of related instances that match criteria described by given lambda
HasRelatedInstance("RelationshipSchemaName:RelationshipName", "Forward|Backward", "RelatedClassSchemaName:RelatedClassName")	bool	Does this instance has a related instance following the specified relationship
HasRelatedInstance("RelatedClassSchemaName:RelatedClassName", lambda_for_filtering_related_instances)	bool	Does this instance has a related instance that matches criteria described by given lambda
GetRelatedValue("RelationshipSchemaName:RelationshipName", "Forward|Backward", "RelatedClassSchemaName:RelatedClassName", "PropertyName")	any	Returns property value of the related instance
GetRelatedValue("RelatedClassSchemaName:RelatedClassName", lambda_for_filtering_related_instances, "PropertyName")	any	Returns property value of related instance that matches criteria described by given lambda
IsOfClass("SchemaName", "ClassName"))	bool	Returns true if the instance is of a class with given schema and class names
IsOfClass(SomeECClassId))	bool	Returns true if the instance is of a class with specified ECClass ID

Deprecated symbols:

Symbol	Type	Value
GetRelatedInstance("RelationshipName:0|1:RelatedClassName")	ECInstance context	Returns related instance context. Not available when evaluating instance filters.

ECInstance key

ECInstance key expression context provides access to class and instance IDs. The context has the following symbols:

Symbol	Type	Value
ECClassId	number	ID of ECInstance's ECClass
ECInstanceId	number	ID of ECInstance

Symbols in global context

Ruleset variables (user settings)

Note: User Settings is a deprecated name of Ruleset Variables concept.

Ruleset variable access symbols allow accessing variable values through ECExpressions.

Symbol	Deprecated Symbol	Type	Value
GetVariableStringValue("var_id")	GetSettingValue("var_id")	string	Get string value of a variable with the specified ID
GetVariableBoolValue("var_id")	GetSettingBoolValue("var_id")	bool	Get boolean value of a variable with the specified ID
GetVariableIntValue("var_id")	GetSettingIntValue("var_id")	number	Get int value of a variable with the specified ID
GetVariableIntValues("var_id")	GetSettingIntValues("var_id")	number[]	Get int value list of a variable with the specified ID
HasVariable("var_id")	HasSetting("var_id")	bool	Does variable with the specified ID exist

Other symbols

Symbol	Type	Value
Set(number1, number2, ..., numberN)	number[]	Create a value list of the supplied numbers.
GetFormattedValue(this.MyProp, "Metric|UsCustomary|UsSurvey|BritishImperial")	any	Returns property value formatted using specified unit system. If unit system is not specified default presentation units are used to format value

Formatted property values

Comparison of formatted property values in ECExpressions can be done using GetFormattedValue function. Specific unit system can be passed as a second argument to function or omitted to use default presentation format:

GetFormattedValue(this.Length, "Metric") = "10.0 m"
GetFormattedValue(this.Length) = "10.0 m"