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, it is possible to 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 OrgUnit structure including traversal to the parent Org. units.

The virtual property 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 are supported:

Virtual reference property	Valid for data object types	Returned data object types	Description
$EffectiveManager	Identity User	Users and User Groups	The EffectiveManager property holds the "managers" of an identity or a user. EffectiveManager is multi-valued so it can show more than one manager if more than one exists. Values are either users or groups (or a combination). The manager is deducted using the primary context type of the identity, usually the Org. units context type. The context hierarchy will be 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.
$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 org unit, this property will return a random one of them. Refer to the $EffectiveManager property to learn how the managers are deducted.
$CreatedBy	All	User	Returns the user who created the object.
$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.

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.