Email templates in database

Overview

With the previous builds, email templates are stored in flat files requires local web server access right to edit them. From 5.1.1 Moonlight release, all email templates are moved into database and admin user can edit them easily using the Identify Admin, it is very convenient especially in web farm environment. Beside support changing content of email's subject and body, we also support inserting data to merge fields in email template so that user data (user name, organization and claim values,...) can be appeared in the sending message.

Moreover, we support more APIs to create/edit an email template or an email server, send reset password email to an user, send an email to an user with a specified email template, send an email to a user with a customized email server and email template.

Structure of an email template

An email template is stored in database as a field configuration (System Setup -> Field Configurations)

ResetPasswordTemplateNew

This field includes following main parts:

Name: name of email template
Resource Key: Because this Field Configuration is used for an email template so value of Resource Key is EmailTemplate
Expression: content of email template

Content of an email template has structure as below:

<?xml version="1.0" encoding="utf-8" ?>
<mails name="ResetPasswordTemplateNew">
<mail>
  <from>noreply@safewhere.com</from>
  <to><![CDATA[<%=sendToMail%>]]></to>
  <bcc></bcc>
  <cc></cc>
  <subject><![CDATA[Password change request for user account: <%=identityBearingClaimValue%>]]></subject>
  <encoding>text</encoding>
  <bodyIsHtml>true</bodyIsHtml>
  <sendAsync>false</sendAsync>
  <body>
    <![CDATA[Dear <%=userName%>,
    <br /><br />
    We have received your password change request. This email contains the information that you need to change your password.
    <br /><br />
    Click this link to <a href="<%=resetPasswordLink%>">enter your new password.</a>
    <br /><br />
    Kind regards,
    <%=organizationName%>
    <br /><br />
    <b>Replies to this message are undeliverable and will not reach <%=organizationName%>. Please do not reply.</b>]]>
  </body>
</mail>
</mails>

With:

Name: is name of email template, it should be same as Name (1.)
Subject: is subject of an email
Body: is body of a email

Merge fields

A merged field in an email template is used to fill property of user that do sending email action. Value of a merged field is depend on user. The syntax is <%=merged_field name%>.

Ex: <%=userName%> is used to fill user name or <%=organizationName%> is used to fill organization of user

At the current Identify supports some of email templates for specific business use cases such as ResetPassword. This means that each of those templates supports a number of special merged fields, e.g. password or resetpasswordlink. Please prefer to Existing Email templates part for more detail

From Identify 5.1.1 Moonlight release build, Identify supports claim type merge fields into an email template. This means that admin can add many claim types to an email template to display user's claim value by using this merged field. A merged field for claim type must start with the prefix "claim:" as <%=claim:claim_type_name%>

Ex: <%=claim:urn:email%>

If claim type is a multiple claim values, all selected values will be displayed and separated by ","

A new email template will be supported following merged field:

<%=userName%>: is value of Display name from Edit User form.

<%=organizationName%>: is value of Owner Organization from Edit User form.

<%=claim:claim_type_name%>: claim type in Identify.

Existing email templates

This list describes email templates are being supported by Identify. These email are used in special scenario, so each of email support some specified merged fields.

Template name	Description
ExpiredUserPassword	This template is used when a user that has expired password try to reset his password by request a reset email password (click "Forgot password? Click here!" link in Username & password form then input necessary information) Supported merged fields are: <%=userName%>: is value of Display name from Edit User form. <%=organizationName%>: is value of Owner Organization from Edit User form. <%=claim:claim_type_name%>: claim type in Identify
LdapResetPasswordRequestTemplate	This template is used when an user in Active Directory want to reset his password through Identify. ( click link "Forget password? Click here!" link in LDAP connection form) Supported merged fields are: <%=userName%>: will get value of field "name" in "Active Directory" <%=resetPasswordLink%>: link to reset password. <%=organizationName%>: will get value of Domain in LDAP Authentication connection <%=claim:distinguishedName%>: will get value of field "distinguishedName" in "Active Directory" <%=claim:mail%>: will get value of field "mail" in "Active Directory" <%=claim:samAccountName%>: will get value of field "samAccountName" in "Active Directory" <%=claim:givenName%>: will get value of field "givenName" in "Active Directory" <%=claim:sn%> will get value of field "sn" in "Active Directory" <%=claim:organization%>: will get value of Domain in LDAP Authentication connection
ResetUserPassword	When receive email from LdapResetPasswordRequestTemplate, click Link in email. Supported merged fields are: <%=userName%>: will get value of field "name" in "Active Directory" <%=password%>: new password
ResetPasswordTemplate	This template is used to send email contain a link to reset password. (Right click User -> Send Password) Supported merged fields are: <%=userName%>: is value of Display name from Edit User form. <%=organizationName%>: is value of Owner Organization from Edit User form. <%=resetPasswordLink%>: reset password link <%=claim:claim_type_name%>: claim types in Identify
ResetPasswordTemplateNew	This template is used when an user try to reset his password by request a reset email password (click "Forgot password? Click here!" link in Username & password form then input necessary information) Supported merged fields are: <%=identityBearingClaimValue%>: Value of this field is gotten from field [Name…] of Reset password from <%=userName%>: is value of Display name from Edit User form. <%=organizationName%>: is value of Owner Organization from Edit User form. <%=resetPasswordLink%>: reset password link <%=claim:claim_type_name%>: claim types in Identify
SendCorrelationErrorTemplate	This template is used to send Correlation Error to admin user. Supported merged fields are: <%=correlationID%>: ID of correlation error<%=source%>: source occurs error <%=issusedTime%>: time that happens error <%=link%>: link to detail of error <%=claim:claim_type_name%>: do not support
SendOtpCodeTemplate	This template is used to send OPT code to user. Supported merged fields are: <%=otpCode%>: OTP code <%=claim:claim_type_name%>: do not support
SendResetPasswordTemplate	This template is used when a new user is created. Supported merged fields are: <%=userName%>: is value of Display name from Edit User form. <%=organizationName%>: is value of Owner Organization from Edit User form. <%=resetPasswordLink%>: reset password link <%=claim:claim_type_name%>: claim types in Identify
SendPasswordTemplate	This template is not used by Identify Admin.
WelcomeNewUser	This template is not used by Identify Admin.
NotifyUsersWhenAuthenticatorsChange	This template is used to notify users of changes made to their authenticators, such as adding, changing, or removing authenticators from their account. Supported merged fields are: <%=userName%>: is value of Display name from Edit User form. <%=otpType%>: is an authenticator type, it is one of these values: - TOTP Authenticator app - WebAuthn (Windows Hello, biometrics, FIDO2, FaceID etc.) - Device authentication Notes: It may include multiple authenticator types, separated by a comma (", "), when performing a mass reset of a user's authenticators. <%=changeType%>: possible values include Registration, De-registration and Update. <%=changedDateTime%>: represents the date and time (in UTC) when the user's authenticator(s) were changed. <%=clientIPAddress%>: the client IP address that initiated the action. <%=organizationName%>: is value of Owner Organization from Edit User form.
NotifyUsersWhenPasswordChange	This new email template is used to notify users when their passwords have been changed. Supported merged fields are: <%=userName%>: is value of Display name from Edit User form. <%=changedDateTime%>: represents the date and time (in UTC) when the user's authenticator(s) were changed. <%=clientIPAddress%>: the client IP address that initiated the action. <%=organizationName%>: is value of Owner Organization from Edit User form.

How to edit an email template

In order to edit an email template form UI do following steps:

Select System Setup > Field Configurations
In All field configurations list, select an email template that want to edit

Edit the subject and body of the template in Expression.
Click Save to save the change

Example:

User Test 0013 has name, organization and claim types as below:

And admin user want to edit email template ResetPasswordTemplate with content (*) as below

<?xml version="1.0" encoding="utf-8" ?>
<mails name="ResetPasswordTemplate">
<mail>
  <from>noreply@safewhere.com</from>
  <to><![CDATA[<%=sendToMail%>]]></to>
  <bcc></bcc>
  <cc></cc>
  <subject><![CDATA[Safewhere Identify - password has been reset for user account: <%=userName%>]]></subject>
  <encoding>text</encoding>
  <bodyIsHtml>true</bodyIsHtml>
  <sendAsync>false</sendAsync>
  <body>
    <![CDATA[Dear <%=userName%>,
    <br /><br />
    You account with <i><%=organizationName%></i> has had its password reset. 
    <br /><br />
    Please click the following link to set a new password.
    <br /><br />
    <a href="<%=resetPasswordLink%>">Click here to update your password.</a>
    <br /><br />
    Kind regards,
    <%=organizationName%>
    <br /><br />
    <b>Replies to this message are undeliverable and will not reach <%=organizationName%>. Please do not reply.</b>]]>
  </body>
</mail>
</mails>

He does the following steps:

Select System Setup > Field Configurations
In All field configurations list, select ResetPasswordTemplate email template
Input above content (*) to Expression field in Edit Field Configuration form.
Click Save to save the change
Do action to send an email that use the template (Right click user Test 0013, select Send Password)

The received email will be:

REST API for email templates and email server

Identify supports more APIs to create/edit an email template as below:

And also supports following APIs to create/edit/delete an email server:

Sending emails with REST API

When a user is created or admin user want to reset password of a user, sending a reset password email to user can help user update his password in a safe way.

With new users, Identify supports sending email out when creating a new user by adding a parameter sendPasswordEmailToUser into sending request of following APIs:

post  /api/rest/v2/users/.batch

post  /api/rest/v2/users

Like this:

https://identifyanyid02.safewhere.local:443/admin/api/rest/v2/users?sendPasswordEmailToUser=true

https://identifyanyid02.safewhere.local:443/admin/api/rest/v2/users/.batch?sendPasswordEmailToUser=false

If sendPasswordEmailToUser = false, the email to reset user password will not be sent.

If sendPasswordEmailToUser = true, the email to reset user password will be sent, the user will receive an email with a link to update his password – of course only if the user has a valid email specified with the account and the email server is setup successfully.

And the default value of sendPasswordEmailToUser is false.

With existing users, Identify supports sending an email to a specified user to reset his password

Besides, Identify also supports sending an email to a specified user with a specified template or a customized email template and email server.

The supported methods are: