3.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.

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.

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

3.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:

  1. Log in to Identity Governance as a Customer or Global Administrator.

  2. Select Configuration > Notification Emails.

  3. 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.

  4. 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.

  5. Save and close the files.

  6. 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:In 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

3.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:

  1. 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.

  2. Download the email template.

  3. 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>.

  4. Upload the modified email template.