Skip to content

Using Email Templates

Many system activities send emails to notify users of process milestones and tasks assigned to them. Default templates are provided for each email type, but they are customizable to your business needs.

The email templates are defined using the Apache Velocity templating syntax. This allows the emails to support variable substitutions as well as simple logic like conditional contents. Each email template includes a fixed set of notification-specific variables which can be used in this substitution process.

Note

Some variables are objects containing multiple properties or fields. To reference those properties in an email template, use the syntax: ${<objectVariable>.<property>}. For example, if you want to reference the user's work phone number in an email, you would enter ${user.workPhone}.

Global Variables - Version 1 and 2 Templates

In addition to notification-specific variables, IdentityNow provides a common set of global variables to email notifications. IdentityNow’s notification process is undergoing a migration, so each template is classified as version 1 or version 2. The two groups have access to different sets of global variables.

Version 1 Templates

Most email templates are version 1 templates. All version 1 email templates are provided these global variables.

Name Description Attributes or Functions
user The email recipient's identity data Any attribute of the identity including, but not limited to, name, alias, firstname, lastname, displayName, uid, manager, phone, workPhone
identityNowUrl URL to the IdentityNow homepage N/A
PRODUCT_NAME The name of the product N/A
spTools SailPoint utility class to support date formatting formatDate()

SPTools Date Formatting

When a version 1 email template is provided a date variable, you can use the spTools.formatDate() function to define how the date is printed in the email. You can pass in different arguments to specify the formatting in different ways.

Note

The variable used in the examples below, $certification.expiration, is taken from the Certification email template. The examples illustrate how to use the formatDate() function to print it in various formats.

Arguments Example Return Value
Date $spTools.formatDate($certification.expiration) The date-time in short format (all numeric) for the locale and timezone of the tenant.
Example: 12/13/22 3:30 PM
Date, format string $spTools.formatDate($certification.expiration, "MM/dd/yyyy HH:mm") The date-time formatted in the Java date pattern specified.
Example:12/13/2022 15:30
Date, date style, time style $spTools.formatDate($certification.expiration,3,1) The date-time formatted for the specified style numbers (see below).
Example:12/13/22 3:30:26 PM CST

Syntax Requirements:

  • In all cases, both the spTools variable and the date variable must be prefixed with the $ symbol.
  • When using the format string option, the pattern must be specified in quotes.
  • When using the date and time styles, specify the styles as integers from 0 to 3, as follows:

    Integer Meaning Examples
    0 full format Tuesday, December 13, 2022 and
    3:30:26 PM Pacific Standard Time
    1 long format December 13, 2022 and 3:30:26 PM PST
    2 medium format Dec 13, 2022 and 3:30:26 PM
    3 short format 12/13/22 and 3:30 PM

Version 2 Templates

The version 2 templates are:

  • All Non-employee email templates
  • Campaign Template Pre-Generation Notification
  • Pending Task Daily Digest

Version 2 templates are instead provided these global variables. The first three provide system data to the templates while the other three provide functions that template authors can use for customizations. Note that all of these variable names start with a double underscore.

Name Description Attributes or Functions
__global General system variables productName, emailFromAddress
__recipient Abbreviated set of identity data for the email recipient name, id, email, phone
__contentJson A JSON representation of the event which caused this notification Varies per event/template
__dateTool VelocityTools class for date calculation and formatting Refer to DateTool documentation
__numberTool VelocityTools class for number formatting Refer to NumberTool documentation
__util SailPoint utility class to support data retrieval getUser(), getObjectByJsonPath()

Note

Some variables in the default text for version 2 templates begin with a single underscore (_variableName). This naming convention was adopted to denote calculated variables in these templates, but use of that notation in your custom template text is optional.

Util Functions
In the version 2 templates, you can use the $__util variable to access data through these utility class functions.

Function Arguments Returns
getUser() An identity ID (a system-generated unique identifier) An object representation of the user, containing its ID, name, email, and phone attributes
getObjectByJsonPath() two arguments: a variable containing a JSON blob and a JSONPath expression The value from the JSON variable corresponding to the JSONPath location

For example, the email template lines below would (1) retrieve a request approver's ID from the JSON provided to the email template in the $__contentJson variable, (2) use that to retrieve user data about the approver such as their name and email address, and (3) print that information into the email message.

  1. #set($approverId = $__util.getObjectByJsonPath($__contentJson, '$.data.approvalItems[*].approver.id'))
  2. #set($approver = $__util.getUser($approverId))
  3. The request is awaiting approval by $approver.name.

Available Templates

The table below shows currently available email templates. Select a template name in the table to view the default template contents and the list of its notification-specific variables.

Important

Customized email templates are not updated when SailPoint makes changes to the default template text, even if you revert the template contents to the default text. To reset a customized template to the default settings so that future template updates will be auto-applied, you must contact SailPoint Support.

Template Description
Access Profile Owner Approval Notification Sent to access profile owners when their access profile is granted to a user as a result of a role request.
Access Request Cancelled Sent to users when a pending access request is canceled before it has been approved and provisioned.
Access Request Decision Sent to a user to notify them whether their request for an app was approved or denied.
Access Request Decision for Other Sent to a user when access was requested for them by another user, and the reviewer of that request has made a decision.
Access Request Failed - Multiple Accounts Notifies a requester that their access request failed because the selected identity has multiple accounts on the source.
Access Request for Other Sent to users when access was requested for them by another user.
Access Request for Self Sent to users to confirm that they've successfully submitted an access request for themselves.
Access Request Reassignment Sent to a reviewer when they have had access requests reassigned to them.
Access Request Reviewer Sent to each access reviewer who needs to review an access request.
Access Request Sunset Date Reminder Sent to a user to remind them that their access to an item is coming to an end.
Access Request Validated - For Requester Notifies a requester of which access requests were successfully submitted and which failed during the validation process.
Access Revoke Approval Reassignment Notifies a user when an access revoke request has been reassigned to them.
Access Revoke Request Decision (Recipient) Notifies a user when a reviewer has made a decision on their access in an access revoke request.
Access Revoke Request Decision (Requester) Notifies a requester when a user has reviewed their access revoke request.
Access Revoke Request Reviewer Notifies a user that they have an access revoke request to review.
Access Revoke Request Submitted (Recipient) Sent to the identity whose access is being reviewed in an access revoke request.
Access Revoke Request Submitted (Requester) Notifies a user that they successfully submitted an access revoke request.
App Password Changed Only used if pass-through authentication is configured. Sent when a user changes their login password, or the password for any app or direct connect source connected to the source used for pass-through authentication.
Application Health Sent when an application changes status. This is a system notification email.
Certification Sent to reviewers whenever a certification campaign is created.
Certification Due Sent to certification reviewers one week after a certification campaign starts and every seven days after that, until they sign off or the campaign ends.
Certification Reassignment Notifies a reviewer when they have been reassigned identities from an existing certification.
Forgot User Name Sent when a user selects Forgot User Name on the Sign In page and then supplies an email address that is valid for their account.
Helpdesk Password Reset Sent when a user requests a password reset via email.
Identity Errors Sent when identity processing causes 5% or more of identities to be in an error state. This is a system notification email.
Lifecycle State Change Sent to select users when an identity's lifecycle state changes.
New Account Provisioned Sent to a user when an account is created on a source for them.
Non-Employee Account Request Sent to a non-employee account manager to confirm that their request for a new account for a non-employee was submitted.
Non-Employee Account Request Decision Sent to an account manager when all applicable account reviewers have made a decision about a non-employee account, to confirm that their account request was either approved or denied.
Non-Employee Account Review Sent to the account reviewers to notify them that a request needs their attention, after a new non-employee account request is submitted.
Non-Employee End Date Reminder Sent to the account managers for a non-employee source when one or more of the non-employees on that source has an end date in 7 days.
Preference Update Sent whenever a user’s authentication settings, like phone number or answers to security questions, change.
Password Expiration Sent when a user's password is about to expire or has expired.
Password Reset Code Sent when a user requests a password reset code via email.
Pending Task Daily Digest If enabled, sent to users daily when they have incomplete tasks in their Task Manager.
Scheduled Certification Campaign Reminder Sent to the person who created a scheduled certification campaign 1 week prior to the scheduled generation date.
Search Subscription Notification Sent to administrators when a scheduled search is run.
SoD Policy Subscription Notification Sent to remediators or notification recipients for SoD Policies.
Source Health Sent when a source changes status. This is a system notification email.
Strong Authentication Sent when a user wants to use strong authentication when using an email.
Unlock User Code Sent when a user selects Unlock on the Sign In page to provide a code that is used to unlock the account.
User Invitations Sent to invite a user to use IdentityNow.
User Locked Out Notifies a user that their account has been locked out due to too many failed sign in attempts.
User Password Changed Sent when a user from any app or source that does not use pass-through authentication changes their IdentityNow password.
User Unlocked Sent after the Unlock User Code email to confirm that the account was unlocked successfully.
User Verification Token Sent when an administrator or Helpdesk admin resets a user's SailPoint password, or their password for a source.
Virtual Appliance Health Sent when a virtual appliance changes status. This is a system notification email.

Customizing Email Templates

You can customize the subject and body of email templates, as well as designate “Reply To” email addresses specific to each one. You can also customize the “From” address for IdentityNow emails.

Tip

Org Admins can also manage email templates through our APIs.

Editing the Email Contents

  1. From the Admin interface, select Global > Email Templates. Choose the email template you wish to edit.

  2. Edit the Subject and Body text to meet the needs of your organization.

    • Emails are HTML-enabled. In addition to text edits, the default WYSIWYG editor for the email body supports formatting options through icons and menus which appear above the text box.

    • Select the Source Edit icon at the far right of the formatting bar to edit the message as HTML. This allows advanced-level specification of your preferred formatting.

    • Review the variables available to each template and reference them as needed in the message contents using the appropriate Velocity variable syntax.

  3. Select Save.

Caution

  • To ensure that your email renders correctly for your users, SailPoint recommends that you always test you email template changes.
  • The WYSIWYG editor cannot render tables. If the email template includes a table, you can still edit the HTML source for the template. To reenable the WYSIWYG editor, remove every table references by deleting all blocks between \<table> and \</table> tags.

Using Images in Email Templates

To insert an image into an email template:

  1. Find the section(s) of the email where you want the image to appear.

    If the Velocity scripting in the email includes conditional content based on system and user data, you might need to add the image to multiple sections of the template body.

  2. Identify the URL of a hosted image reference.

    Best Practice

    When adding logos to email templates, you may use any external internet-accessible image, but SailPoint recommends using the logo image you used when customizing your UI.

    To use this image, right-click the logo in the top left corner of your IdentityNow site and choose Copy image address to copy the URL. The exact menu label, such as Copy image address/link/location, depends on your browser.

  3. In the email template, use tagging like:

    <div><p style="text-align:right"><img src="[URL]" width="150" ></p></div>

    where [URL] is the URL from step 2 above.

    This example, specified as the first line of the email template body, adds the image at the top right of the message above the text.

    Notes

    • You can add the HTML for an image directly in the standard text box or through the HTML source editor.
    • Unless you are certain of your image’s dimensions, it is best to specify only a width or a height and allow the image to auto-scale accordingly.
  4. Select Save and then test the email to verify that your changes have been applied. 

Embedding Base 64 Encoded Files

If you have experience with base-64 encoding, you can also embed a base-64 encoded file for the image src instead of referencing a URL.

Be aware that embedding an image increases the overall size of your email message. Many email servers block email messages larger than a particular size. To lessen the chance of a bounced email when using embedded images, scale your image down to the same size as your desired height and width settings first, and then base-64 encode the scaled image.

Setting the Reply To Address

Each template can have its own “Reply To” email address, specified in the Reply To field on the template's configuration page. This determines the email address that appears in the To field when a user replies to an email sent from IdentityNow. This lets you direct users to the right enterprise contacts for help with a topic or process.

Setting the From Address

The “From” address is a global setting that applies to all emails sent from IdentityNow, rather than varying by template. You can set a single “From” address for your whole org, or you can specify one per brand when you configure brands within your tenant. In that case, the "From" address used will be the one specified for the brand the recipient is part of.

Notes

  • You can assign up to 10 "From" addresses for each orgs.
  • Each email address can only be used as a "From" address for one org. If you need to reuse the same email address on multiple orgs, such as a staging org and a production org, contact SailPoint Support.

To change the "From" address:

  1. From the Admin interface, go to Global > System Settings. The Product Branding page is displayed.

  2. If you have multiple brands defined, select the Brand Identity Attribute for the brand you want to configure. If brands have not been set up, that option will be disabled, and this configuration will apply to all users in your org.

  3. Scroll to 'From:' Address.

  4. Email addresses used as "From" addresses must first be validated. To add and validate a new email address:

    • Select New.

    • Specify an email address and select Add.

    • Check email at that address. You will receive an email from AWS to confirm that you own that email address. Select the link in that email within 24 hours.

  5. Once the email has been validated, choose it from the Select a validated email list as the "From" address for the chosen brand or for the org.

  6. Select Save.

  7. Repeat these steps for all configured brands.

Important

If you change the "From" address, use one of the options outlined in Ensuring Successful Delivery of Emails to make sure employees can receive the emails.

"From" and "Reply To" Addresses

“Reply To” addresses that have not been customized per template will automatically match the “From” address when emails are sent. However, changes to the “From” address are not reflected in the Reply To field on each email template; that will still display no-reply@sailpoint.com for templates where it has not been overridden.

Removing a "From" Address

You can remove a "From" address from your org by selecting the X icon beside it in the All email addresses list. If the X icon beside an email address is disabled, the 'From' address is in use in one or more of your brands. Choose another email for those brands and try again.

Testing Email Templates

Test any email templates you have changed to verify that the content will display as intended when they are sent to your system users. You can do this per email template after you save changes.

  1. Within the Admin interface, navigate to Global > Email Templates.

  2. Choose the desired email template, edit as needed, and select Save.

  3. Select Test Email. The email message will be sent to the email address of the logged-in user.

Notes

  • Only global variables render within the generated test email because the other variables are populated by the process that triggers the email.
  • Conditional sections of the message are not included in the test emails.

Redirecting Emails

In non-production tenants, admins commonly redirect all emails to a test address rather than allowing them to be sent to business users. To configure this redirection:

  1. From the Admin interface, navigate to Global > Email Templates.

  2. Scroll to the bottom of the list and select Email Config.

  3. Choose Test Address:, enter the email address you want to use, and select Save.

An audit event is created whenever the test address is changed.

Caution

Use this option with care in a production environment. All emails will be redirected until you return to this page and choose Intended Recipients.

Stopping Automated Emails

Some system notifications can be enabled or disabled through process configurations. For example, you can choose to send or suppress emails related to:

You can also prevent IdentityNow from sending emails on a per-email-template basis by specifying any of the following keywords as the first word in the template’s Subject field:

  • #stop
  • no_send
  • Stop

Best Practice

Leave the rest of the subject text intact to simplify future reinstatement of the template.