4.4 Customizing Email Notification Templates

Identity Governance notifies users of tasks in their queue, as well as other review events, as specified in review definitions. Depending on your configuration, various events associated with functional areas, such as bulk data update, business role approval, request, review, Separation of Duties (SoD), and fulfillment, might trigger email notifications. For example, the Bulk Data Administrator can be notified when a bulk data template is generated and when a bulk data update occurs; and an SoD Policy Owner can be notified when a new SoD violation is detected after data source collection and publication. The application supplies default templates with preconfigured tokens for the email notifications and uses the templates as is unless you customize them for your environment.

Users must have a valid email in the Identity Governance catalog to receive notifications. If Self is specified as the recipient and a user affected by the policy has no email, the application will not send the notification to Customer, Global, or other authorized administrators. When an user has multiple email addresses in the catalog, Identity Governance will send notification to only one email address.

IMPORTANT:Make sure users have a valid email because tasks such as Data and Certification policy violation uses emails for remediations and review and request approval tasks are also communicated via emails.

HINT:When setting up and testing Identity Governance notifications or testing preview review notifications, make sure you are using a test email system or test email addresses. For example, use fake mail, mail catcher, or test corporate mail server. Do not send emails to a live server while testing your system. If you have real email accounts in your test system you can inadvertently send spam email to people in your company.

You can also customize the product name in email notifications to brand it for your organization. To change the product name, run the Identity Governance Configuration Utility in the console mode, and specify the product name you prefer on the Identity Governance Server Details tab. For more information, see Using the Identity Governance Configuration Utility in the Identity Governance 4.3.1 Installation and Configuration Guide.

For information about configuring Identity Governance to send email notifications, see Enabling Email Notifications for Identity Governance in the Identity Governance 4.3.1 Installation and Configuration Guide. For information about Review related notifications, see: Section 25.1.9, Setting Review Notifications.

4.4.1 Modifying Email Templates

Identity Governance allows you to modify an XML file that contains the email text in the languages supported for Identity Governance. You can edit the XML file with one of the following programs to customize it for your organization:

XML editor
Text editor
Designer for NetIQ Identity Manager

To modify an email template content:

Log in to Identity Governance as a Global Administrator.
Select Configuration > Notification Emails.
Select a download option:
- To customize all email templates in a single file, select Download XML. Depending on your browser settings, you might be prompted for the download path.
  
  NOTE:If prompted, do not rename the EmailTemplates.xml file. Identity Governance cannot upload a file that does not match the expected name.
- To download the XML file for all the emails of a functional area in a single locale, select Implemented Locale from the View functional area drop-down list, then select the locale.
- To download the XML file for a single email in all the implemented locales, select Email from the View functional area drop-down list, then click an email name.
  
  Optionally, select Email source preview (en) to view the template. Specify an email address to Send notification preview.
  
  Click Download XML.
Modify the content in the email templates you have downloaded.

NOTE:Do not modify any text in the code strings in the file. Identity Governance might not function correctly if you change the code strings. For descriptions of the email tokens, see Email Tokens.
Save and close the files.
To submit the modified files, click Import XML.

Email Tokens

When customizing emails, be careful in handling the tokens. Identity Governance allows the use of entities and their attributes in your email templates. Entity tokens must appear in the form:token-descriptions section to be processed. If it only appears in the <body/> section of the template it will stay unresolved.

Some email templates expect only certain processing and entity tokens. Therefore, the product might not be able to replace a token with a value in some situations. For example, when an unexpected token is present in the template, a entity token is evaluated as null during notification preview, or an entity attribute was not collected and was resolved as null, the generated email might contain blank values or might contain token as-is. Notifications sent during review preview mode that enable administrators and review owners to preview notifications, might not always replace tokens with values, and names seen in the preview might not be the name that is sent in the live mode email.

The email templates use the following processing tokens:

Token	Notes
applicationId	Application ID, unused in the Certification External Provisioning Start Error template
applicationName	Application name
appName	Application name
approverName	Business role approver
certifierFullName	Reviewer's full name
certifyTaskLink	Link to task
changesetId	Unused in the Certification External Provisioning Start Error template
content	Used in the generic email template
curatorFullName	Bulk data feed curator
error	Fulfillment error
errorMessage	Error message text
externalPrdLink	Unused in the Certification External Provisioning Start Error template
feedName	Bulk data update definition
fulfillerName	Full name of the fulfiller
host	The workflow hostname
inputFile	Bulk data CSV file
link	URL link
message	The output message from a system process.
newTaskType	Used in the Certification Auto Provisioning Start Failed template
ownerName	Owner of the SoD policy
permissionsToLose	List of application permissions
prdName	Workflow name used in the external fulfillment template
prevReviewerFullName	User that the task was reassigned from
productName	Configured product name, such as Identity Governance or Access Review
reassignedByFullName	User who reassigned the task
reassignComment	Optional comment entered at reassignment
retryCount	Number of fulfillment items in a retry state
reviewLink	URL link to review NOTE:Do not use this token in notification emails to users, such as reviewers who have limited access to reviews. Instead use the certifyTaskLink token.
reviewName	Name of the review
reviewOwner	Review owner’s name
reviewOwnerPhone	Review owner’s phone number
roles	List of business approval roles
subject	Found in Certification Started and Certification Changed email templates with no reference to the token in the templates.
taskTimeoutDays	Task timeout in days
theTerminator	The user that terminated a review
userFullName	Identity Governance user's full name
violations	Used in the Detected SoD Violation email template.

NOTE:Instances where there are multiple review owners, and the review uses any one of these listed templates:

Certification Approval Task Pending Reminder
Certification Approval Task Pending
Certify Task Past Due
Certify Task Pending Reminder
Certify Task Pending
Certify Task Reassignment

Identity Governance sends the email notification with the primary and the additional review owner’s phone numbers for the token $reviewOwnerPhone$ and their names for the token $reviewOwner$. If the $reviewOwnerPhone$ token is not present in the template, then Identity Governance lists the names of the review owners.

The email templates use the following entity and role-based tokens:

Entity Token	Entity Type	Notes
ADDRESSEE	USER	Primary (TO) address. Resolves to one of the following role: Review Owner Reviewer Auditor Escalation Reviewer
REVIEW	REVIEWINSTANCE	Review instance
REVIEWDEF	REVIEW_DEFINITION	Attributes for the review definition
REVIEWER	USER	Task owner of a current review instance. Used only in notifications to task owners.
PAST_REVIEWER	USER	Reviewer of the previous review instance. Used only in task reassignment notifications.

The following table shows the current attribute definitions for the review based entity types.

Entity Type	Attributes
REVIEWINSTANCE	certificationDate endDate expectedEndDate startDate lastStatusChange validToDate taskCount taskCompleteCount itemCount itemCompleteCount itemApproveCount statusComment auditorComment startMessage approvedBy canceledBy approvedByPolicy status owners auditor
REVIEW_DEFINITION	name description activeFromDate activeToDate latestValidToDate startDate isActive duration escalationTimeout validFor repeat expirationExtension reviewType durationUnit escalationTimeoutUnit validForUnit repeatUnit expirationExtensionUnit owners auditor

4.4.2 Adding an Image to the Email Template

In addition to modifying an email template, you can also add an image or logo to the email template.

To add an image to the email template:

Select the image you want to add to the template and encode it in base64 string format.

HINT:Use the base64encode website or similar encoders to encode the image.
Download the email template.
Add the <img src="data:image/png;base64, %base64-value% "/>t ag where you want the image to appear. For example, <p>Powered by <img src="data:image/png;base64,iVBORw0KAAA..."/></p>.
Upload the modified email template.

4.4.3 Deleting a Custom Email Template

When you no longer want to use a custom email template, you can delete the custom template by clicking the custom email template name on the Notification Emails page, then clicking Delete.