Specifying reference path

A reference path consists of a number of fragments that are separated by a forward slash or backward slash.

• A forward slash like /SYSTEMREF specifies a forward reference from the data object that is the starting point (in this example, a resource data object) via SYSTEMREF to one or more other data objects (in this example, a system data object).
• A backward slash like \SYSTEMREF specifies a backward reference to the data object that is the start point (in this example, a system data object) from one or more data objects (in this example, resource data object) via SYSTEMREF.

info

Only the following characters are allowed to be a part of a reference path. Depending on the part of reference path the following regular expressions are used:

• strings: A-Za-z0-9._\-\s
• property or variable: A-Za-z0-9_

Fragments

A fragment must be either:

• The system name of a reference property.
• The name of a built-in reference field.
• The name of a virtual reference property. You can only use this as a forward reference.

Built-in reference fields

The following built-in reference fields are supported:

Built-in reference field	Valid for data object types	Note
TARGET	Process Activity
PROCESS	Activity Any target object type
TREECHILDREN	Any	Can only be a forward reference in a path.
TREEPARENT	Any	Can only be a forward reference in a path.

Virtual reference properties

With a virtual reference property, you can add business logic to a reference path expression. As an example, the expression /IDENTITYREF/$ActualManager yields the manager of the referenced identity - not only the value from the MANAGER property, but the manager according to the Org. unit structure (including traversal to the parent Org. units).

The virtual reference properties can be used in several places:

Assignee path

In the Assignee path of a process activity. Thereby the assignee of the activity is calculated instead of static. Look at the example from the Maintain my data template:

Mail receiver

As the receiver of a mail-in-mail action using The users referenced via reference paths field:

Mail field

In a mail message using the REFPATH prefix:

View field

As a view column - add a ReferencePath field (1-5) and supply a reference path expression with a virtual reference property.

The following virtual reference properties (VRPs) are supported:

Virtual reference property	Valid for data object types	Returned data object types	Description
$EffectiveManager	Identity User	Users and User Groups	This VRP holds the "managers" of an identity or a user. This property is multi-valued so it can show more than one manager if more than one exists. Values are users or groups (or a combination). The manager is deduced using the primary context type of the identity, usually the Org. units context type. The context hierarchy is traversed upwards until a manager is found. If a supervisor property is defined on the context type, and a value is defined on the identity object, it takes precedence over the context hierarchy manager. However, if the GetIdentManMode customer setting is set to 1, then both the supervisor and the context manager are returned. Optionally, you can use the OWNERPROPERTY and MEMBERSHIPPROPERTYONLY parameters for this property. They can be specified in parentheses after the VRP, for instance: $EffectiveManager(OWNERPROPERTY=EXPLICITOWNER;MEMBERSHIPPROPERTYONLY=1). By using the OWNERPROPERTY parameter, you can specify an alternative manager property for the context, apart from the one configured for the context type object. This can help, for example, when an approval task or a mail notification is only destined for one manager, and not the others. For instance, in Org. units, the manager property calculated by default is MANAGER, and it contains delegated managers and access requested managers, whereas the EXPLICITOWNER field by default contains the HR manager. You can use the parameter if some approval task or mail notification should only be destined for the HR manager. Using the MEMBERSHIPPROPERTYONLY parameter, the VRP does not include or traverse direct context assignments. Therefore, managers for context assignments in a grace period are not included when calculating the manager. Likewise, this can be useful when having secondary or part-time associations to a context.
$ActualManager	Identity User	User	Yields a single manager of an identity or a user. There may be situations where a single manager is needed, for example, for provisioning. If there are multiple managers configured on an organizational unit level, this property returns the lowest ID. Refer to the $EffectiveManager property to learn how the managers are deduced. This VRP supports the OWNERPROPERTY and MEMBERSHIPPROPERTYONLY parameters. They can be useful if, for instance, you want to resolve the service desk without including direct context assignments.
$EffectiveServiceDesk	Identity User	Users and User Groups	This VRP resolves the first primary context where there is a value in the Service desk property defined on the Context type, typically configured as the Service desk agents property. This VRP supports the OWNERPROPERTY and MEMBERSHIPPROPERTYONLY parameters. This can help if, for instance, you want to resolve the service desk without including direct context assignments. Unlike $EffectiveManager and $ActualManager, this VRP returns itself if it is the closest Service desk agent in the context tree. Unlike $EffectiveManager and $ActualManager, this VRP returns the identity or the user itself if it is the closest Service desk agent in the context tree.
$ContextOwner	Object types with a Context type definition, for example, Org. units	Users and User Groups	Resolves the context owner for a context object based on the setting in the context type, for example, traversing to the parent context until it finds an owner. The owner property defined in the context type can be overwritten with the OWNERPROPERTY parameter, for example: /$ContextOwner(OWNERPROPERTY=EXPLICITOWNER) If the VRP meets the calling user, then it traverses to the next level. This can be overridden by specifying the parameter CRAWLMODE, for example, /$ContextOwner(CRAWLMODE=3), where: 0: traverse if the owner is undefined or only contain the calling user 1: traverse if the active user is among the owners 2: traverse and accumulate all the way to the top 3: return the first non-empty owner, regardless if it's the calling user.
$Process	Activity	Process	Returns the process object for an activity.
$AccessReqOrgApprover	Resource assignment	User	Calculates the approvers in the access request survey. If a resource assignment, subject to approval, has a reference to a context (usually, it does), then the approver is the owner of that context. If not, the approver will be calculated as the manager of the beneficiary (the identity). For technical identities, the approver is resolved based on the owner of the technical identity.
$IdentityOwnerUser	Identity	User	The IdentityOwnerUser property returns the owner (user) of an identity. If the identity is a primary identity, then the owner is the user referring to the identity. If the identity is a machine identity, the result is the user referring to the owner of the machine identity.
$TransferOwnershipAssignee	Identity	Users	The property yields the system owners (users) for systems referencing the provided (technical) identities through the SYSTEMIDENTITIES property.
$AttributeValueReferences	Attributes	Any object type	This property returns the objects pointed to by the attribute values on the Attributes property of the resource assignment data object. The attribute values are suited to reference other data objects according to the definition of the Attribute object on the resource type. For this property to work, the Reference value format on the Attribute must contain a single property (for example, IDENT), or it must be left empty (in which case, the Display name field is used). It both cases, the value must uniquely identify the object. This property can be used to implement attribute-based approval of access requests. If you want to assign the approval of a resource to the owner of the object being referenced through attributes, use the following assignee path in the Access Approval Survey: /RESASSIGNMENT/ATTRIBVALUES/$AttributeValueReferences/OWNERREF. When modeling a multi-dimensional access model, remember that revocations and recertifications are resource-based. You cannot maintain the selected attributes. Therefore, we recommend that you limit the allowed attribute values to one per attribute. Also note that you cannot combine multiple dimensions (attribute values) into a single approval step. For example, if you have attributes for location and legal entity, you will need two different approval steps.
$CreatedBy	All	User	Returns the user who created the object.

Fragment expressions

Each fragment can contain filter expressions which are applied to the data objects that results from the fragment, for example:

\SYSTEMREF{NAME='Cost Center Owner'; RESOURCESTATUS='Active'}

The starting point is a system data object. The example only gives resources with the name Cost Center Owner and a status of Active. Expressions are always treated as having an implicit and between them.

Expressions of the supported data types

The data type of an expression is controlled by the left-side:

Data type	Note	Constant value examples
String		'hello'
Integer		42
DateTime		2016-01-28T09:00:00Z
Boolean		True
Reference	A reference to another object in the system. You must specify this as an integer ID or a (guid) uid. Normally, a referred object is a data object, but it can also be other types of objects, such as data object types and set property values.	1000262 AF32A836-FBAF-4929-9AB2-57E67017545C
Enum	A fixed set of enumeration values are supported. Which depends on the left-side field.	'Active'

The following fields are allowed on the left-side:

Allowed on left-side	Data type	Note
Value property - Text	String
Value property - Integer	Integer
Value property - DateTime	DateTime
Value property - Boolean	Boolean
Set property	Reference	Reference to a set property value. Besides IDs and UIDs, the right-side can be the name of a set property value in the active user’s language.
Reference property	Reference	Reference to a data object.
Virtual reference property	Reference	Reference to a data object.
CreateTime	DateTime
CreatedBy	Reference	Reference to a User data object.
ChangeTime	DateTime
ChangedBy	Reference	Reference to a User data object.
Number	Integer
Type	Reference	Reference to a data object type.
UserName	String	Applies to User data objects.
Id	Reference	Reference to a data object.
ActivityState	Enum	Applies to Activity data objects. The possible values are: Inactive,       Active, Completed, Terminated
ProcessState	Enum	Applies to Process data objects. The possible values are: Inactive, Active, Completed, Terminated
Template	Boolean
Inactive	Boolean	Applies to user data objects.
DisplayName	String

The following operators are supported:

Operator	Supported for data types
`=	Reference, String, Integer, DateTime, Boolean
<	Integer, DateTime
>	Integer, DateTime
<=	Integer, DateTime
>=	Integer, DateTime
<>	Reference, String, Integer, DateTime, Boolean
Like	String

Reference path examples

The following table presents the reference path examples:

Starting point	Reference path	Description
Resource	/SYSTEMREF	Get the system that a resource belongs to.
System	\SYSTEMREF	Get the resources that belong to a system. The only data object type that refers to SYSTEMREF is Resource.
System	\SYSTEMREF{NAME='Cost Center Owner'}	Get a resource that belongs to a system. You must name the resource Cost Center Owner.
System	\SYSTEMREF{NAME like 'Resource'}	Get the resources that belong to a system. You must begin the name of the resource with Resource.
System	\SYSTEMREF{RESOURCESTATUS='2cebbf25-b2b9-4922-b539-02f3c764c0fc'}	Get the resources that belong to a system – the resources must have status Active.
System	\SYSTEMREF{RESOURCESTATUS='Active'}	Get the resources that belong to a system – the resources must have status Active. Even though this query is easier to write than the query above, Omada does not recommend that you use this format in code, as the Active value is dependent on the language in use.
System	\SYSTEMREF{RESOURCESTATUS='2cebbf25-b2b9-4922-b539-02f3c764c0fc'; NAME like 'Resource'}	Get the resources that belong to a system. The resources must have the status Active and their name must begin with Resource.
System	\SYSTEMREF{NAME like 'Resource'}/ROLETYPEREF	Get the resource types of the resources that belong to a system. The name of the resource must begin with Resource.
Any non-special type	/PROCESS	Get the process(es) that has the starting point as target object.
Activity	/PROCESS	Get the process that the activity belongs to.
Process	\PROCESS	Get the target and activity objects of the process.
Process	\PROCESS{Index=2}	Get the activity in the process that has index 2.
Process	\PROCESS{Index>=2}	Get the activity in the process that has index 2 or above.
Process	\PROCESS{Index<2}	Get the activity in the process that has an index less than 2.
Process	\PROCESS{Index<>2}	Get the activity in the process that has an index which is not 2.
Process	/TARGET	Get the target object of the process.
Activity	/TARGET	Get the target object of the process that the activity is part of.
Any non-special type	\TARGET	Get the process and activity objects in which the starting point is target object.
System	\SYSTEMREF{ChangeTime>2015-05-01T09:00:00Z}	Get the resources that belong to a system. You must have modified the resources later than May 1st, 2015.
System	/OWNERREF{Inactive=False}	Get the owners (users) of a system but only those that are active.

Display name format

In some places, you can add a display name format after the reference path. You separate the reference path from the display name format by typing a colon after the reference path, for example:

/SomeReference/SomeOtherReference:[FirstName] [LastName]

The post fixed display format is used to obtain textual values of the data objects found using the reference path. The display format may contain fixed text and variable text in the form of properties and fixed fields. You must state the properties by their system name enclosed in square brackets (example: [NAME]). Fixed fields must be stated by their name enclosed in square brackets (example: [Assignee]).

Testing a reference path

When you have created a reference path, you may want to test to see if the reference path servers your purpose. Omada Identity includes a test page on which you can test a reference path. You can access the page by typing http://<websiteurl>/RefPathQuery.aspx in your browser.

The test page allows you to enter a starting point data object in addition to a reference path and see the results of entering them.

You must enter an ID for the data object that server as the starting point. You do this in the Source objects ids field. The ID used in the example below is for the built-in resource data object called Cost Center Owner.

The ID is most likely is not the same in your solution. You must obtain it yourself.

You can find the ID by holding down CTRL + right-click in a view that shows the data object, then click Page Variables. Select the value for DOID.