Rule Engine Object Properties

For general rule help see Rule Engine Introduction

In many cases (e.g. Report field, workflow trigger, Uplift flow rule), a rule should return a value based on the context argument. Object Properties rules traverse the context object of a rule. They can also traverse properties on an object returned by another rule.

Object traversal is one of the biggest points of difference between the Rule Engine and other languages with similar syntax. The following are key differences:

• Dotted notation is used for all traversal, including dictionary and list/array indexing. Instead of:
  

  Counters[2] or Attributes["givenName"]

  we use

  Counters.2 or Attributes.givenName

• Both positive and negative indexing is supported for lists. A negative number counts from the end of the list (as in the Python language). The last item in a list is -1, then -2. The first item is 0. For example:

  context.-1
  context.-2
  context.0
  context.1
  

• Any path index (except for the path root) may contain certain non-alphanumeric characters, including ':', '-', and ' '. For example:

  Attributes.Display Name

• Every path traversal starts with 'context.', and most of the time this is implicit. The exception is when the first part of the traversal includes non-alphanumeric characters. For example:

  Attributes.givenName

  is the same as

  context.Attributes.givenName

  However, instead of just

  Display Name

  we need

  context.Display Name

• Any special value may be used in a path traversal and it treats the result of the special value as if it were literally typed as the path value. For Example:

  Attributes.special.Attribute.givenName and Counters.special.History Counter.Import Add

  are the same as

  Attributes.givenName and Counters.2

The rule helper for Object Properties allows selection of a type (often this is pre-selected if Identity Panel knows what type is expected). It then displays an expandable tree of links representing properties and documentation in the structure of the type. Clicking on a link will insert the traversal to that value. A Dictionary or List property will have a textbox or dropdown to indicate what value to insert at that part of the traversal.

Derived Objects

Sometimes object traversal will be done against the results of another rule, rather than with the primary context object. Also, some rule functions take a rule as an argument, and apply the rule to other context arguments.

For the example rule, the first argument to the Filter function operates on the overall context of HistoryRecord, but the second argument operates on child context objects of HistoryError. Finally, object notation returns the length of the filtered list.

Filter(Errors, Contains(DN, "DC=softwareidm")).Count > 0

Note: the above rule could be equivalently written as:

Filter(context.Errors, Contains(context.DN, "DC=softwareidm")).Count > 0

Property Names and Case Sensitivity

There is an important behavioral difference between indexing into a list or dictionary, and traversing a property. The Rule Engine includes bounds checking to avoid IndexOutOfRange and KeyNotFound errors and returns null values instead, whereas indexing a property that does not exist on the type will result in a NullReferenceException when the rule is evaluated. This behavior may be confusing at first, but makes the most common cases easier for working with report fields and flow rules.

The Rule Engine will ALWAYS return a property name before a dictionary value. For example, if you have a report row that does grouping and you want to return the size of the group you CANNOT access the row count of the group with:

Data.Count

This will just return the number of columns in the row. If an object property exists with the same name as a desired dictionary key you must use the Key() function:

Key(Data, "Count")

Object traversal should generally be thought of as case-sensitive. The one exception is that dotted indexing into a dictionary property may be case-insensitive if the implementing object has used the String.OrdinalIgnoreCase (or similar) comparator, to reduce common errors. Two such examples are ObjectRecord.Attributes, and ReportRow.Data.

Note: dictionary in this case refers to any object implementing a .NET string indexer (i.e. an Item function taking a string), not just the .NET generic dictionary.

List Functions

It should be noted that many of the functions in the List Functions section are related to and may be combined with object traversal. Among other things these functions can be used to produce, sort, and filter lists, find values, and lookup dictionary values where the key name is produced by another rule.