Value references
A value reference is an expression that resolves into the value of the referenced property. For example, the %description% value reference will resolve into the value of the Description property of a directory object. The context where value reference is used determines which object to get the value from. For instance, value references used in a business rule that triggers After creating a user will resolve into the property values of the new user.
Syntax
In its most basic form, a value reference has the following format: %propertyName%.
propertyName is the name of the property whose value to obtain. The name must be specified exactly as it is defined in your directory schema. The percent (%) character signifies the beginning and the end of a value reference. If you need to use a % character without invoking a value reference, escape it with %%. For example, the modulus operator in PowerShell scripts used in Adaxes must be escaped: $myInt = 7 %% 2.
You can apply additional formatting to the resulting value. All value references except date/time properties follow the same general formatting syntax. Date/time properties have their own syntax.
In Administration console and Web interface configurator, you can use the Insert value reference 
button to quickly insert a correctly formatted value reference into a field.
General formatting
%propertyName[:format[]][:lower|upper],[count],[char]%
To modify the resulting value, use the following optional parameters:
-
[:format[]]
-
Customizes the format of the resulting value. See details below.
-
[:lower|upper]
-
Changes the case of the entire resulting value to lowercase or uppercase.
-
[,count]
-
Trims the resulting value to the specified number of characters.
-
[,char]
-
Inserts padding characters if the resulting value is shorter than the count parameter value. To use percent (%) as the padding character, specify it as %% (e.g. %department,5,%%%).
The :format[] parameter can be used to set the format of the resulting value. Here's the list of available formats.
name
Available for
- Email-format properties e.g. local-part@domain.
- DN properties e.g. CN=John Smith,CN=Users,DC=example,DC=com.
Resulting value
Only the local part of the email-format property.
%mail% => jsmith@example.com
%mail:format[name]% => jsmith
Only the RDN of the DN property.
%manager% => CN=John Smith,CN=Users,DC=example,DC=com
%manager:format[name]% => John Smith
domain
Available for
- Email-format properties e.g. local-part@domain.
- DN properties e.g. CN=John Smith,CN=Users,DC=example,DC=com.
Resulting value
Only the domain part of the property.
%mail% => jsmith@example.com
%mail:format[domain]% => example.com
%manager% => CN=John Smith,CN=Users,DC=example,DC=com
%manager:format[domain]% => example.com
full
Available for
The username alias.
Resulting value
The full username, including the domain part.
%username% => jsmith
%username:format[full]% => jsmith@example.com
Examples
-
%company% will be replaced with the value of the Company property.
%company% => Acme -
%company:lower,2% will be replaced with the first two characters of the Company property value in lower case.
%company:lower,2% => ac -
%company,7,#% will be be replaced with the value of the Company property. If the value contains fewer than 7 characters, the # characters will be added to make the resulting value 7 characters long.
%company,7,#% => Acme### -
%mail:format[domain]% will be be replaced with the domain part taken from the value of the Email property.
%mail:format[domain]% => example.com -
%manager:format[name]% will be be replaced with the manager's full name derived from the value of the Manager property.
%manager:format[name]% => John Smith
Date/time formatting
The resulting value of value references that refer to date/time properties (e.g. When Created) can be heavily modified. For example, you can customize the date format or obtain only a specific portion of the date. Date/time value references have the following syntax:
%propertyName[:format[]],[modifiers],[time],[utc]%
-
[:format[]]
-
Specifies the date/time format of the resulting value, for example, dd/MM/yy hh:mm:ss. Use the custom format specifiers to set the required format. To use a specifier character literally, escape it with a backslash (\).
-
[,modifiers]
-
Adds or substracts the specified number of years, months, days, hours, minutes, or seconds from the resulting value. For example, to add one year and 6 months, specify %whenCreated,+1y+6M%.
-
[,time]
-
Specifies the time to use in the resulting value. If included, this parameter will take precedence over the time value in the referenced property and any time modifiers.
-
[,utc]
-
Converts the resulting value to the UTC time zone.
Examples
Let's assume that the value of the When Created property in these examples is May 4, 2022 12:00:00.
-
%whenCreated,,05:00% will be replaced with the value of the When Created property, but the time of the resulting value will be set to 5:00 AM.
%whenCreated,,05:00% => 05/04/2022 05:00:00 -
%whenCreated,+2M% will be replaced with the value of the When Created property plus 2 months.
%whenCreated,+2M% => 07/04/2022 12:00:00 -
%whenCreated:format[yyyy-MMMM-dd, hh:mm]% will be replaced with the value of the When Created property in the following format: 2022-May-04, 12:00.
%whenCreated:format[yyyy-MMMM-dd, hh:mm]% => 2022-May-04, 12:00 -
%whenCreated:format[timestamp]% will be replaced with a timestamp representing the number of 100-nanosecond intervals since January 1, 1601 (UTC) up to the date specified in the When Created property.
%whenCreated:format[timestamp]% => 132961716000000000
Value references in scripts
When value references are used in PowerShell scripts, Adaxes sanitizes the resulting values to prevent code injection. For this reason, value references that reference string properties must be enclosed in double quotes (" character) instead of single quotes.
# CORRECT: value reference will properly resolve and sanitize the value
$value = "%myProperty%"
# This is INCORRECT
$value = '%myProperty%'
Aliases
Out of the box, Adaxes provides aliases for frequently used properties. You can use aliases instead of property names in value references.
For example, for the value of the cn property, you can use either the %cn% or %fullname% value reference.
Calculated properties
Adaxes has the so called calculated or virtual properties. They are not stored anywhere but are rather calculated on the fly. Value references can be used to get the values of calculated properties just like any other properties. For instance, %adm-CurrentDateTime% doesn't refer to any physical property value. Instead, it is replaced with the current date and time when it resolves.
For more details about calculated properties and the full list of them, see Calculated properties.
Building DNs with value references
Microsoft Entra objects in Adaxes have a distinguished name (DN), just like objects from Active Directory. However, the DNs of Microsoft Entra objects contain their GUID to make the DN unique, because Microsoft Entra ID allows creating multiple objects with the same name. For example:
CN=Sales Staff\0AUID:952322ad597f4b1bb4ce40360a1bc07c,OU=Gropus,DC=example,DC=onmicrosoft,DC=com
CN=Sales Staff\0AUID:86ecfb68226f43e295fe50a370b9db31,OU=Gropus,DC=example,DC=onmicrosoft,DC=com
When you use value references in templates to build object DNs, the GUID can be omitted. Adaxes will still recognize such a DN as a valid DN.
CN=%department% Staff,OU=Groups,DC=example,DC=onmicrosoft,DC=com
However, if multiple objects in Microsoft Entra ID have the same name (e.g. two groups named Sales Staff) and are located in the same container in Adaxes, the DN generated by such a template will match several objects. In this case, Adaxes will pick the first object it encounters.