• Templates
  • Headers
    • Special Headers
  • Template Types
  • Variables
    • Perl templates
    • Selected Simple template variables
  • Templates Provided with RT
  • Queue-specific template overrides

Templates

Templates are used in RT to send notifications, typically email. You have access to RT data via variables available to you in the scope of the template. Templates can also be used for some special actions like creating a new ticket as part of the execution of a scrip.

Each template is split into two sections: a block of headers and a body. These sections are separated by a blank line. Blank lines are not allowed before the headers, but can be included in the body as needed after the headers section.

Templates are processed by the Text::Template module. This module allows you to embed arbitrary Perl code into your templates. Text wrapped in curly braces, {...} is interpreted as Perl. See Text::Template for more information.

Headers

Your template may specify arbitrary email headers. Each header is a name, a colon, then a value. So, for example, to specify a subject, you can use:

    Subject: Thanks for your bug report.

Special Headers

RT-Attach-Message: yes

This special header tells RT that any attachments that were added in the original message should also be included in the email notification going out.

Content-Type: text/html

The special header "Content-Type: text/html" tells RT that the template should be parsed as HTML. RT will automatically make the outgoing message multipart. That way, recipients who can read only plaintext email will receive something readable, while users with clients which can display HTML will receive the full experience. Please be aware that HTML support in mail clients varies greatly, much more so than different web browsers.

Starting in RT 4.2, HTML templates are included along with plain text templates for the standard RT notifications.

Template Types

Templates have a Type which dictates the level of code execution allowed.

Templates of type Perl are evaluated using Text::Template which allows arbitrary code execution. Only users with the global ExecuteCode privilege may write templates of type Perl. Prior to RT 4.0, this was the only type of Template available.

Templates of type Simple permit only simple variable interpolation. No special privilege beyond ModifyTemplate is needed to write Simple templates.

For both types of templates, text between curly braces { ... } is interpolated. For Perl templates, this text can be any code (see "Details" in Text::Template). For Simple templates, only simple variables are permitted; for example { $TicketSubject }.

Variables

Perl templates

The variables that your templates may use include:

$Transaction

The transaction object.

$rtname

The value of the "rtname" config variable.

$Ticket

The ticket object. This is only set during a ticket transaction.

$Requestor

This is not an object, but the name of the first requestor on the ticket. If this is not what you need, inspect $Ticket->Requestors.

loc("text")

A localization function. See Locale::Maketext.

The $Transaction and $Ticket objects are particularly useful. For example, here are some values you can get from each:

    $Ticket->Status      # Current status
    $Ticket->Owner       # Current owner
    $Ticket->FirstCustomFieldValue('CustomFieldName') # CF value
    $Ticket->DueObj      # Due as an RT::Date object
    $Ticket->DueObj->AsString # Current due date as a string
    $Ticket->QueueObj    # Queue object for this ticket

    $Transaction->Type     # Type of transaction
    $Transaction->OldValue # Previous value, if type is Set
    $Transaction->NewValue # New value, if type is Set
    $Transaction->CreatorObj->EmailAddress # Email address of trans creator

You can see the methods available in the RT::Ticket and RT::Transaction documentation.

Selected Simple template variables

Since method calls are not allowed in simple templates, many common method results have been placed into scalar variables for the template's use. Among them:

$TicketId

$TicketSubject

$TicketStatus

$TicketQueueName

$TicketOwnerName

$TicketOwnerEmailAddress

$TicketCF(Name)

For example, $TicketCFDepartment. For CFs with more complicated names, all non-word characters (anything that is not letters, numbers, or underscores) are stripped to determine the appropriate variable name.

$TransactionType

$TransactionField

$TransactionOldValue

$TransactionNewValue

$TransactionData

$TransactionContent

$TransactionDescription

$TransactionBriefDescription

$TransactionCF(Name)

For example, $TransactionCFLocation.

Templates Provided with RT

RT comes with a set of templates for the default notifications. As you start to customize your templates, these templates are a good place to look for examples. As you customize, it can be helpful to create new templates and update your scrips to reference your new templates. This leaves the original RT templates in place for easy reference.

Starting in RT 4.2, each template has a plain text version and an HTML version. For example, the "Correspondence" template is the plain text version of the default template for correspondence (replies) and the "Correspondence in HTML" template is the same template formatted in HTML. The 4.2 upgrade provides a switch-templates-to script to switch all default templates from plain text to HTML or the reverse. See the UPGRADING-4.2 notes for details.

Queue-specific template overrides

Each scrip in RT has a template associated with it. When a scrip goes to send email (or use its template for some other purpose), it first tries to load a queue-level template with that name. If there is no queue-level template, then the scrip will continue by loading the global template with that name.

You can take advantage of this to customize your templates for a specific queue by creating a queue-level template with the exact same name as a global template. For example, you can make an "Autoreply" template for your Security queue which has a completely different message. Other queues will continue to use the global "Autoreply" template, but for the Security queue, its special "Autoreply" override will be used.

One common pattern is to create a blank template, which the "send email" action takes as a hint to avoid sending its email. So by creating a blank queue template you can "disable" a specific notification, such as Ticket Taken, for an individual queue, while still keeping the scrip globally applied to all queues.

You can manage queue-specific templates by visiting Admin -> Queues -> Select -> ... -> Templates.

← Back to index