TemplateSnippets

From Request Tracker Wiki
Revision as of 12:26, 6 March 2020 by Phanousk (talk | contribs) (→‎Tips&Tricks)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Introduction

This page provides you with some code that can be used in notification Templates and is part of the CodeSnippets series of articles.

If you want to do something that RT does in its user interface that isn't listed here, you can take a quick look at share/html/Elements/*/ColumnMap . For example, if looking for how to create a relative due date, you'd look in RT__Ticket/ColumnMap for the DueRelative sub. (From Kevin Falcone)

Notification templates specifics

See the Template page for more on templates. This page talks about notification templates only, but there are other kinds you might want to investigate. Anyway, back to it...

In notification templates, you have to enclose code in curly brackets:

{ CODE HERE }

Templates offer some variables you will almost certainly want to use, to access specifics about the ticket or transaction for which the template is being rendered. These are accessed like any other Perl variable. For instance, The Ticket object is stored in $Ticket, and the current Transaction is in $Transaction. These, and other available objects, offer properties and methods which are, like the variables themselves, called with standard Perl syntax:

{ $Ticket->Status }

When you put a variable, like the above status example, in a template, it gets printed. If your template had the above snippet, you would see the status of the ticket in the resulting output. However, you can do a lot more than just outputting a variable's contents. Here's how to append a lot of text to a local variable before you print it. Note that here, we use "my" to signify a local variable, as opposed to a variable RT makes available to us.

{ my $out = '';
        $out .= "append some text line\n";
        foreach my $element (...) {
            $out .= "append more data $element\n";
        }
        $out; # don't forget to put $out at the end to return it
      }

Please notice that we used straight Perl in the above example. So long as it's within a set of braces ({}), any valid Perl syntax is allowed. Combine this with RT's variables, and you can see how powerful templates can be.

Code snippets

Basics

Ticket status

{ $Ticket->Status }

Queue name

{ $Ticket->QueueObj->Name }

Insert Queue email address for correspondence/comment

{ $Ticket->QueueObj->CorrespondAddress; }
{ $Ticket->QueueObj->CommentAddress; }

Puts content of the first transaction into email

{ $Ticket->Transactions->First->Content }

People

Get the email address of the user who created the ticket

{ $Ticket->CreatorObj->EmailAddress }

Get the email address of the user who created the transaction

{ $Transaction->CreatorObj->EmailAddress }

Get the name of the user who created the transaction

{ $Transaction->CreatorObj->Name }

Get the name of the user who last updated the ticket

{ $Ticket->LastUpdatedByObj->Name }

Get the email addresses of the Requestor(s)

{ $Ticket->RequestorAddresses }

Get the email addresses of the users added as CC or AdminCC to the ticket

{ $Ticket->CcAddresses }
{ $Ticket->AdminCcAddresses }

Requestors' names or other properties

Requestors: {
        # 'Requestors' may be replaced with 'Cc' or 'AdminCc'
        my $users = $Ticket->Requestors->UserMembersObj;
        my $output = '';
        while( my $user = $users->Next ) {
           $output .= ', ' if $output; # comma between values
           $output .= $user->Name; # or any other user's property
        }
        $output;
      }
      

Dates

Ticket creation time as formatted string:

{ $Ticket->CreatedAsString }

The same:

{ $Ticket->CreatedObj->AsString }

The same for Transaction

{ $Transaction->CreatedAsString }

Show the first date that is set:

 This ticket was last active on {
     my $date;
     foreach my $method ( qw(ToldObj LastUpdatedObj CreatedObj) ) {
         $date = $Ticket->$method(); # get date
         last if $date->Unix > 0; # stop on first that is set
     }
     $date->AsString;
 }

 Relative dates

You often want to show a relative ("friendly" or "humanized") date, ie "due in 35 minutes". The same approach will work for any of the $Ticket object's other dates, like Start, too. It and will append "ago" where the date is in the past.

{ $Ticket->DueObj->AgeAsString() }

This will work fine in templates invoked with rt-crontool.

Complex

Add the number of tickets in queue:

There are currently {
   my $tickets = RT::Tickets->new( $RT::SystemUser );
   $tickets->FromSQL( "Status = 'new' AND Queue = ". $Ticket->Queue );
   $tickets->Count;
 } ticket(s) awaiting processing before yours, please be patient.

Tips&Tricks

Don't show content if it's empty

{ if( my $tcc = $Ticket->CcAddresses ) { "Ticket Ccs: ". $tcc } }
{ if( my $qcc = $Ticket->QueueObj->CcAddresses ) { "Queue Ccs: ". $qcc } }
{ if( my $tacc = $Ticket->AdminCcAddresses ) { "Ticket AdminCcs: ". $tacc } }

See also

Template, CodeSnippets, CustomConditionSnippets