Ozibug - web based bug tracking


  1. Introduction
  2. Templates
  3. Tags
  4. Selecting mail templates
Back to index
 

This howto describes what is involved in creating templates for the subject and body of email notifications.

Back to top
 

All mail notification templates are stored in the directory usually located under the servlet context directory which will have the following path OZIBUG_HOME/WEB-INF/templates/notifications where OZIBUG_HOME is the directory where the Ozibug war file was unzipped (or expanded) in.

The templates can be any type of text based file such as txt, html, xml or csv, the only requirement is that the characters are encoded as UTF-8 characters, ie., no binary representations of Unicode characters should be included. Unicode characters can be added to the templates by using an ascii Unicode escape sequence \uXXXX where XXXX is the character code, for example \u00AB is the escape sequence for the single character '<<' and \u00BB is the escape sequence for the single character '>>'.

The template used for the subject of the email notification should be a plain text file consisting of a single short line. Any CRLFs present in the file will be converted to spaces prior to sending the notification, and the subject will be truncated to 65 characters in order to be suitable for viewing in most mail readers.

The template used for the body of the email notification will typically be plain text or html. Consideration should be given to the mail readers used by the recipients of the email notifications if a format other than plain text is to be used.

Three example templates are shipped with Ozibug, default_subject.txt, default_body.txt and default_body.html. Depending on requirements, one option is to create templates for each module.

Note: You should never change the original template files that are shipped with Ozibug. You should create new files so that you can always fallback to the shipped files.

Back to top
 

The templates are based around replacement tags which are processed during email generation and substituted with the updated bug data from Ozibug. The tags are of the form <tag name="fieldName"/>, where the fieldName is one of those listed below.

  • Standard fields. These are available for all modules.
    • Non repeating fields. Substitution occurs for an occurrence of these fields one time only.
      • system - the name of the system, typically Ozibug
      • action - a short description of the change made to the bug that caused the email notification. The types of update and their corresponding substitution values are
        • new bug - created
        • new assigned bug - (new) has been assigned to you
        • updated bug - updated
        • assigned bug - has been assigned to you
        • reassigned bug - has been re-assigned
      • module - the name of the module
      • id - the formatted bug id
      • status - the status of the bug
      • priority - the priority of the bug
      • assignee - the assignee of the bug
      • creator - the creator of the bug
      • updated - the last updated date and time of the bug
      • notifications - the notifications of the bug
      • privacy - the privacy of the bug
      • description - the (short) description or summary of the bug
      • detail - the detailed description (or first comment) of the bug
      • resolution - the last comment (if there was one) of the bug
      • previousDetails - the formatted module/bug id of the bugs previous location in the case of a moved bug
      • linkedBugs - a comma separated list of formatted module/bug ids of linked bugs (if there are any)
      • updateDate - the date of the update to the bug
      • updateUser - the updator of the bug
      • updateUserName - the full name of the updator
      • updateDescription - the description of the update (ie. audit trail entry)
      • viewBugLink - the url that provides direct access to view the updated bug in Ozibug. If this link is followed when a current Ozibug session is active then the view bug page will be displayed, if there is no active session then the user will first be required to login before being redirected to the view bug page. Access control is enforced when attempting to view the bug, and an error page will be displayed if access is denied to the bug. Note: To customize the value of this url, set the base system url system preference.
    • Repeating fields. All repeating data must be placed between the <repeat> and </repeat> tags, both of which must be present on a line by themselves.
      • fileAttachmentId - the id of a file attachment
      • fileAttachmentDate - the date of a file attachment
      • fileAttachmentContentType - the content type of a file attachment
      • fileAttachmentSize - the size of a file attachment
      • fileAttachmentDescription - the description of a file attachment
      • commentDate - the date of a comment
      • commentUser - the creator of a comment
      • commentDescription - the description of a comment
      • auditDate - the date of an audit trail entry
      • auditUser - the creator of an audit trail entry
      • auditDescription - the description of an audit trail entry
  • Custom fields. These are the custom categories that are enabled for the module being reported on. They are non-repeating fields and the field names are the names of the categories.
Back to top
 

Mail templates can be configured on a per module basis. This is achieved through the selection of the module reference data option from the top navigation panel for the admin user. The mail template fields allow selection of suitable templates for both the subject and body of email notifications for the required module.

If a template is not selected, an error occurs at the time of the email generation (perhaps due to a missing file or invalid tags) then a default template is used.

Back to top
 
Back to index