11.1 Customizing and Using Email Templates
Key Takeaways
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.
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 templateslcmemailtemplates.xml– Lifecycle Manager templatesemailtemplatesSample.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
importcommand. 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 examplegetDisplayableName(). Extended attributes are reached through$identity.attributes.regionor$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), andescapeHtml(...). - 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#ifthere 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),#foreachover 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.
An administrator edits the out-of-the-box Work Item Reminder template directly in the Debug pages. What risk does the documentation warn about?
The change can be overwritten during an IdentityIQ upgrade, so a renamed copy should be customized and associated instead.
The template stops rendering Velocity directives.
Debug page edits to templates are only visible to System Administrators.
The template loses its Signature element.
A certification reminder template includes #if($requester) logic but prints the literal text "#if" in the email. The same element also contains $(identityName). Why?
Velocity directives only work in the Subject.
spTools must be imported first.
The template is missing a CDATA block.
The workflow-style $(variableName) notation makes IdentityIQ skip Velocity for that element, so the directives print as text.
A team builds an HTML email body with tables and links. What must the Body element contain?
Only plain text, because IdentityIQ cannot send HTML email
A reference to an external HTML file
The HTML inside a CDATA block so characters such as < and & are not parsed as XML
An HTML argument passed in from the workflow
A custom template associated with the Work Item Assignment notification renders mostly empty values. What is the most likely cause?
The template lacks a to attribute.
Its expected arguments do not match the fixed arguments that the Work Item Assignment event provides.
Suppress Duplicate Emails is enabled.
The template was imported without the -noids option.
Sections you finish are checked off in the contents.