Appendix B: Understanding velocity e-mail templates

Velocity is a presentation language, similar to JavaServer Pages (JSP), that allows for much flexibility. It lets you mix HTML and velocity tags so that you can craft dynamic e-mail content and styles for your notifications. You can modify the message templates and can use any functionality that velocity makes available.

Variables are accessed in velocity files in the following format: ${ objects.device.manufacturerName }. In this example, objects is the top-level object and device is its child. manufacturerName is the actual variable or property in the objects.device object that is returned.

Here are some helpful tips for customizing notifications using velocity.

Some e-mail providers, such as Gmail^TM webmail service, may ignore HTML styles that are included in the velocity templates. But if the HTML styles are embedded inline, then they are honored.
If you are not sure whether an object is null, then use an "if/else" clause to check it before you show it. Or include the following logic in the variable statement: ${ ticket?.technician?.displayname }. This logic ensures that if the ticket and technician objects are not null, then the display name field is returned.

Updating velocity templates

The velocity templates used to generate e-mail messages come preconfigured on the Fleet Tracker server in the install_path\server\webapps\ROOT\WEB-INF\classes\emails directory. To customize the e-mail notifications that Fleet Tracker sends, update the velocity files accordingly.

Access the Fleet Tracker server, and then navigate to install_path\server\webapps\ROOT\WEB-INF\classes\emails.
Open the velocity template that you want to update, make the necessary changes, and then save the file.
Note: To revert to predefined templates at a later time, make sure to keep backup copies of the templates.

If the Fleet Tracker server detects changes in the templates, then it recompiles the velocity files. The next e-mail notification it sends uses the updated template.

There are five predefined templates that Fleet Tracker uses to generate e-mail notifications. Each template has some specific objects associated with it and objects that are common across all templates that you can use to customize the content. The rest of this topic outlines what each template is used for and the data items that are available for them.

The following objects are common across all the velocity e-mail templates:

dictionary—This object is used internally to translate text strings, primarily field names, into the appropriate localized text. There are no predefined child objects; instead, the developer defines them and they vary based on the implementation. This object is an extension to the strings that appear in /i18n/index_$language.properties, where language is a language code, such as "en" or "de."
objects—This object contains the "theme objects" of the e-mail (such as objects.device and objects.policy). Most of the data items that you use in the notifications are found in this object.
host—This object contains the host name and host IP address of the server sending the e-mail. To access the fields, use "host.hostAddress" for the IP address and "host.hostName" for the host name.

The PolicyGroupEvent_language.vm template is used to generate e-mail notifications for policy events, as configured in the printer policy. The following objects can be used in this template:

Object	Property	Data Type	Description
objects.device	.manufacturerName	String	Name of printer manufacturer.
	.modelName	String	Model name of the printer.
	.serialNumber	String	Serial number of the printer.
	.contactName	String	Name of the contact for the printer.
	.name	String	Friendly name of the printer.
	.ipAddress	String	IP address of the printer.
	.colorCapable	boolean	Returns true if the printer is color capable.
	.accountCode	String	The client the printer belongs to.
	.tickets	array of Objects	Contains all tickets associated with the printer. Each Object exposes the following properties: .details (String) .dateCreated (Date) .lastUpdated (Date) .dueDate (Date) .dueTime (Date) .technician (Object) .technician.displayName (String) .ticketId (String) .status (String) .priority (String)
	.port	Object	Exposes the .type (String) property.
	.lastDataCollection	Date	The last time rollup data was received from the printer.
	.macAddress	String	MAC address of the printer.
	.dnsHostName	String	DNS host name of the printer.
	.assetTag	String	An optional identifier field; may be null.
	.firmware	String	Current version of firmware installed on the printer.
	.engineCode	String	Engine firmware level of the printer.
objects.policy	.problem	String	The event that triggered the policy notification.

The PolicyGroupEvent_language.vm template is used to generate e-mail notifications for policy events, as defined in the group policy. The following objects can be used in this template:

Object	Property	Data Type	Description
objects.group	.name	String	Name of the group
	.notes	String	Informational text associated with the group
	.accountCode	String	Account code of the group
	.address1	String	The first line of the address where the group is located
	.address2	String	The second line of the address where the group is located
	.city	String	The city where the group is located
	.province	String	The province where the group is located
	.postalCode	String	The postal code for the group
	.country	String	The country where the group is located
	.email	String	The e-mail address associated with the group
	.telephone	String	The telephone number associated with the group
	.fax	String	The fax number associated with the group
	.contact	String	The name of the group contact
	.contactPhone	String	The telephone number of the group contact
	.contactEmail	String	The e-mail address of the group contact
objects.policy	.problem	String	The event that triggered the policy notification

The CostForGroupExpiration_language.vm template is used to generate e-mail notifications for contract expiration at the group level. The CostForDeviceExpiration_language.vm template is used to generate e-mail notifications for contract expiration at the printer level. The following objects can be used in both of these templates:

Object	Property	Data Type	Description
objects.costs	.purchaseOrder	String	Identifier to track the actual purchase order for the specific group or printer.
	.acquisitionDate	Date	Date of acquisition in MM/DD/YYYY format.
	.acquisitionType	String	Type can be "Purchase," "Lease," or "Rental."
	.puchaseOption	float	Used to keep buyout price.
	.initialPayment	float	Initial payment.
	.finalPayment	float	Final payment.
	.monthlyPayment	float	Monthly payment.
	.numberOfPayments	Integer	Total number of payments.
	.expirationNoticeDate	Date	Date of expiration of the contract in MM/DD/YYYY format.
	.emailNotification	String	E-mail address associated with the selected user.
	.bwAllowances	Integer	Number of allotted black-and-white pages.
	.colorAllowances	Integer	Number of allotted color pages.
	.bwRatePerPage	float	Price per black-and-white page.
	.colorRatePerPage	float	Price per color page.
	.bwOverage	float	Overage price per black-and-white page.
	.colorOverage	float	Overage price per color page.
	.maintenancePayment	String	Maintenance payment can be "Annually," "Monthly," "Quarterly," or "Cost Per Page."
	.maintenanceCost	float	Maintenance cost.
objects.group			An object that, along with all its child objects, is available for *CostsForGroupExpiration_language.vm.*
objects.device			An object that, along with all its child objects, is available for *CostsForDeviceExpiration_language.vm*.

The final velocity template available for customization is ReportEmail_language.vm, which is used to generate messages when reports are e-mailed. Fleet Tracker lets users print transparencies and does not make any objects available for this template. But users can still structure the style and presentation of the e-mail using velocity.

The following velocity example shows how to filter data by using conditional logic. The e-mail message shows information about tickets that are created or updated as a result of the printer alert, as determined by the time stamps. This example can be useful when a policy event triggers ticket creation, ticket changes, or e-mail notifications.

Name: $!objects.dataCollector.name
        Address: $!objects.dataCollector.address
        Company Code: $!objects.dataCollector.accountCode
        Site Location/Group: #if($objects.dataCollector.group)#if
				($objects.dataCollector.group.class_ == 
				"com.lexmark.lfm.domain.Group")$!objects.dataCollector.group.name
#else<br>
#end
#else<br>
#end
        Enrollment Code:<b>$!objects.dataCollector.enrollmentCode</b>
        City: $!objects.dataCollector.city
        State/Province: $!objects.dataCollector.province
        Zip/Postal Code: $!objects.dataCollector.postalCode
        Country: $!objects.dataCollector.country
        Telephone: $!objects.dataCollector.telephone
        Facsimile: $!objects.dataCollector.group.fax
        Website: $!objects.dataCollector.group.website
        E-mail: $!objects.dataCollector.email

        Contact Person:
        ==============
        Name: $!objects.dataCollector.contact
        Telephone: $!objects.dataCollector.contactPhone
        E-mail: $!objects.dataCollector.contactEmail