Study guide

11.1 Customizing and Using Email Templates

SailPoint Certified IdentityIQ Engineer Exam

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: The IdentityIQ Engineer Exam

1.1 Exam Format, Official Blueprint, and Study Strategy

2 Chapter 2: Infrastructure, Installation, and Extended Attributes

2.1 IdentityIQ Infrastructure Components 2.2 Installation Steps and Procedures 2.3 Creating Extended Attributes and the Objects That Support Them

3 Chapter 3: Build, Deployment, Patching, Access, and Email

3.1 Ongoing Build and Deployment 3.2 Installing Patches and Performing Upgrades 3.3 Configuring End-User Access 3.4 Email Server Settings and Email Redirection

4 Chapter 4: Lifecycle Manager Configuration, Provisioning Policies, and Workflows

4.1 Configuring Lifecycle Manager 4.2 Identity Provisioning Policies 4.3 Configuring LCM Workflows

5 Chapter 5: Lifecycle Events, QuickLinks, Batch Requests, and Rapid Setup

5.1 Lifecycle Events and Their Workflows 5.2 QuickLinks and QuickLink Populations 5.3 Configuring and Using Batch Requests 5.4 Rapid Setup in Lifecycle Events and Identity Operations

6 Chapter 6: Certification Campaigns and Certification Rules

6.1 Configuring and Scheduling Certification Campaigns 6.2 The Purpose of Common Certification Rules

7 Chapter 7: Policies and Policy Violations

7.1 Configuring and Leveraging Policies 7.2 Responding to Policy Violations

8 Chapter 8: Reporting, Advanced Analytics, and Auditing

8.1 Executing and Leveraging Reports 8.2 Leveraging Advanced Analytics 8.3 Configuring and Using Auditing

9 Chapter 9: Rules, Rule Libraries, and the SailPoint API

9.1 The Purpose and Use of Rule Libraries 9.2 Rule Input and Output Arguments 9.3 Common SailPoint API Objects and Methods

10 Chapter 10: Workflow Development

10.1 Workflow Variables, Transitions, and Step Conditions 10.2 Workflow Steps That Generate Work Items 10.3 The Different Workflow Step Usages 10.4 Leveraging Sub-Workflows

11 Chapter 11: Email Templates, Branding, and Localization

11.1 Customizing and Using Email Templates 11.2 Branding the SailPoint User Interface 11.3 Localizing the SailPoint UI

12 Chapter 12: Application Definitions, Connector Settings, and Rapid Setup Aggregation

12.1 Configuring Application Definitions 12.2 Configuring Common Connector Settings 12.3 Configuring Rapid Setup Aggregation Settings

13 Chapter 13: Data-Loading Tasks and Application and Connector Rules

13.1 Scheduling Tasks for Data Loading and Processing 13.2 Common Application Rule Types 13.3 Common Connector Rule Types

14 Chapter 14: Debugging with log4j, Syslog, and the IdentityIQ Console

14.1 Configuring and Leveraging log4j 14.2 Configuring and Leveraging Syslog 14.3 Leveraging the IdentityIQ Console for Debugging

15 Chapter 15: Debug Pages and the Administrator Console

15.1 Leveraging the Debug Pages for Debugging 15.2 Leveraging the Administrator Console for Debugging

16 Chapter 16: Role Model and Identity Attribute Mappings

16.1 Default Role Models and Role Types 16.2 Configuring Roles and Role Options 16.3 Configuring Identity Attribute Mappings

17 Chapter 17: Data Objects, Relationships, and Group Types

17.1 Common IdentityIQ Data Objects 17.2 Relationships Between Common Data Object Models 17.3 The Difference Between Group Types

11.1 Customizing and Using Email Templates

Key Takeaways Explain This Topic AI

Default templates load from emailtemplates.xml and lcmemailtemplates.xml in WEB-INF/config; emailtemplatesSample.xml holds extra HTML examples that are not loaded.

Never edit a default template directly, because upgrades overwrite it; copy it, rename it, and associate the copy with the event.

Templates use Velocity (VTL): $variable references, #if/#foreach/#set directives, and the spTools helper for dates and message-catalog text.

A template can use only the arguments its event supplies; the Signature documents them, and HTML cannot be passed in as an argument value.

An HTML body must be wrapped in a CDATA block, and workflow-referenced templates can use every workflow variable and step argument.

Last updated: September 2026

Customizing and Using Email Templates

Objective 4.8 asks you to know how to customize and use email templates . Every IdentityIQ email, including work item assignments, reminders, certification notices, LCM notifications, and policy violation alerts, is generated from an EmailTemplate object.

Where Templates Come From

The defaults ship in identityiq_home/WEB-INF/config :

  • emailtemplates.xml – core templates
  • lcmemailtemplates.xml – Lifecycle Manager templates
  • emailtemplatesSample.xml – extra examples not loaded during initial setup, showing how to build HTML email

Once imported, templates are XML objects you can view in the Debug pages (EmailTemplate).

The Golden Rule of Customization

The default email templates should not be modified directly , because they can be overwritten during upgrades .

The documented process:

Copy and rename the template with a unique name, such as ACME Work Item Assignment .

Edit the copy outside IdentityIQ and keep it in source control.

Import it through Global Settings > Import from File or the console import command. A file with several templates must be wrapped in <sailpoint>…</sailpoint> .

Associate the copy with the event that should use it.

  • EmailTemplate XML <EmailTemplate name="ACME Work Item Assignment" cc="$!{workItem.owner.manager.email}">
  • <Description>Sent when a work item is assigned.</Description>
  • <Signature>
  • <Inputs>
  • <Argument name="workItem" type="WorkItem"/>
  • <Argument name="workItemName" type="string"/>
  • </Inputs>
  • </Signature>
  • <Subject>New work item: $workItemName</Subject>
  • <Body><![CDATA[
  • <html><body>
  • <p>Hello $!{workItem.owner.firstname},</p>
  • <p>You have a new item: <b>$workItemName</b>.</p>
  • #if ($workItem.expiration)
  • <p>Please act by $spTools.formatDate($workItem.expiration).</p>
  • #end
  • </body></html>
  • ]]></Body>
  • </EmailTemplate>
  • Part Notes
  • name Unique identifier

cc , bcc Can be dynamic. There is no to attribute , because recipients are set by the sending process and would override it.

from / <From> If omitted, the Default From Address in Notification Settings is used

<Subject> , <Body> The message. HTML bodies go in CDATA because characters such as < and & are illegal in XML text.

<Signature> / <Inputs> / <Argument> Documents the arguments the event supplies . You cannot add new ones by editing XML.

Velocity Template Language (VTL)

Templates are rendered by Apache Velocity . All signature arguments are loaded into the Velocity context.

References: $identityName , $certification.name , $certifier.displayableName . Velocity calls the matching getter, for example getDisplayableName() . Extended attributes are reached through $identity.attributes.region or $identity.getAttribute("region") . Use $!{var} for "quiet" references that print nothing when null.

Directives: #if / #elseif / #else / #end , #foreach ... #end (for example, looping through $acctReq.attributeRequests ), and #set .

spTools is added to every template. It provides formatDate(...) in several forms, getMessage(key) for message-catalog text (section 11.3), and escapeHtml(...) .

Do not mix notations. Workflow-style $(variableName) is not Velocity. If IdentityIQ sees it in an element, that element skips Velocity and uses simple substitution, so any #if there prints as plain text.

HTML escaping is applied to HTML passed in through variables. HTML cannot be passed as an argument value. All markup belongs in the template itself.

Associating Templates With Events

Where Examples

Global Settings > IdentityIQ Configuration > Notification Settings Work Item Reminder, Escalation, Comment, Forward, Assignment, Policy Violation, Task Result Signoff, Delegation, Remediation Work Item, Access Request Reminder, Sunset Expiration Reminder; also the Server Root Path used to build links

Compliance Manager Certification initial notice, challenge notices, mitigation expiration, bulk reassignment, sign-off approval

Each certification Initial, reminder, escalation, and revocation templates (overrides)

Workflows Process variables, step arguments, or an approval's work item configuration. Workflow-referenced templates can use every workflow variable and step argument .

Reports Sign-off templates. The Default Report Template is used for sending PDFs.

SystemConfiguration keys (XML-only templates) For example delegationEmailTemplate , remediationEmailTemplate , openCertsEmailTemplate

Match the arguments. The selection lists show every template, but each event provides a fixed set of arguments . Only a template whose argument list matches the default template's list will render useful content. Clone the default for that event instead of reusing an unrelated template.

Worked Example: A Friendlier Manager Approval Email

The requirement: managers should see the requestee's department and a clear deadline, and the email should link straight to the approval.

Find the template the approval currently uses. In LCM Provisioning, it is set through the approval's work item configuration or a process variable such as the manager email template.

Copy that template's XML, rename it ACME LCM Manager Approval , and keep its Signature unchanged, because the workflow supplies the same arguments.

Rewrite the body in HTML inside CDATA. Use $!{identityDisplayName} (quiet reference, so a missing value prints nothing), #foreach over the approval items, and $spTools.formatDate(...) for dates.

Because the template is referenced from a workflow , workflow variables and step arguments are also available. That is how a value such as the requestee's department can be shown, if the workflow passes it.

Build links from the Server Root Path in Notification Settings, so they point at the right host in each environment.

Import the template, point the workflow's variable or approval configuration at the new name, and test with redirection.

Troubleshooting Templates

  • Symptom Likely cause
  • Literal $variable text in the email The argument is not in the event's argument set, or its name is misspelled
  • #if printed as text $(...) notation in the same element, or a Velocity syntax error
  • Import fails Invalid XML, such as HTML outside CDATA or several templates without a <sailpoint> wrapper
  • Links point to localhost Server Root Path not set for this environment
  • Testing

Switch to Redirect to File (section 3.4), trigger the event or run the sample Test Email Sending rule from the console, and read the output. From your own rules, send email with context.sendEmailNotification(template, new EmailOptions(to, args)) , as that sample rule shows.