Customizing OTRS list views

Probably if you get here, you already know about OTRS. One of the most powerful and most used help desk and incident tracking system, and much much more you can learn about in www.otrs.com

I have been using OTRS for some years at my company for both internal incident tracking and customer service. Though it's a very powerful system, with good ITIL capabilities from early versions, and very customizable in some aspects, there are some kind of customizations that are a bit tricky, at least they were for me, and I am covering one of those in this post.




I talk about customizing list views, like the ticket queue view or status view. In the default list, you can see some ticket colums (Ticket Number, Age, From / About, Status, Blocked, Queue, Owner, Customer ID).

Sometimes you may want to add another column, or maybe replace one of the default ones. In our company, we were more interested in having the Creation Date column in this list instead of the Age column.

To achieve this change you have to change the screen templates in order to add the new columns.

Changing the screen templates

The templating system is easy to customize. All the screen HTML is defined in template (.dtl) files, located in <OTRS_HOME>/Kernel/Output/HTML/Standard , to customize a template the best solution is creating a new folder <OTRS_HOME>/Kernel/Output/HTML/<TEMPLATE_NAME> and copy inside this folder the files you want to customize from the Standard template folder. My customized templates are located in <OTRS_HOME>/Kernel/Output/HTML/IMCS.

To change the overview of tickets, in both the "Queue View" and "Status View", you have to customize the template AgentTicketOverviewSmall.dtl and/or the AgentTicketOverviewMedium.dtl, I will concentrate in the first one for this example.

The .dtl files contain a mix of HTML and tags that the OTRS engine use to generate the final HTML views. By taking a look at this files and comparing them with the final HTML output you can get a good idea of how the templates work.

To change the "Age" column header with the "Creation Date" one, I just replaced this code (I have shortened the long line a bit for presentation purposes)

<!-- dtl:block:OverviewNavBarPageAge -->
   <th class="Age $QData{"CSS"}">
      <a name="OverviewControl" href="$Env{"Baselink"} ...  >$Text{"Age"}</a>
   </th>
<!-- dtl:block:OverviewNavBarPageAge -->

by this one

   <th class="Creation $QData{"CSS"}">
      <span>$Text{"Creation"}</span>
   </th>

then to change the field data replaced this code

<td>
    $QData{"Age"}
</td>

by this one to change the column data.

<td>
    $QData{"Created"}
</td>

That's it, now your list shows the Creation Date column instead of the Age one.

Some tricky issues

Take a closer look at the header changes. Maybe you have realized I removed the "<!-- dtl:block:... -->" blocks from the header. You can see too that I did change the original and long anchor tag in the table header by a simpler span tag. The reason is simple, if you change all the references to "Age" to "Creation" in that block, the column is not shown.

The reason for that issue relies in the way the screen is coded and the templating system works. In addition to the ".dtl" file you have already modified, you have the perl files that "put" the data into the template and generate the final output. This files are located in <OTRS_HOME>/Kernel/Output/HTML and if you take a look at TicketOverviewSmall.pm you can clearly see that there is a hardcoded list of columns and that list has it's own processing loop in order to make the record sorting work when you click on column headers.

        my @Col = (qw(TicketNumber Age State Lock Queue Owner CustomerID));

        # show escalation
        if ( $Param{Escalation} ) {
            push @Col, 'EscalationTime';
        }

        # check if last customer subject or ticket title should be shown
        if ( $Self->{SmallViewColumnHeader} eq 'LastCustomerSubject' ) {
            push @Col, 'LastCustomerSubject';
        }
        elsif ( $Self->{SmallViewColumnHeader} eq 'TicketTitle' ) {
            push @Col, 'Title';
        }

        for my $Key (@Col) {
            my $CSS = '';
            my $OrderBy;
            if ( $Param{SortBy} && ( $Param{SortBy} eq $Key ) ) {
                if ( $Param{OrderBy} && ( $Param{OrderBy} eq 'Up' ) ) {
                    $OrderBy = 'Down';
                    $CSS .= ' SortAscending';
                }
                else {
                    $OrderBy = 'Up';
                    $CSS .= ' SortDescending';
                }
            }

            $Self->{LayoutObject}->Block(
                Name => 'OverviewNavBarPage' . $Key,
                Data => {
                    %Param,
                    OrderBy => $OrderBy,
                    CSS     => $CSS,
                },
            );
        }

It seems that <!-- dtl:block --> not referenced in code are simply removed from the output. So you have some possible workarounds:

1.- Just write no <!-- dtl:block:... --> around your header and/or data code, as I already did in the example. That means you will see the column but no way of sorting.

2.- If you are replacing a default column like I did, then you can just leave the comment block untouched, though you will face probably problems with the sorting stuff, so will have to touch the source code anyway.

3.- Modify the ".pm" source code and add the column by hand. It seems the only solution to make the sorting stuff work.

If you want to change other views, the process is similar. You can find some differences when modifying the ITSM modules views, as an example the CMDB overview columns. I will talk about this in next posts.

I just hope you find this post useful, see you soon!!!