The pattern of placeholders
The string pattern defining a placeholder follows certain rules:
- Placeholders are case-sensitive and contain exclusively upper-case letters.
- A placeholder always starts and ends with two underscores (
__
), except for ODT templates. In those templates, the starting and ending double underscores are not used. - Property names are converted into placeholders by removing any empty space, underscore and hyphen.
- Underscores within a placeholder are used to separate parent-child or element-attribute relations.
- A placeholder always has a context, which may be a certain user or a user's credential. For example, when resolving the placeholders within a mail template, it is already known that the mail will be sent to a certain user. Therefore, all placeholders are resolved in the context of that user.
Examples
The points above become clearer with some examples:
__USER_EMAIL__
: In this placeholder, USER is the object and EMAIL is an attribute of the user.__CRED_PROP_CERTPROP__
: CRED is the object and refers to a credential. PROP is a child object of the credential, the credential's property. And CERTPROP refers to the property's name. Due to rule 3, above, the effective name of the property may be "cert prop" or "cert-prop" or "cert_prop".
Placeholders for user attributes and properties
Most of the attributes defined on the user in the nevisIDM data model can be retrieved by means of placeholders as shown in the table below.
Document type | Available user placeholders |
---|---|
E-mail, HTMLemail template | __USER_EXTID__ __USER_LOGINID__ __USER_TITLE__ __USER_FIRSTNAME__ __USER_NAME__ __USER_SEX__ __USER_SALUTATION__ __USER_ADDRESSLINE1__ __USER_ADDRESSLINE2__ __USER_CITY__ __USER_POSTALCODE__ __USER_COUNTRY__ __USER_COUNTRY_NAME__ __USER_COUNTRY_NAME_DE__ __USER_COUNTRY_NAME_EN__ __USER_COUNTRY_NAME_FR__ __USER_COUNTRY_NAME_IT__ __USER_TELEPHONE__ __USER_TELEFAX__ __USER_MOBILE__ __USER_EMAIL__ __USER_MAINUSERS_EMAIL__ __USER_LANGUAGE__ __NEW_EMAIL__ Optional placeholders for address extension (eCH-0010): __USER_STREET__ __USER_HOUSE_NUMBER__ __USER_DWELLING_NUMBER__ __USER_POBOX_NUMBER__ __USER_POBOX_TEXT__ __USER_LOCALITY__ (info) In case of HTMLemail, the placeholder values will be HTML escaped. |
OpenOffice template | USER_EXTID USER_LOGINID USER_TITLE USER_FIRSTNAME USER_NAME USER_SEX USER_SALUTATION USER_ADDRESSLINE1 USER_ADDRESSLINE2 USER_CITY USER_POSTALCODE USER_COUNTRY USER_COUNTRY_NAME USER_COUNTRY_NAME_DE USER_COUNTRY_NAME_EN USER_COUNTRY_NAME_FR USER_COUNTRY_NAME_IT USER_TELEPHONE USER_TELEFAX USER_MOBILE USER_EMAIL USER_MAINUSERS_EMAIL USER_LANGUAGE Optional placeholders for address extension (eCH-0010), available only if feature is enabled per client policy: USER_STREET USER_HOUSE_NUMBER USER_DWELLING_NUMBER USER_POBOX_NUMBER USER_POBOX_TEXT USER_LOCALITY |
SMS template | __USER_EXTID__ __USER_LOGINID__ __USER_TITLE__ __USER_FIRSTNAME__ __USER_NAME__ __USER_SEX__ __USER_SALUTATION__ __USER_ADDRESSLINE1__ __USER_ADDRESSLINE2__ __USER_CITY__ __USER_POSTALCODE__ __USER_COUNTRY__ __USER_COUNTRY_NAME__ __USER_COUNTRY_NAME_DE__ __USER_COUNTRY_NAME_EN__ __USER_COUNTRY_NAME_FR__ __USER_COUNTRY_NAME_IT__ __USER_TELEPHONE__ __USER_TELEFAX__ __USER_MOBILE__ __USER_EMAIL__ __USER_MAINUSERS_EMAIL__ __USER_LANGUAGE__ Optional placeholders for address extension (eCH-0010), available only if feature is enabled per client policy: __USER_STREET__ __USER_HOUSE_NUMBER__ __USER_DWELLING_NUMBER__ __USER_POBOX_NUMBER__ __USER_POBOX_TEXT__ __USER_LOCALITY__ |
Refer to the chapter Data Model, where the attributes of users are listed.
The placeholder USER is deprecated. Use USER_EMAIL instead.
User properties
Properties of a user can be referred to as mentioned earlier:
__USER_PROP_PROPERTYNAME__
, where PROPERTYNAME is the simplified name of the property according to the previously mentioned rule 3. It is also possible to use the property placeholders as address fields in e-mail templates. It is the up to the administrator to make sure that the property is a valid e-mail address.USER_COUNTRY
is the two-letter country code (example: CH, HU).USER_COUNTRY_NAME
is the country name in the user's language (example: Switzerland, Hungary if the user's preferred language was English).USER_COUNTRY_NAME_EN
and similar are the country names in corresponding languages (e.g., Switzerland, Hungary).USER_MAINUSERS_EMAIL
is a semicolon-separated list of e-mail addresses of all main users of the current deputy user. This placeholder is useful for example as a carbon copy (cc), when the main users have to be notified about sub-user communication.
User salutation and country names
For the supported application languages German, English, French and Italian, the placeholders USER_SALUTATION and USER_COUNTRY_NAME are by default translated in the preferred user language. In case you have configured any other language, you can add the corresponding translations for the above mentioned placeholders as a custom message resource. Put the translations for each additional language in a file with the following name pattern: custLitDict_<languageCode>.properties
.
The property file custLitDict_<languageCode>.properties
will be read with UTF-8 encoding.
The following example shows the Spanish translations for the salutation and user country name placeholders, in the file custLitDict_es.properties
:
user.salutation.F=Estimada Sra
user.salutation.M=Estimado Sr
user.salutation.null=Estimado Sra/Sr
form.countries.es=España
If the "other" gender option is enabled in the Client Policy, it will use the translation of placeholder user.salutation.null
.
Store the custom message resource files in the directory web.gui.messageresource.dir
(as configured in the file nevisidm-prod.properties
- see also the table describing the nevisidm-prod.properties file in Configuration files).
Placeholders for credential attributes and properties
Only a small set of credential attributes can be referenced by means of placeholders as shown below. However, there are certain special placeholders which allow referencing to new passwords, reset codes, etc. The special placeholders are explained in the chapter Special placeholders.
Document type | Available credential placeholders |
---|---|
E-mail, HTMLemail, SMS template Certificate policy | __CRED_NAME__ __CRED_VALIDFROM__ __CRED_VALIDTO__ __CRED_PROP_PROPERTYNAME__ __PUK__ __CRED_EXTID__ |
OpenOffice template | CRED_NAME CRED_VALIDFROM CRED_VALIDTO CRED_PROP_PROPERTYNAME PUK CRED_EXTID |
Credential properties
Credential properties are referenced as it is done for user properties. For example, if the certificate credential has the property "certID", one could refer to this property with __CRED_PROP_CERTID__
.
Special placeholders
The following variables have special semantics and can only be used with the indicated feature of nevisIDM.
The placeholder __ADMIN__
is deprecated. Instead, use __ADMIN_EMAIL__
.
Placeholder | Document type | Description |
---|---|---|
__CURRENT_DATE__ | OpenOffice template | Current date |
__LINK__ | E-mail, HTMLemail template for URL ticket credentials | Personalized URL of the one-time URL ticket credential. |
E-mail,SMS and OpenOffice template for ticket and temporary strong password credentials. | Replaced by the referrer URL calculated of the request. Deprecated: Replacement does not work if combined with URL mappings of reverse proxies. Instead, write the required URL directly into the template. Only usable if JavaScript is enabled. | |
__NEW_EMAIL__ | E-mail, HTMLemail template | Used by selfAdmin GUI e-mail verification process, when client policy parameter gui.selfadmin.email.change.verify and gui.selfadmin.email.change.allowed are set to true. E-mail templates for the communication event SelfadminTicketNotification can use this placeholder. |
__NEW_MOBILE__ | SMS template | Used by the mobile verification process of the Self administration GUI (selfAdmin). SMS templates for the communication event SelfadminMobileNotification can use this placeholder. |
__RESET_CODE__ | E-mail, HTML email, SMS and OpenOffice template | Password reset code. The initial password as well as re-generated passwords are referenced by this placeholder. |
__TICKET__ | E-mail, HTMLemail, SMS and OpenOffice template | Ticket string |
__ADMIN_EMAIL__ | E-mail, HTMLemail template | E-mail addresses of the user’s administrators. User adminstrators are all users with the UserAdmin permission for this user. |
__WARNING_DAYS_UNTIL_ DISABLE_USER__ | E-mail, HTMLemail template | The job UpdateUserStateJob may send out deactivation warning mails. The value of this placeholder is the configured grace period (daysGracePeriod). |
External placeholders
The values for all above mentioned placeholders are generated by nevisIDM or resolved from the database. Starting from nevisIDM version 2.79 so called external placeholders are also allowed. For these, the values are not resolved or generated by nevisIDM but provided by a client calling nevisIDM. For example, you can create an email template with the placeholder __EXTERNAL_CITY__
and, you can provide the value for the placeholder using the notification REST API of nevisIDM. All placeholders must start with the EXTERNAL prefix.