Apache Velocity Engine

IdentityIQ email templates are processed through an open-source engine called Apache Velocity. Velocity is a Java-based template engine that allows web page designers to reference methods defined in Java code. IdentityIQ 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, work item, and action involved.

The Velocity Template Language (VTL) is a fairly simple to use. Highlights are included below, and full documentation on the syntax is available in the Apache Velocity User Guide or Reference Guide.

References

As IdentityIQ prepares to send an email notification, the appropriate email template is loaded and its argument variables are passed into the VelocityContext where they can be accessed through VTL reference syntax. The contents of different variable types can be accessed through the syntax described in below.

Variables
$identityName$$!identityName
These three syntaxes are generally interchangeable in VTL. Shorthand notation (the first example) is the most commonly used, but each of the other two is required in special cases. Refer to the Velocity User Guide for more information.

Hash table values
$customer.Address
Returns the value corresponding to the Address key in a customer hash table

Object properties
$identity.DisplayName
Invokes the getDisplayName() method on the identity object

Note

Property notation resolves to the getter method corresponding to the property name, not to an instance variable.Nested object properties can also be retrieved with this notation.
Example: $item.Certification.Name invokes the getName() method on the Certification object retrieved through the getCertification() method on the item object

Object methods
$identity.getBundles($application)$identity.hasRole($role,'true')
Used for all non-getter methods and for any 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.

#If… #elseif… #else… #end
Conditional evaluation
#if($requester) requested by $requester.displayableName. #{end}

#foreach… #end
Loop through a list of objects
#foreach ($attrReq in $acctReq.attributeRequests) Operation: $attrReq.operation Attribute:$attrReq.name Value(s): $attrReq.value#end

#set
Establish the value of a reference
#set ($identityName = "John.Smith")#set ($book.Title = "War and Peace")

Refer to the Velocity User Guide for additional information on the language, including the syntax for less commonly used directives.

VTL vs. $(variableName) Notation

The VTL reference syntax must not be confused with the $(variableName) notation used for variable referencing in other IdentityIQ XML objects, such as Workflows. Velocity does not recognize this syntax and is unable to parse text that uses it. When IdentityIQ detects this syntax in any element of an email template, that portion of the message is not passed to Velocity for rendering at all. Instead, its contents are rendered by a simpler mechanism that is capable of doing the variable substitution based on the template's arguments. However, none of the Velocity directives are interpreted. Any Velocity commands included in the same element with a variable that uses the $(variableName) notation is treated as normal text and printed as-is in the final message.