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