rt/docs/charts.pod

   1 =head1 RT Charts
   2
   3 RT has a built-in charting feature to allow you to create charts
   4 and graphs to visualize ticket data. Charts can be useful for
   5 anything from one-off reports (how many tickets did we process
   6 last year?) to regular status reports that you then include in
   7 shared dashboards that everyone can see.
   8
   9 RT has had charts for a long time, but many significant improvements
  10 came in RT 4.2. If you're running a version of RT earlier than
  11 4.2 some options and features described here may not be available.
  12
  13 =head1 Enabling Charts
  14
  15 =head2 Installing GD
  16
  17 While charts is a core part of RT, you do need to enable it using
  18 the C<--enable-gd> option and install the required dependencies when
  19 you install RT. If you didn't originally install with this flag, you can
  20 enable it by re-running the L<< C<configure> >> script from the RT
  21 distribution (including all previous options passed to it originally)
  22 or doing the following in your current install:
  23
  24 =over
  25
  26 =item 1
  27
  28 In your C<RT_SiteConfig.pm> set C<$DisableGD> to 0:
  29
  30     Set($DisableGD, 0);
  31
  32 =item 2
  33
  34 Run the RT dependency checker:
  35
  36     $ /opt/rt4/sbin/rt-test-dependencies --with-gd --verbose
  37
  38 =item 3
  39
  40 Install GD libraries
  41
  42 GD is an open source graphics library and it is available as a package
  43 for most Linux systems. The package might be called C<gd>, C<gd2>, C<libgd2>,
  44 or something similar. On some systems you will also need additional package
  45 required to compile code using the library. The package might be called
  46 C<gd-devel>, C<gd2-dev>, or something similar.
  47
  48 =item 4
  49
  50 Install Perl GD modules:
  51
  52     $ /opt/rt4/sbin/rt-test-dependencies --with-gd --install --verbose
  53
  54
  55 =back
  56
  57 =head2 Chart Configuration Options
  58
  59 By default, RT is configured to use the "Droid Sans" font for Unicode support
  60 across English, many western european languages, Chinese (Traditional and
  61 Simplified), and Japanese.  If you prefer to use a different font, you can
  62 change the L<< "C<%ChartFont>"|RT_Config/ChartFont >> option.
  63
  64 There is also an option to use database timezone conversion for PostgreSQL
  65 and MySQL to enable timezone conversion for time-based reports. See
  66 F<docs/customizing/timezones_in_charts.pod> for details.
  67
  68 Search for "Chart" entries in L<< C<RT_Config> >> for more information on these
  69 options.
  70
  71 =head1 Basic Charting
  72
  73 Charts are based on the set of tickets returned by a search, so every chart starts
  74 with a search of your RT tickets. When constructing your search, think about
  75 the report you need to generate and try to narrow the results to the set
  76 of tickets that will have the information you want.
  77
  78 =head2 Basic Ticket Search
  79
  80 As a basic example, assume you want to look at activity in July 2012 for
  81 the General queue. First use the Query Builder to build a query with
  82 something like:
  83
  84     Queue = 'General'
  85     AND Created >= '2012-07-01'
  86     AND Created <= '2012-07-31'
  87
  88 This search will give you tickets for July because the criteria uses before
  89 and after for the dates.
  90
  91 This search shows one of the initial things you'll want to consider, which is
  92 the element of ticket metadata you want to use as the basis for time. In
  93 the example we're using Created, but depending on what you are reporting
  94 on you might want Started, Resolved, or any of the other ticket time values.
  95
  96 When selecting the criteria for the time search, make sure it
  97 is appropriate to the report you want to see and be consistent so you
  98 are looking at the right set of tickets in the search and the resulting
  99 charts and reports.
 100
 101 For this example, we'll say the activity we want to look at is new
 102 tickets coming into the queue, and Created works well for that.
 103
 104 =head2 Ticket Charts
 105
 106 If we run the search and look at the results, we get the standard
 107 RT search results page. From this page we can click on Chart in the submenu
 108 on the upper right of the page. This brings us to the Charts page with a
 109 default bar chart showing tickets by status in the General queue.
 110
 111 =for html <img alt="General Queue Status Chart" src="images/general-status-chart.png">
 112
 113 =for :text [General Queue Status Chart F<docs/images/general-status-chart.png>]
 114
 115 =for :man [General Queue Status Chart F<docs/images/general-status-chart.png>]
 116
 117 This chart gives us a nice view of tickets by status and the good news is
 118 most of the tickets in this time period have been resolved. Under the graph
 119 is a "Group by" section and we can see "Status" is selected as the criteria
 120 in the first dropdown in the first section. The second dropdown is also Status
 121 since status only has one representation.
 122
 123 Now let's assume we want to see who was working on those tickets. You can
 124 select Owner from the first 'Group tickets by' dropdown and you'll see
 125 the second dropdown now has options to display labels based on RT user
 126 entries. Select an option and click 'Update Chart' and now you'll see
 127 the tickets displayed by Owner.
 128
 129 =for html <img alt="General Owner Chart" src="images/general-owner-chart.png">
 130
 131 =for :text [General Owner Chart F<docs/images/general-owner-chart.png>]
 132
 133 =for :man [General Owner Chart F<docs/images/general-owner-chart.png>]
 134
 135 In this case, we can see that although people are resolving tickets, they
 136 aren't Taking the tickets and Owner is not getting set. We may want to
 137 remind people to take tickets or even create a scrip to set Owner
 138 automatically on reply or resolve.
 139
 140 Before we do that, we can use more chart features to find out more about
 141 what's going on. The "Group by" portlet allows us to set multiple criteria,
 142 so in the second set of dropdowns we'll select LastUpdatedBy and Name
 143 and click 'Update Chart'.
 144
 145 =for html <img alt="General Owner LastUpdatedBy Chart" src="images/general-owner-lastupdated-chart.png">
 146
 147 =for :text [General Owner LastUpdatedBy Chart F<docs/images/general-owner-lastupdated-chart.png>]
 148
 149 =for :man [General Owner LastUpdatedBy Chart F<docs/images/general-owner-lastupdated-chart.png>]
 150
 151 Now we can see that our culprit seems to primarily be the root user, who
 152 is getting a bunch of work done but isn't taking tickets. Maybe we just
 153 need to remind root to take tickets.
 154
 155 =head2 Using Multiple Group Bys
 156
 157 As you can see in the previous example, RT's charts allow you to define
 158 multiple criteria for grouping data from your search results. In many cases,
 159 grouping multiple levels of criteria can reveal interesting and useful graphs.
 160 To give you the greatest flexibility possible, the RT interface allows you
 161 to select from nearly all ticket values, but not all combinations of group
 162 by criteria will make sense or create a helpful chart. If you select some
 163 options and produce a chart that looks jumbled, consider again what
 164 you're trying to visualize from the data.
 165
 166
 167 =head1 Calculated Values
 168
 169 The Calculate section of the RT charts interface allows you to generate
 170 charts with calculated time values. You can select time values used in time
 171 tracking (e.g., TimeWorked) and calculated values from the various timestamps
 172 on tickets like Created, Resolved, etc. Once you have selected the values or
 173 ranges you want to view, you can choose to see an Average, Total, Maximum,
 174 Minimum or a summary presenting them all.
 175
 176 =head2 Viewing Ticket Response Times
 177
 178 As described above, the Calculate section allows you to pull out durations
 179 like how long it took for tickets to be opened, which is the difference
 180 between Created and Started. To create a chart with this information,
 181 we first create a new search to return all resolved tickets for a select
 182 group of queues we're interested in. You could also add some date criteria
 183 to narrow the search to a range of time as in the previous example.
 184
 185 After getting our result set and clicking on Charts, we select
 186 Queue from the "Group by" section so we see data grouped by the queues we
 187 selected. In the Calculate section we select Created-Started from the
 188 first dropdown and the Summary option from the second dropdown and click
 189 "Update Chart".
 190
 191 This generates a detailed chart with a bunch of time data for all of the
 192 queues we selected in our search. It's a little busy, so we might look at
 193 some of the other display options available in the second dropdown.
 194 What we're really interested in is the average time from Created to Started,
 195 since this will give us a general idea how long it's taking people to
 196 initially respond to requests.
 197
 198 The second dropdown in the Calculate section has an option for
 199 "Average Created-Started". If we select that and update the
 200 chart, we see a nice graph of average time for tickets to be opened across
 201 all of the queues we selected.
 202
 203 =for html <img alt="Queue Created Started Chart" src="images/queue-created-started-chart.png">
 204
 205 =for :text [Queue Created Started Chart F<docs/images/queue-created-started-chart.png>]
 206
 207 =for :man [Queue Created Started Chart F<docs/images/queue-created-started-chart.png>]
 208
 209 Now perhaps we also want to see how long tickets stay active. In the Calculate
 210 section you can add Started-Resolved to the first "and then" and select
 211 "Average Started-Resolved" from the second dropdown. Click "Update Chart"
 212 and you've now got a graphical view of how long, on average, tickets are
 213 waiting to be opened and how long people are working on them.
 214
 215 If you use RT for time tracking, you can create similar useful charts
 216 using TimeEstimated, TimeWorked, and TimeLeft.
 217
 218 =head1 Chart Style and Size
 219
 220 Charts default to a bar style, but you can display data as a pie chart
 221 by selecting pie in the "Picture" portlet. You can also adjust the width
 222 height of the generated chart by entering a size in pixels. These width
 223 and height values are saved if you save the chart and are used if
 224 you include the chart on a Dashboard as well.
 225
 226 =head1 Saving Charts
 227
 228 Much like searches, you can save charts once you get them configured the
 229 way you want. The Privacy setting determines who else on the RT system
 230 will be able to see your saved charts. Note that this setting applies only
 231 to the chart itself and not necessarily the data included which may still
 232 be blocked from other users.
 233
 234 To save a chart, select a Privacy setting, give it a Description and click
 235 Save. Once saved, you can retrieve the chart later by coming to the chart
 236 page and selecting it from the "Load saved search" dropdown and clicking
 237 Load.
 238
 239 When you save a chart, it also becomes available to the Dashboard interface.
 240 This allows you to go to Home > New Dashboard and create a Dashboard that
 241 shows the chart you have created. This can be very useful for charts you
 242 want to monitor frequently or create for others.
 243
 244 If you need to change a chart, load it, make your changes, then click
 245 Update. Delete deletes the saved chart and will also remove it from all
 246 Dashboards that are using it.