You are on page 1of 16

Email Template Usage and Customization

This document explains how to customize the IdentityIQ email templates to meet each installation’s specific messaging needs.

........................................................ 8 EmailTemplate Attributes................................................................................................................ 13 CDATA Blocks ....................................................................................................................................................... 15 Using a Rule to Test Templates and Email Configuration ............................................................................. 14 Sending an Email from a Rule ........................................................................................ 3 Accessing the Templates .................................................................................................... 12 Method Calls ........................................ 11 Conditional Statements ........................................................................................................................... 4 Associating Templates with Events ...................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................... 3 Importing Email Templates into IdentityIQ ............................................................................................................. 10 VTL vs....................................................................................................................................................................... 11 Reference Variables............................................................ 10 Incorporating VTL in Email Template XML.................................... 9 References ..................... $(variableName) Notation ............................................................................................................. 8 EmailTemplate Nested Elements ..............Table of Contents IdentityIQ Email Templates ..................... 13 SPTools Function Library .......................................................................................... 11 Where to Use VTL .............................................................................................................................................................................................. 9 Apache Velocity Engine ..................... 16 Email Template Usage and Customization Page 2 of 16 ................ 9 Directives (Commands) ............................... 5 Email Template XML ..............................................................................................................................................................................................................................................................................................................................

Basic templates are provided out of the box to construct messages corresponding to each of the email-generating events.xml and lcmemailtemplates. NOTE: To customize any of these templates.xml. The default email templates should not be modified directly for customizations because they may be overwritten during the IdentityIQ release upgrade process.IdentityIQ Email Templates Many events in IdentityIQ generate email notifications to users notifying them of action required by them or action taken that directly affects them. These email messages are built based on email templates.xml that contains some additional example templates that are not loaded into IdentityIQ during the initial load process. Click the desired template to view or edit its XML representation. these templates show how to create HTML email messages. make a copy of it and rename the copy to a unique name. Accessing the Templates The default email templates ship with the product and can be found in the [IdentityIQ Installation Directory]/WEB-INF/config directory in the files: emailtemplates. email templates are stored as XML objects and can be viewed or modified through the IdentityIQ Debug pages. Then associate the customized template to the email-generating event through the IdentityIQ user interface or configuration XML (as described in Importing Email Templates into IdentityIQ below). Figure 1: Accessing Email Templates from the Debug Pages Email Template Usage and Customization Page 3 of 16 . Any of the templates in these files can be cloned to create custom templates. and these messages can be customized to meet the specific needs of each customer. To view the list of email templates from the Debug pages. There is a third file called emailtemplatesSample. if permitted by the organization’s source code control procedures. select EmailTemplate from the object list and click List. but customized templates can be edited directly through the Debug pages. The default templates should not be modified from here since they will be overwritten during any IdentityIQ version update. Once loaded into IdentityIQ (either during the initial load or using the console or UI import option).

IdentityIQ parses the XML during the import process and recognizes the file’s contents as an EmailTemplate object.Figure 2: Email Template List Importing Email Templates into IdentityIQ When email templates are edited outside of IdentityIQ. the import will only be successful if the XML is valid. Then use the console’s import command to import the file. The import will fail if the XML is invalid. As with the UI import option. Click Browse to select the email template’s XML file from the file system and click Import. To import a template through the user interface. Figure 3: Import through IdentityIQ UI To import the email template through the iiq console. click System Setup -> Import from File. first start the console from the [IdentityIQ Installation Directory]/WEB-INF/bin directory. they must be imported into the system before they can be used for any notifications. any errors encountered are reported to the console. Email Template Usage and Customization Page 4 of 16 . Email templates can be imported through the IdentityIQ user interface or through the iiq console.

The table below shows the notification type. and ensure that the selected template’s argument list matches the default template’s arguments. Refer to the default template’s XML to see the arguments (names and variable types) for each notification.Figure 4: Iiq Console Import Import files may contain one or more EmailTemplate objects. the import methods expect the set of objects to be wrapped in a <sailpoint></sailpoint> block. NOTE: Different email templates accept and use different arguments. The selection lists in the UI for each notification lists all email templates. To use a custom template for any of these notifications. only templates whose arguments list matches the provided arguments will work correctly to create a useful event notification. Since IdentityIQ provides a fixed set of arguments for each notification type. and their association location. the default template name. no matter what arguments they require. Associating Templates with Events Email templates are associated to their respective email-generating events in several places in the IdentityIQ UI and configuration XML. specify the custom template name in place of the default template in that notification configuration. if a file contains more than one object. Notification Type (Field Label or Configuration Key) For reminder notices For escalation notices For work item comment notices For work item forwarding notices For policy violation notices For task and report signoff notices For work item assignment notices For work item assignment removal notices For remediation item assignment notices For remediation item assignment removal notices Initial Notification Email Template Exceptions Expiration Notices Bulk Reassignment Modification notices Challenge Period Start Notices to Challengers Challenge Period End Notices to Certifiers Challenge Creation Notices to Challengers Challenged Decision Notices to Certifiers Default Email Template Work Item Reminder Work Item Escalation Work Item Comment Work Item Forward Policy Violation Task Result Signoff Work Item Assignment Work Item Assignment Removal Remediation Item Assignment Remediation Item Assignment Removal Certification Mitigation Expiration Bulk Reassignment Challenge Period Start Challenge Period End Challenge Creation Notification Certification Decision Challenged Notification Configuration Location System Setup -> IdentityIQ Configuration -> Miscellaneous tab -> Email Templates section System Setup -> Certification Configuration -> Email Templates section NOTE: Challenge-related notification email templates can be overridden for individual certifications on the Lifecycle page in each certification Email Template Usage and Customization Page 5 of 16 . However.

This customization must be reapplied after any IdentityIQ version upgrade. its XML can be edited to add an “emailTemplateId” argument to change the email message template used. step argument. NOTE: Because this is cumbersome. once a report is defined. (Continuous Certification Reminder/Escalation only used with Continuous Certifications) Configured in report specification when Require Signoff is selected: Analyze -> Reports -> [select report from Reports tab] -> Require Signoff Not specified in the UI. Specified within workflow definitions (Define -> Business Processes) either as a process variable. NOTE: Initial Notification and Bulk Reassignment notices can be overridden for each certification on the Notifications page in each certification configuration. organizations may choose to edit the Default Report Template directly rather than cloning it. as it will be overwritten during the upgrade process. or work item configuration email notification template Reminder Email Template Escalation Email Template (Revocation) Reminder Email Template (Revocation) Escalation Email Template (Certification Required Period) Reminder Email Template (Overdue Period) Escalation Email Template Report signoff initial notification Report signoff reminder notice Report signoff escalation notice Work Item Reminder Work Item Escalation Work Item Reminder Work Item Escalation Continuous Certification Reminder Continuous Certification Escalation Task Result Signoff No default in UI but argument list matches Work Item Reminder No default in UI but argument list matches Work Item Escalation Default Report Template Send PDF of report to someone Various:  Process Variables  Step Arguments  Approval Work Item Configuration Email Notification Template LCM Requester Notification LCM Manager Notification LCM User Notification LCM Identity Update Approval LCM Pending Manual Changes LCM Password Change Email Template Usage and Customization Page 6 of 16 .Notification Type (Field Label or Configuration Key) Challenge Expiration Notices to Challengers Challenge Decision Expiration Notices to Challengers and Certifiers Challenge Accepted Notices to Challengers Challenge Rejected Notices to Challengers Sign-off Approval Notices to Approvers Default Email Template Challenge Expiration Challenge Decision Expiration Challenge Accepted Challenge Rejected Certification Sign-off Approval Configuration Location configuration when the challenge period is enabled. Set in the Notifications step in each certification configuration when the associated reminder or escalation option is enabled.

body. only editable through System Config XML From IdentityIQ Debug Pages. and all steps arguments and approval arguments defined for the step that invokes the email template are also available for use in the email message (subject. cc.) key= "certificationReminderEmailTemplate" key= "policyViolationDelegationEmailTemplate" key= "AccountGroupPermissions. challengeGenerationEmailTemplate" Delegation Delegation Revocation Delegation Finished Remediation Work Item Remediation Notification (Sent when Notify Users of Revocations is selected in a certification configuration) Certification Reminder (Sent on demand from certification dashboard) Policy Violation Delegation Account Group Challenge Creation Notification (specialized form of the Challenge Creation Notification email) Access Request Reminder (Sent on demand from the Manage -> Access Requests window) Open Certifications Not configurable through the UI. all workflow variables. click System Configuration and search the XML for these email template names or key values key= "accessRequestReminderEmailTemplate" key="openCertsEmailTemplate" Email Template Usage and Customization Page 7 of 16 .Notification Type (Field Label or Configuration Key) Workflows (including sub-processes) using these templates:  Identity Correlation  Do Manual Actions  Do Provisioning Forms  Assimilate Provisioning Form  Identity Request Approve  Identity Request Notify  Identity Request Provision  LCM Create and Update  LCM Manage Passwords  LCM Provisioning  Lifecycle Event – Leaver  Lifecycle Event Reinstate  Role Modeler – Impact Analysis  Role Modeler – Owner Approval key="delegationEmailTemplate" key="delegationRevocationEmailTemplate" key="delegationFinishedEmailTemplate" key="remediationEmailTemplate" key="remediationNotificationEmailTemplate" Default Email Template Notification Pending Manual Changes Account Selection Notification Provisioning Form Notification Role Modeler – Approval Role Modeler – Impact Analysis Review Configuration Location NOTE: For templates referenced from a workflow. etc.

etc. from Email Template Usage and Customization Page 8 of 16 .).com” > EmailTemplate Attribute name cc. bcc Purpose Short but descriptive name for template. EmailTemplate Attributes The table below lists the components that are generally expressed as attributes on the Email Template.email” from=”administrator@XYZCorp.Email Template XML The Email Template XML consists of an <EmailTemplate> element with a set of attributes and nested elements that specify the basic components of an email message (sender. Example: <EmailTemplate name=“Work Item Reminder” cc=”$identity. subject. message body. if this is not specified in template. the default sender specified on the System Setup -> IdentityIQ Configuration window’s Default From Address is used.Manager. Figure 5: Example Email Template XML The next two sections describe those attributes and nested elements. uniquely identifies email template Carbon Copy and Blind Carbon Copy recipients for the email NOTE: The to attribute is not specified in the email template because it is determined programmatically as the email is sent and would be overridden Sender email address.

Apache Velocity Engine IdentityIQ email templates are processed through an open-source engine called Apache Velocity. their complexity and length drive that decision. At the most basic level. Highlights are included below. of the email message Hashmap of arguments to the email template The signature for each template cannot be changed through the XML.g. Velocity is a Java-based template engine that allows web page designers to reference methods defined in Java code. and action involved. bcc. subject. describes the element in which it is nested (e. Nested element within Signature. and full documentation on the syntax is available in the Apache Velocity User Guide or Reference Guide. Email Template Usage and Customization Page 9 of 16 . Properties and methods belonging to any object passed as an argument are available to include in the message. The contents of different variable types can be accessed through the syntax described in the table below. the contents of these elements and attributes can be written as straight text values with no variable substitutions. but other objects that are not part of the template’s signature cannot be retrieved to use in the email message. or main content. the appropriate email template is loaded and its argument variables are passed into the VelocityContext where they can be accessed through VTL’s reference syntax. Nested Element <subject> <body> <signature> Purpose Subject line for the email message Body. Arguments to each template vary based on the associated system activity to which they apply. <Description> within the <EmailTemplate> describes the purpose and usage of the template itself) <Inputs> <Argument> <Description> NOTE: The cc. IdentityIQ’s email templates make use of the Velocity Template Language to dynamically specify the email messages’ contents and generate custom email messages specific to the recipient. <Description> within <Argument> describes the argument’s usage. this element names and specifies the type of each input argument to the template Indicates descriptive information for the reader of the XML. and other attributes. or from attribute values can also be expressed as nested elements instead of as attributes on the <EmailTemplate> element. the real flexibility and usefulness of these templates is found when custom text is substituted into the message body. The Velocity Template Language (VTL) is a fairly simple to use. This substitution is managed by the Apache Velocity Engine. However. work item.EmailTemplate Nested Elements The components listed in this table are generally expressed as nested elements due to their complexity and length. References As IdentityIQ prepares to send an email notification. signifying the input arguments to the template Nested element within Signature and Inputs.

$customer.Name invokes the getName() method on the Certification object retrieved through the getCertification() method on the item object $identity. Workflows).Certification. Instead.DisplayName Invokes the getDisplayName() method on the identity object NOTE: Property notation resolves to the getter method corresponding to the property name.getBundles($application) Used for all non-getter methods and for any $identity. VTL vs.‘true’) methods that require arguments Directives (Commands) These are the key commands of the Velocity Template Language that are most frequently used in IdentityIQ email templates to dynamically determine the text that is printed in each email message. #{end} #foreach ($attrReq in $acctReq.name Value(s): $attrReq.Reference Type Variables Examples $identityName ${identityName} $!identityName Hash table values Object properties Object methods Additional Information These three syntaxes are generally interchangeable in VTL. Shorthand notation (the first example) is the most commonly used.displayableName. Nested objects’ properties can also be retrieved through this notation. Example: $item.attributeRequests) Operation: $attrReq.g. Command/Directive Usage/Purpose #If… #elseif… #else… Conditional evaluation #end #foreach… #end Loop through a list of objects Example #if($requester) requested by $requester.hasRole($role. $(variableName) Notation The VTL reference syntax must not be confused with the $(variableName) notation used for variable referencing in other IdentityIQ XML objects (e.operation Attribute: $attrReq. including the syntax for less commonly used directives. that portion of the message will not be passed to Velocity for rendering at all. Velocity does not recognize this syntax and will be unable to parse text that uses it.Smith”) #set ($book. not to an instance variable itself.Address Returns the value corresponding to the Address key in a customer hash table $identity.Title = “War and Peace”) #set Establish the value of a reference Refer to the Velocity User Guide for additional information on the language. In fact. its contents will be rendered Email Template Usage and Customization Page 10 of 16 . Refer to the Velocity User Guide for more information. but each of the other two is required in special cases.value #end #set ($identityName = “John. when IdentityIQ detects this syntax in any element of an email template.

displayableName and requires your approval. etc. this email template’s argument list includes a Certification object (named certification) and an Identity object (named certifier). Incorporating VTL in Email Template XML All input arguments in the template’s signature are automatically loaded into the VelocityContext and are therefore accessible through the VTL reference notation for inclusion in the message text. Any Velocity commands included in the same element with a variable that uses the $(variableName) notation will be treated as normal text and printed as-is in the final message. its value is substituted into the text in its place. Login and view your work item inbox to complete this request. Most commonly. Additionally. Consider the <subject> and <body> elements shown below.) can be used in determining the text to print in the messages. but the cc and bcc recipients (as well as the from email address) are often dynamically specified through reference variables as well.name was signed by $certifier. loops.by a simpler mechanism that is capable of doing the variable substitution based on the template’s arguments but does not interpret any of the Velocity directives. Velocity can also access data values in fields within objects passed as arguments and replace the variable notation with those values. this means the <Subject> and <Body> elements of the message. Excerpts from the default email templates in IdentityIQ are used as examples throughout the rest of this section to illustrate how reference variables and various command syntaxes can be used. <Subject>$certification. Example: <Body>$certifierName has accepted the challenge for '$challengeItem' and will change the decision. </Body> Variable substitution results in the email message content: John Smith has accepted the challenge for ‘Entitlements on Financials’ and will change the decision. Reference Variables When a variable name is referenced within the text for any of the message elements. Where to Use VTL The Velocity Template Language syntax can be specified in any attribute or element that is used to build the email message. </Body> Email Template Usage and Customization Page 11 of 16 . Velocity’s commands (conditional statements.name requires approval</Subject> <Body>$certification.

g. are accessible through the Identity’s attributes hash map or through the getAttribute() method on the Identity object (e. #else Email Template Usage and Customization Page 12 of 16 . and” is suppressed. ProvisioningPlan. Identity extended attributes.displayableName. and #{end}created on … Attribute values can also be evaluated to determine which of multiple text selections to include in a message: #if ( $launcher != $identityName ) $launcher requested the following password changes be made to your account(s). Extended attributes on IdentityIQ objects can be accessed through the attributes hash map or by providing the attribute name as an argument to the appropriate getter method. the portion of the text “requested by $requester.region and $certifier.getAttribute(“region”) both return the value in the “region” extended attribute). #if ($remindersRemaining > 0) This work item will escalate after $remindersRemaining more reminder(s). When the substitut ions are made. Any attribute or method on any of a template’s input arguments can be accessed through the reference variables. for example.attributes. #end Additionally.displayableName.To resolve these variable references. <Body>This is your $ordinalNumReminders reminder that the work item $workItemName #if($requester)requested by $requester.) can be found in the SailPoint JavaDocs that ship with the IdentityIQ product. $certifier. These can be viewed through a browser at URL: [IdentityIQ base URL]/doc/javadoc/. Certification. In this example. Whole paragraphs can be included or omitted based on conditional tests. NOTE: The list of available methods for IdentityIQ objects (Identity. parts of a paragraph or sentence can be suppressed or altered based on conditional evaluations. the final email message looks like this: Subject: Manager Access Review for Catherine Simmons requires approval Manager Access Review for Catherine Simmons was signed by Catherine Simmons and requires your approval. if $requester is null. Login and view your work item inbox to complete this request. etc. Conditional Statements Conditional statements can be used to determine whether text should be included in the message or to choose alternate wording based on attribute values. Specifying the #if statement in-line with the rest of the text prevents extra line breaks in the middle of the sentence in the resulting email message. Velocity calls the getName() method on the certification object and the getDisplayableName() method on the certifier’s identity object.

formatDate() method. Throughout this example. #{else} was due on $spTools.3. SpTools is a function library that contains a few localization utility methods to help with message formatting -. #if($expiration) #if($expiration.3. #{end} This block checks to see if $expiration is null. The methods available within spTools are listed in the table below: Method String formatDate(Object date) Description Formats the passed-in date object to a string representation using the IIQ default date and time styles (both the java.formatDate($expiration. this is an older expired workItem so the message uses the $oldDueDate field as work item due date in the message. SPTools Function Library Immediately before any template is submitted for evaluation by the Velocity engine.The following password changes were made to your account(s) at your request.formatDate($expiration.dateformat SHORT formats). Line breaks have been inserted here for readability and should not be included in the message body unless they are desired in the resulting message text. The spTools reference variable is discussed in the next section.1). If it is not null. this #if statement was specified in-line to prevent unwanted line breaks in the message. the spTools argument is added to the VelocityContext so the template can access its methods. formatted per the norms of the server’s default locale and timezone NOTE: The styles are represented by constant values: SHORT = 3 MEDIUM = 2 LONG = 1 FULL = 0 String formatDate(Object date. In the template. #{end} #{else} was due on $spTools.1).getTime()) is due on $spTools. the printed date/time is formatted with the spTools.util.1). it pri nts “is due on…” or “was due on…” based on whether the expiration date/time is before or after the current date/time. NOTE: This example was altered from its original format in the default Work Item Reminder email template. formatted per the norms of the server’s default locale and timezone Formats the passed-in date object to a string representation using the specified date and time styles. Integer timeStyle) Email Template Usage and Customization Page 13 of 16 .primarily date formatting.3. If $expiration is null. Integer dateStyle.formatDate($oldDueDate.getTime() > $nowDate. #end Method Calls Methods within object arguments can be accessed directly through the method reference syntax.

color:#333.margin:0.font:bold 10pt Arial.) contains characters that are illegal in XML text (e. respectively).This is an article&lt. the most commonly used method from this library is the formatDate() method that takes a date object and two integers as arguments: $spTools.3. and is due on <strong>$spTools. <a href="http://localhost:8080/identityiq/manage/certification/entityList. String formatString) String getMessage(String key) String escapeHtml( String string) dateStyle and timeStyle correspond to java. In the out-of-the-box email templates.lineheight:15pt.formatDate($expiration.padding:0.</p> <p style="margin:0 0 20px. the date/time value in the expiration argument will be printed in the email message in MM/dd/yy hh:mm:ssPM format (or the appropriate equivalent for the server’s locale). you are responsible for certifying the access your employees have to enterprise applications.SimpleDateFormat method) Returns an internationalized message from the message catalog corresponding to the provided key Converts HTML special characters to their entity equivalents Example: escapeHtml('<div class="article">This is an article</div>') Returns: &lt.text."> <p style="margin:20px 0 0.color:#333.formatDate( $certification.1) After the reference shown above is resolved by Velocity. etc./div&gt. subject.color:#333.">A specific access certification is named <b>$!{workItemName}</b> has been created for you. <Body><![CDATA[ <html> <body style="background:#FFF.padding:0.jsf?certifi cationId=$!{certification.font:normal 10pt Arial.text-align:left.owner.g. </p> <p style="margin:0.lineheight:15pt.padding:0.">$!{workItem.">As part of our periodic compliance efforts.String formatDate(Object date. CDATA Blocks When any component of the email message (body.id}">Click here to get started on this task. any message body written as HTML must be contained within a CDATA section. the entire component must be expressed in a CDATA block to prevent it from being parsed.expiration.padding:0. characters like < and & that are interpreted by the parser as the start of an XML element or character entity.div class="article"&gt. see the Sun Javadocs for details Formats the date according to the specified formatString (uses the java. For example.3.3)</strong>.DateFormat constants.firstname}. cc.lineheight:15pt.</a></p> </body> </html> ]]> </Body> Email Template Usage and Customization Page 14 of 16 .font:normal 10pt Arial.text.

Test Email Sending". </Description> </Argument> <Argument name="context"> <Description> A sailpoint.*. if (null == template) { log. "This is a test of template parameters.util. Email Template Usage and Customization Page 15 of 16 .getObjectByName(EmailTemplate.0' encoding='UTF-8'?> <!DOCTYPE sailpoint PUBLIC "sailpoint. The example below shows how to send an email from a rule.lang. } template = (EmailTemplate) template. Sending an Email from a Rule Some installations may require notifications to be sent based on events that are not covered by the automated system notifications.deepCopy(context). return.put("testField1". <?xml version='1.object. </Description> </Argument> </Inputs> </Signature> <Source> // Library inclusions for BeanShell import sailpoint.Sends a sample email out via the email server. EmailTemplate template = context.*.api. // Add all args needed by the template like this args.*. // Specify the email template name in tplName String tplName = "SailPoint . return.SailPointContext object that can be used to query the database if necessary.text.com". import java.hampton@example."). import sailpoint.*.error("ERROR: could not find email template [ " + tplName + "]").dtd" "sailpoint.error("ERROR: failed to deepCopy template [ " + tplName + "]"). } Map args = new HashMap().*.*. import sailpoint.tools.</Description> <Signature returnType="Map"> <Inputs> <Argument name="log"> <Description> The log object associated with the SailPointContext. import java. if (null == template) { log.api. import java.class. // Point this to the “To” email address String emailDest = "adam. tplName). Rules can often be used to drive these notifications.The marked up text can then be passed to Velocity for variable substitution and can be rendered as an HTML email message.dtd"> <sailpoint> <Rule language="beanshell" name="Test Email Sending" type="BuildMap"> <Description>Debugging Tool .

Complete these steps to use the rule for testing purposes: 1.EmailOptions ops = new EmailOptions(emailDest. Document Revision History Revision Date May 2012 Written/Edited By Jennifer Mitchell Comments Initial Creation (current IdentityIQ version: 5. as described in Importing Email Templates into IdentityIQ . Edit the “Test Email Sending” rule to include the desired "To" email address. Using a Rule to Test Templates and Email Configuration This example rule can also be used to test the email server configuration or to test any email template. Set up an email server under System Setup -> IdentityIQ Configuration -> Miscellaneous -> Email Settings. and template arguments to create the desired notification. This writes the email text to the specified file. choose Email Notification Type: Redirect to File. email template. Edit an email template to contain the desired message and import it.) 2. Simply change the email template name. 3. ops). </Source> </Rule> </sailpoint> The beanshell from this example rule can be used as a template for sending an email from any defined rule. recipient. return.5) Email Template Usage and Customization Page 16 of 16 . context. > rule “Test Email Sending” 5.) 4. Run the "Test Email Sending" rule from the IIQ console to send the email. and import the rule. args). (NOTE: To test email templates independently from the email server configuration without actually sending emails through the server.sendEmailNotification(template. Examine the resultant email (either in the recipient’s inbox or the redirect email file) to verify that the message appears as expected. and arguments. (Rules are imported the same way as templates.