Reference Variables

Note: For HTML contained within variables, refer to HTML Escaping.

When a variable name is referenced within the text for any of the message elements, its value is substituted into the text in its place.

Example:

Copy 
<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. Velocity can also access data values in fields within objects passed as arguments and replace the variable notation with those values. Consider the <subject> and <body> elements shown below. The argument list for this email template includes a Certification object (named certification) and an Identity object (named certifier).

Copy 
<Subject>$certification.name requires approval</Subject>
<Body>$certification.name was signed by $certifier.displayableName and requires your 
approval.
Login and view your work item inbox to complete this request.
</Body>

To resolve these variable references, Velocity calls the getName() method on the certification object and the getDisplayableName() method on the certifier's identity object. When the substitutions are made, 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.

Login and view your work item inbox to complete this request.

Any attribute or method on any of a template's input arguments can be accessed through the reference variables.

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. Identity extended attributes, for example, are accessible through the Identity's attributes hash map or through the getAttribute() method on the Identity object (e.g. $certifier.attributes.region and $certifier.getAttribute("region") both return the value in the "region" extended attribute).

Note: The list of available methods for IdentityIQ objects (Identity, Certification, ProvisioningPlan, etc.) can be found in the SailPoint JavaDocs that ship with the IdentityIQ product. These can be viewed through a browser at URL: [IdentityIQ base URL]/doc/javadoc/.

HTML Escaping

Note: HTML escaping is applied to HTML that is passed into a HTML email template using a variable.

HTML escaping, or encoding, is the process of replacing any HTML reserved characters in a string, such as < or >, with their non-interpretable HTML entity representation. This is done to prevent unvalidated data from being included in a template and distributed through an email.

For example this:

Copy 
<a href="http://www.sailpoint.com" onclick="steal_passwords();return false">Click here to
approve</a>

is transformed into this when HTML-escaped :

Copy 
&lt;a href=&rdquo;http://www.sailpoint.com&rdquo;onclick=&rdquo;steal_passwords();return 
false&rdquo;&gt;Click here to approve&lt;/a&gt;

HTML content that is part of the template body itself is not escaped, it is rendered by any HTML email client correctly.

For security reasons, all HTML strings passed into a HTML email template using variables have their HTML escaped.

Refactoring HTML Email Templates

If you have already defined email templates to use HTML supplied by variables, they must be refactored so that all HMTL is contained within the email template itself.

For example if you have the following email template:

Copy 
<html>
<body> 
$header 

You have a pending work item that requires attention. Work Item: $workItemDescription

--------------------------------------------------------------------------------
$!comment
</body>
</html>

Where the $header is a variable containing HTML, such as <h2>Hello, $identityname</h2>, the HTML part of the string needs to be moved directly into the email template.

For example:

Copy 
<html>
<body> 

<h2>Hello, $identityName</h2> 

You have a pending work item that requires attention. Work Item: $workItemDescription

--------------------------------------------------------------------------------
$!comment
</body>
</html>

Where $header is an $identityName variable which contains only the name.

$(…) Variable Syntax

The $(…) variable syntax pre-dates the use of Velocity VTL templates. If you have templates that contain the $(…) variable syntax, two changes in IdentityIQ might affect you:

  • HTML passed to a template using $(…) syntax is escaped just like VTL.

  • VTL and the $(…) syntax can not coexist in the same template. If the $(…) syntax is found anywhere in the template, the entire template string is passed to IdentityIQ's non-Velocity resolver and any VTL scripting code or velocity reference variables are not be processed. SailPoint-provided context variables are still resolved as expected.

For example, if your email template contains VTL as follows:

Copy 
#if (
!$workItem.get("fromSource").equalsIgnoreCase("QuickLink"))
$workflow.get("launcherDisplayName")
#else
$(managerName)
#end

The VTL if/else statements is not processed because of the existence of $(managerName), but instead rendered as literal strings.

In VTL, you should change any of the $(variableName) syntax to use the VTL $variableName syntax.