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_EXTIDUSER_LOGINIDUSER_TITLEUSER_FIRSTNAMEUSER_NAMEUSER_SEXUSER_SALUTATIONUSER_ADDRESSLINE1USER_ADDRESSLINE2USER_CITYUSER_POSTALCODEUSER_COUNTRYUSER_COUNTRY_NAMEUSER_COUNTRY_NAME_DEUSER_COUNTRY_NAME_ENUSER_COUNTRY_NAME_FRUSER_COUNTRY_NAME_ITUSER_TELEPHONEUSER_TELEFAXUSER_MOBILEUSER_EMAILUSER_MAINUSERS_EMAILUSER_LANGUAGEOptional placeholders for address extension (eCH-0010), available only if feature is enabled per client policy: USER_STREETUSER_HOUSE_NUMBERUSER_DWELLING_NUMBERUSER_POBOX_NUMBERUSER_POBOX_TEXTUSER_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_COUNTRYis the two-letter country code (example: CH, HU).USER_COUNTRY_NAMEis the country name in the user's language (example: Switzerland, Hungary if the user's preferred language was English).USER_COUNTRY_NAME_ENand similar are the country names in corresponding languages (e.g., Switzerland, Hungary).USER_MAINUSERS_EMAILis 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_NAMECRED_VALIDFROMCRED_VALIDTOCRED_PROP_PROPERTYNAMEPUKCRED_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.