Advanced placeholders

Placeholders such as ${user.email} or ${device.model} are used in several places in Relution, for example in device names, certificates, Exchange accounts or app configurations. The underlying template engine FreeMarker provides additional functions that allow placeholders to be customized further.

Substrings #

The notation [start..*length] extracts only a portion of a value: at most length characters from position start. Counting starts at 0. If the value is shorter, correspondingly fewer characters are inserted; if it is empty, none. This requires start not to lie beyond the end of the value; otherwise the substitution fails as with [start..end] (see the note below).

• ${user.givenName[0..*1]} → first letter of the given name
• ${device.model[0..*2]} → first two characters of the device model

Example: ${user.givenName[0..*1]}${user.surname[0..*1]}-${device.model[0..*2]}-${(device.custom1)!"00000"} results in MM-iP-00042 for a user account “Max Mustermann” with a custom1 value of 00042 on an iPad12,1.

Default value for unset fields #

If a field is not set, a default value can be provided using the ! operator: ${(device.custom1)!"00000"}. If the custom field custom1 is not set, 00000 is used instead of the placeholder remaining empty. A value that is set but empty, however, counts as present: the default value does not apply and the placeholder remains empty.

Case conversion and character replacement #

Using ?lower_case or ?upper_case, a value is converted entirely to lower or upper case. With ?replace("old", "new"), individual characters or character sequences can be replaced, for example to resolve umlauts for systems that do not allow special characters in user names:

${user.surname?lower_case?replace("ä","ae")?replace("ö","oe")?replace("ü","ue")?replace("ß","ss")}

Using the local part of an email address #

To use only the part before the @ sign of ${user.name} (or ${user.email}), several variants are available:

• ${user.name?keep_before("@")}
• ${user.name?split("@")[0]}
• ${user.name[0..user.name?index_of("@")-1]}

If the value contains no @, the first two variants return the complete value, while the third one fails. ?keep_before is therefore recommended.

User certificates #

Placeholders of the form ${user.certificate.…} insert the certificates stored on the user profile (section User Certificates) into a configuration as a base64-encoded string — for example into a managed app configuration whose fields expect a certificate as a base64 string. The placeholder is resolved when the configuration is transferred to the device, based on the user assigned to that device.

Three selection forms are available:

The subtype is the Category selected for the certificate on the user profile. The subtype is not case-sensitive.

Certificate names in square brackets #

For computed names, the inner placeholder is written without the surrounding ${…}, i.e. [device.serialnumber] instead of [${device.serialnumber}] — nested ${…} expressions are not supported. For names consisting only of letters, digits and underscores, the dot form ${user.certificate.EXCHANGE.iPhone} also works.

Password for PKCS#12 certificates #

For password-protected PKCS#12 certificates (e.g. an S/MIME identity), the import password is delivered via the reserved key password:

• ${user.certificate.SMIME_SIGNING.password}
• ${user.certificate.SMIME_SIGNING["my-certificate"].password}

For certificates that are not PKCS#12 containers, the value remains empty. Since password is a reserved key, a certificate that is itself named password cannot be selected via placeholders — both the dot form and the bracket form resolve to the password in this case. A different certificate name should be used instead.

Output format #

Regardless of the uploaded file format (PEM or DER), the placeholder always yields the base64-encoded DER form of the certificate. PKCS#12 containers are delivered base64-encoded as stored, so together with the password they can be imported directly by the receiving app. Other certificate types are also delivered as stored.

Example of a managed app configuration for an email client with S/MIME signing:

<key>SMIMECertificate</key>
<string>${user.certificate.SMIME_SIGNING}</string>
<key>SMIMECertificatePassword</key>
<string>${user.certificate.SMIME_SIGNING.password}</string>

Availability #

User certificate placeholders are intended for configurations whose content is delivered to the device of the assigned user, in particular managed app configurations (iOS/macOS, Android Enterprise), Knox configurations (Android Enterprise, Samsung KNS), custom configuration profiles (.mobileconfig) and Windows custom CSP. In these configurations, the portal also lists them under Available placeholders. They are not resolved (the placeholder remains empty) in device names, i.e. when renaming devices and in device name configurations for Apple and Windows, in Android Enterprise lock screen and support messages, work account setup and setup actions, in script environment variables, or in webhook actions of device groups. They are not supported for Linux configurations. In custom configuration profiles (.mobileconfig), the placeholder can only be used in string fields, not in data fields; in managed app configurations, both work.

If no certificate can be determined — for example due to an unknown subtype, a name that does not exist, or a missing user assignment — the placeholder remains empty and the configuration is still delivered. Details about the cause are recorded in the server log.

Notes #

Which base placeholders (e.g. ${user.email}, ${device.serialnumber}) are available in a specific configuration is shown in the configuration form or the respective dialog in the Available placeholders section. Clicking an entry copies it to the clipboard.

Values that are not set are inserted as an empty string. If, however, the evaluation of an expression fails — for example a slice [0..0] of a value that is set but empty or an unknown function name —, this does not only affect the individual placeholder: the entire text of the field or configuration is delivered unchanged, i.e. with all ${…} expressions unreplaced. The cause is logged in the server log.