Search Expressions

Definition

Search Expressions are domain-specific language used to search objects (Managed Objects, Reporting collections,…) or express constraints on them.

They are composed of Property Expressions (e.g. firstName LIKE 'John*') and Functions combined with Logical Operators (AND, OR, NOT)

securityOrganization <<= 'Finance' AND hasRoleMatching(role IN ('sap_user', 'sap_admin'))

Property Expression

A Property Expression expresses a constraint on a single object property. For Managed Objects, those properties are the Object Attributes.

They consist of a Property, an Operator and Values, for instance firstName = 'John'.

Expression operators

The table below lists all the available operators.

Available operators depend on the use case

Dotted Property Paths

It is possible to express constraints on referenced objects using dotted property paths, like manager.firstName

For instance, for Manage Objects, manager.firstName = 'John' would match all identities whose manager’s first name is John.

Logical Operators

Logical operators AND, OR and NOT are used to combine Search Expressions (including other Logical Operators).

For instance: (firstName = 'John' OR firstName = 'Jane') AND lastName = 'Doe'

The Empty Expression

The Empty Expression () is a special Expression matching everything. Its negation NOT () matches nothing.

Search Expression Functions

Search Expression functions accept one or more Search Expression arguments. they are builtin tools to implement complex scenarios that cannot be expressed simply with search expressions:

• Search Identities having at least one Role Assignment matching a criterion: hasRoleMatching(role = 'someRole' AND status = 'ASSIGNED')

• Search Identities having a Security Organization matching a criterion: hasSecurityOrganizationMatching(id BELOW_OR_EQUALS 'europe' AND NOT (id BELOW_OR_EQUALS 'france'))

• Role Request engine, to find assignable Roles based on Role Request Policies

• Object Recertification Metadata, to find the recertifications of an object: hasRecertificationMetadataMatching(recertifiedAt IN LAST 'P3M')

• Etc.

Usage

UI

In the user portal, search expressions is one of the two means to search on objects, in complement with full text search.

They can be input either graphically for simple expressions, or using a DSL for complex cases:

Text DSL

Depending on configuration, Search Expression may be input in plain text:

securityOrganization <<= 'Finance' AND hasRoleMatching(role IN ('sap_user', 'sap_admin'))

Property Expressions

Property Expressions must be written as <property name> <operator> <value>:

firstName = 'John'

Syntax rules:

• Property name may be a single property (firstName) or a dotted Property Path (manager.securityOrganization.type).

• Property names that do not start with a latin letter or an underscore, or that other characters than latin letters, numbers must be quoted with double quotes ("), e.g "some \"weird\" property".

• Operators are the Formula Operators in the table above.

• Use parenthesis for IN and NOT IN operators, e.g firstName IN ('John', 'Jane')

• Use an AND separator for BETWEEN operator: enabledFrom BETWEEN '2022-01-01T00:00:00Z' AND '2023-01-01T00:00:00Z'

• String values must be quoted using single quotes ('), e.g. 'John \'Johnny\' Doe')

• Date and Date & Time values must be written as ISO-8601 strings, e.g. ‘2022-11-04' / '2022-11-04T07:30:43Z'

• Numbers must be written using the dot (.) as decimal separator, e.g. -42, +43.756

Operator Expressions

On may combine arbitrary Search expressions using AND, OR and NOT operators, and parenthesis:

(securityOrganization <<= 'Finance' OR securityOrganization <<= 'Sales') AND hasRoleMatching(role IN ('sap_user', 'sap_admin'))

Functions

Function Expressions must be written as <function name>(<argument1>, <argument2>,...):

hasRoleMatching(role IN ('sap_user', 'sap_admin'))

Syntax rules:

• Function names follow the same quoting rules as Property names

• Function arguments are always Search Expressions, separated by commas (,)

XML configuration

Search Expressions appear in the Configuration mostly in Scopes:

• Features: Feature Scope, Search widgets, Reporting Widgets,…

• Policies

• Reference Attributes

• …

They use the dedicated search namespace.

Property Expressions

<search:Prop op="EQUALS" name="enabled">
    <value>true</value>
</search:Prop>

<search:Prop op="IN" name="firstName">
    <value>John</value>
    <value>John</value>
</search:Prop>

In the context of Dynamic Scopes, the value element may contain Groovy code:

<search:Prop op="EQUALS" name="manager">
    <value script="true">OBJECT.id</value>
</search:Prop>

See Scopes for further details.

Logical Expressions

<search:And>
    <search:Prop op="EQUALS" name="lastName">
        <value>Doe</value>
    </search:Prop>
    <search:Prop op="EQUALS" name="firstName">
        <value>John</value>
    </search:Prop>
</search:And>

<search:Or>
    <search:Prop op="EQUALS" name="firstName">
        <value>Jane</value>
    </search:Prop>
    <search:Prop op="EQUALS" name="firstName">
        <value>John</value>
    </search:Prop>
</search:Or>

<search:Not>
    <search:Prop op="EQUALS" name="manager.firstName">
        <value>John</value>
    </search:Prop>
</search:Not>

Empty Expression

<search:Empty/>

Functions

<search:Func name="hasRoleMatching">
    <search:And>
        <search:Prop op="EQUALS" name="status">
            <value>ASSIGNED</value>
        </search:Prop>
        <search:Prop op="EQUALS" name="role.application">
            <value>o365</value>
        </search:Prop>
    </search:And>
</search:Func>

Groovy Rules

A groovy DSL is available to easily construct search expressions:

def emptyExpression = expr {}
def firstNameAndLastNameConstraint = expr {firstName.eq("John") & lastName.eq("Doe")}
def hasO365Role = expr {hasRoleMatching(status.eq(RoleAssignmentStatus.ASSIGNED) & prop("role.application").eq("o365"))}

See Rules and Actions API for further details.

Special builtin attributes

Some builtin attributes, especially on Identities are not of a simple type (String, Integer,…). This section explains how to search on them

Identity Rights

To match Identities having a Right Grant, use a Property Expression with the EQUALS or IN operators on the rights Attribute. The Property Expression value must be a String of the form <right name>:<right target>:<right privilege> where each part can be omitted:

• Match all identities having a specific right, with any target or privilege:

  CODE

  rights = 'app.o365.access'

• Match all identities having a specific right on a specific target, with any privilege:

  CODE

  rights = 'user.manager:France'

• Match all identities having a specific right on any target, with a specific privilege:

  CODE

  rights = 'feat.user-card-read::2'

• Match all identities having a specific right on a specific target with a specific privilege:

  CODE

  rights = 'app.sap.sales:France:1000000'

Identity Roles

It is also possible to match Identities using criteria on Role Assignments using the hasRoleMatching Function. For instance:

hasRoleMatching(status = 'ASSIGNED' AND "role.application" = 'o365')

Will match all identities having at least one Role Assignment whose status is ASSIGNED and whose Role matches application = 'o365'

Role Assignment Dimensions

To match Role Assignments having a certain dimension values, use a Property Expression with the CONTAINS operator on the dimensions Property. The Property Expression value the JSON serialization of the dimension values to match:

dimensions CONTAINS '{"dim1": "foo", "dim2": ["bar", "baz"]}'

Will match all Role Assignments where

• Dimension dim1 is equal to foo

• Dimension dim2 contains at least bar and baz in any order.

Read Next