Edit1 What are Templates?
One of the primary functions of the IssueNet Service Manager is to simplify the editing and management of notification templates. IssueNet provides the advantage of allowing each Notification Action to use a distinct template. By using distinct templates, each notification can provide its recipients with information specific to the reason for the notification as well as other supporting content.
IssueNet stores notification templates as files with a .tpl extension. The Service Manager loads the templates for editing and sending notifications from the Template Directory and any subdirectories. The default template directory location is the
Notification Templates subdirectory of the IssueNet installation directory.
The Templates must be edited on the machine on which the service manager is installed, failure to do so will result in an error message : "The notification template directory C:\Program Files\Elsinore Technologies\IssueNet\Notification Templates does not exist. Unable to load notification."
Edit1.1 Configuring Notification Templates
Selecting
Tools|Configuration allows you to view and set the location of the Template directory. This directory is by located by default in
C:\Program Files\Elsinore Technologies\IssueNet\Notification Templates.
Edit1.2 Creating a New Template
Based on the selected Template Directory, the Service Browser will display the root template directory and all folders located within that directory. When a directory is selected, the browser will display all template files contained in the folder.
From the Service Browser you can create new template folders by selecting the desired parent directory and choosing the right-click
New Folder menu item. The Service Manager provides template folders as a simple way to manage large numbers of notification templates. By default, the template directories organize the templates based on the class for which each template is designed to notify.
To create a new notification template right-click on a template directory and select
New Template or select
File|New|Template from the menu. The new template will be created in the currently selected template folder.
Edit1.3 Editing an exiting Template
To begin editing a notification template simply double click on it in the Service Browser. The template will open in an editor that features a View mode and Design mode.
Edit2 View Mode
The template View mode renders the template as closely as possible to the appearance of an email notification generated from that template. This mode provides a simple way to preview the design of a template as you edit it. The View mode will refresh each time you select it based on any changes made in Design mode.
In View mode you may notice template elements enclosed in parentheses and prefixed by a “$” symbol. A common example of one of these elements is: "$(Notification.Rule)." These elements are template tags. The values in the parentheses are variables that are substituted for the actual values when a notification is sent. Since the actual value of a variable cannot be known during design, the View mode displays the tags as they were entered in the template design.
Edit3 Design Mode
The Design mode allows you to edit the template subject and body using a combination of standard HTML code and IssueNet specific property tags.
Edit4 Template Editing Basics
While the Template editor is nearly a WSYIWYG editor, there are some basic rules and best practices to tailor the appearance and content of your templates to best suit your particular environment.
Edit4.1 Editing the Email Subject
The text for the email subject is entered in the
Subject field of the template editor. The email subject is always interpreted as and should be edited as text. Any special formatting tags you enter will be displayed as text when a notification is generated.
Edit4.2 Editing the Email Body
The email body is entered in the Body field of the template editor The email body can be edited as text or HTML. Those two formats are the formats IssueNet officially supports. However, because IssueNet simply substitutes the content of the body field when the notification is generated, you should have success with other formats supported by your target email client.
To create a text email template, simply enter text into the body field – no special tags are necessary. To create a HTML template, begin and end the template with the standard HTML and start and end tags.
To add content to your HTML template simply type between the tags as you would for any HTML document.
Edit4.3 Using Property Tags
The templates you create and edit will contain many standard elements such as text, tables, images, and links to other content. While these elements are essential to a well designed and aesthetically pleasing template they cannot be used to provide any content specific to the item a notification is about. For example, you cannot include the text of the issue subject in your email notifications using HTML tags or text.
To allow you to incorporate the specific values of an item in your notifications, IssueNet allows you to include Property Tags anywhere in a template. A property tag is a specially formatted element. Every property tag is prefixed by a “$” symbol and encloses the tag name in parenthesis. Every tag name consists of the tag name type followed by a period “.” and the tag name value. For example, if you wanted to include the issue description in your template you would include the tag: $(Property.Description). When a template containing this tag is used to generate a notification IssueNet will look for a property named “Description” belonging to the class the notification is about and substitute the correct value. As a result this same tag could be used to include the description in a template for Contact notifications. In a similar fashion, to include the Issue Status in a notification, you would simply include the tag: $(Property.Status).
Edit4.4 Using the Property Tag Menu
In any IssueNet solution the number of different properties may be large and remembering all of the property names can be a challenge. In addition any IssueNet solution can be easily customized to include new classes and class properties. To make adding a wide variety of standard and custom properties to templates simple and minimize typing, IssueNet provides a Property Tag Menu that can be dynamically generated whenever you edit a template. To use the Property Tag Menu:
Select
File|Connect to connect to the IssueNet solution. Once you connect, IssueNet will load all valid properties for every Class contained in the solution. Open a template for editing. In the Class box at the top of the template editing window select the class the template is being designed for. In Design mode right-click at the location in the template where you want to add a tag, select Property Tags and pick the property you want to add from the submenu.
Edit4.5 Using Queue Tags
In addition to tags for class properties, the IssueNet Service Manager also features tags for common, or boilerplate, information most organizations would include in every template. Instead of adding the information to each template you can define the value for each tag in the properties of the notification queue, and then add the tag to each template where necessary. Whenever you want to change the information included in the template, you can simply change the tag value instead of editing each template.
The values for the Queue Tags are defined in the properties of each notification queue you create. To edit the Queue Tag values, double-click on a queue and click on the Constants tab. On the Constants tab you can edit the following tags:
- Header - Common text used to identify the type and origin of the notification. For example, “Elsinore Technologies, Inc. – Issue Notification”
- Copyright - Copyright information for the information contained in the notification
- Reference URL - A common URL value to be used throughout the notification
- Logo URL - A URL for referencing a logo image to be included in each notification email Address
- Email Address - Typically, this would be the email address of the IssueNet Administrator
- NULL Text - Text to be substituted in the event that a field defined in the template has a NULL value. Typically, this would be set to None
- Privacy - Text for a privacy policy statement to be included in each notification
Edit4.6 Using the Queue Tab Menu
Like Property Tags, Queue Tags can be added can be added to a template using a right click menu. To add a Queue Tag to a template, right-click in a template in Design mode and select
Queue Tags and pick the property you want to add from the submenu.
Edit4.7 Other Tags and Properties
IssueNet includes a special tag for adding the name of the notification action that generated the notification: $(Notification.Rule). Adding the rule name to the template can help users identify the specific event or workflow transition that triggered a notification. To add a Rule Tag to a template, right-click in a template in Design mode and select Queue Tags and pick Rule from the submenu.
One can also add a URL tag to a template so that users can click on a link in the notification and be taken to the item being referenced in the notification. To add a URI Tag to a template, right-click in a template in Design mode and select URI Tag.
The Queue constants also allow you specify a Null Text value. If there is no value for a property when a notification is sent out the Null Text value set in the Queue constants is substituted for that value. For example, if there is no text in the description of an issue and a notification is generated based on its information, the NULL Text value can be used to include indicative text such as “Not Specified”. The NULL Text property performs a function very similar to the “This page intentionally left blank.” message included in other types of documents.
Edit4.8 Template Editing Tips
- Use the templates installed by IssueNet as examples. The stock templates have been based on successful designs and provide examples of every type of property tag.
- Focus on making the subject as informative as possible by using property tags. A well designed subject often provides a user all of the information they need.
- Use the ClassID tag, $(Property.ClassID), to substitute the class name instead of coding it into the template. The ClassID tag will substitute the display name of the class. By using the ClassID tag you can use a single template for multiple classes, and always have it display the correct class name.
- Always add the Rule tag, $(Notification.Rule), to your templates. If the notification action that generated the notification has a descriptive name, it provides a clear indication why the notification was generated.
- Only add property tags to your templates that are relevant to the change the notification is about. By focusing on the type of change the notification is about you can make your templates more informative
- The Templates must be edited on the machine on which the service manager is installed, failure to do so will result in an error message : "The notification template directory C:\Program Files\Elsinore Technologies\IssueNet\Notification Templates does not exist. Unable to load notification."