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)

EditFieldConfiguration

This field includes following main parts:

  1. Name: name of email template
  2. Resource Key: Because this Field Configuration is used for an email template so value of Resource Key is “EmailTemplate”
  3. Expression: content of email template

Content of an email template has structure as below:

<?xml version="1.0" encoding="utf-8" ?><mail name="ResetPasswordTemplateNew"><from>noreply@safewhere.com</from><to>

<![CDATA[<%=sendToMail%>]]></to>

<bcc/>

<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. Email <%=claim:uri:email%> and rest api role <%=claim:urn:identify:rest-api:role%> and <%=claim:http://schemas.microsoft.com/ws/2008/06/identity/claims/role%></b>]]>

</body>

</mail>

 

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 “Identify 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.xml 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 “Identify Name” from “Edit User” form<%=organizationName%>: is value of “Owner Organization” from “Edit User” form.<%=claim:claim_type_name%>: claim type in Identify
LdapResetPasswordRequestTemplate.xml 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.xml 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.xml 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 “Identify 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.xml 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 “Identify 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.xml 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%>: don’t support
SendOtpCodeTemplate.xml This template is used to send OPT code to user.
Supported merged fields are:<%=otpCode%>: OTP code<%=claim:claim_type_name%>: don’t support
SendResetPasswordTemplate.xml This template is used when a new user is created.
Supported merged fields are:<%=userName%>: is value of “Identify 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.xml This template is not used by Identify Admin.
WelcomeNewUser.xml This template is not used by Identify Admin.

 

How to edit an email template


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

  1. Select System Setup > Field Configurations
  2. In All field configurations list, select an email template that want to editEditFieldConfiguration
  3. Edit the subject and body of the template in Expression.
  4. Click Save or Save & Close to save the change

Example:

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

User_Identify Name

 

User_OwnerOrganization

User_MultiClaims

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

<?xml version="1.0" encoding="utf-8" ?><mail name="ResetPasswordTemplate"><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 />Your claims are: <br /><br /> uri:MultiDiscreteClaim:name2: <%=claim:uri:MultiDiscreteClaim:name2%> <br /><br /> uri:namebearing: <%=claim:uri:namebearing%> <br /><br />  uri:SingleDiscreteClaim:name1: <%=claim:uri:SingleDiscreteClaim:name1%> <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>

He does the following steps:

  1. Select System Setup > Field Configurations
  2. In All field configurations list, select “ResetPasswordTemplate” email template
  3. Input above content (*) to Expression field in [Edit Field Configuration] form.
  4. Click Save or Save & Close to save the change
  5. Do action to send an email that use the template  (Right click user Test 0013, select Send Password)   

The received email will be:

ReceivedEmail

REST API for email templates and email server


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

REST_API_EmailConfiguration_EmailTemplate

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

REST_API_EmailConfiguration_EmailServer

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://your_tenant.safewhere.local:443/admin/api/rest/v2/users?sendPasswordEmailToUser=true

https://your_tenant.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

Sending_email_resetpassword

 

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:

Sending_email_communication