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..end] extracts only a portion of a value. Counting starts at 0.

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

Example: ${user.givenName[0..0]}${user.surname[0..0]}-${device.model[0..1]}-${(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 empty fields #

If a field is empty or not set, a default value can be provided using the ! operator: ${(device.custom1)!"00000"}. If the custom field custom1 is not filled, 00000 is used instead of the placeholder remaining empty or causing an error.

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.username} (or ${user.email}), several equivalent variants are available:

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

User certificates #

Placeholders of the form ${user.certificate.…} insert the certificates stored on the user profile (Custom 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 available subtypes correspond to the functions on the user profile: GENERAL_CERTIFICATE, WIFI, EXCHANGE, VPN, SMIME_ENCRYPTION and SMIME_SIGNING.

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.

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 available in all placeholder-capable configurations for iOS, macOS, tvOS, Android Enterprise, Android, Windows, Samsung KNS and ChromeOS. 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 below the corresponding input field in the Relution Portal.