docs/dashboards.pod

   1 =head1 Dashboards
   2
   3 RT's dashboard feature provides a convenient way to create your own pages
   4 focused on the tickets and charts you need. Dashboards are available right from
   5 the Home menu, can be set up individually or shared, and can even be sent out
   6 via email on a schedule. To show some of the dashboard features, we'll set up a
   7 dashboard and notifications to track outstanding invoice tickets.
   8
   9 There are several different rights you can grant to allow users access to the
  10 features described here. These rights are described in L</"Dashboard Rights">.
  11
  12 =head2 Creating a Personal Dashboard
  13
  14 Saved searches and charts are the building blocks of dashboards, so to set up a
  15 new dashboard you first need to create and save a search that displays the
  16 ticket data you want. We want to view new and open invoice tickets and, for our
  17 example, assume we have an Accounts Receivable queue. On the ticket search
  18 page, we create a new search with this query:
  19
  20     Queue = 'Accounts Receivable'
  21     AND (
  22         Status = 'new'
  23         OR Status = 'open' )
  24
  25 We also want to modify the sort order of the search to use Due rather than the
  26 default id. In the Sorting section, we select Due for the initial sort, then
  27 add Created as the second sort value. Finally, we set Rows per page to
  28 Unlimited so we don't miss any invoices.
  29
  30 =for html <img alt="Dashboard search sorting"
  31 src="images/dashboard-search-sorting.png">
  32
  33 =for :text [Search sorting F<docs/images/dashboard-search-sorting.png>]
  34
  35 =for :man [Search sorting F<docs/images/dashboard-search-sorting.png>]
  36
  37 Once you have those set, you can click "Add these terms and Search" or "Update
  38 format and Search" to see the results. If it's still not quite right, you can
  39 click "Edit Search" in the submenu and continue to refine things.
  40
  41 When you're finished tweaking the search, return to Query Builder page again so
  42 you can save it. Under the "Saved Searches" box, type "Outstanding Invoices"
  43 in the Description box. For now, leave Privacy set to "My saved searches" and
  44 click Save. You now have a saved search you can use for your dashboard.
  45
  46 To create the dashboard, select Home > New Dashboard. Type "Outstanding
  47 Invoices" for the name and leave the privacy set to "My Dashboards". Click
  48 Create and the new dashboard is created.
  49
  50 Now we want to populate the new dashboard with the saved search we created.
  51 Click Content in the submenu to go to the content selection page. Dashboards
  52 allow you to put content in the main body or the sidebar, much like the default
  53 RT homepage, so you'll see a Body section and a Sidebar section to set the
  54 content. Find your saved "Outstanding Invoices" search, select it, and click
  55 the arrow to move it to the righthand box and add it to the dashboard.
  56
  57 =for html <img alt="Adding dashboard content"
  58 src="images/dashboard-content-invoices.png">
  59
  60 =for :text [Adding dashboard content
  61 F<docs/images/dashboard-content-invoices.png>]
  62
  63 =for :man [Adding dashboard content
  64 F<docs/images/dashboard-content-invoices.png>]
  65
  66 Click Show in the submenu and you'll see your new dashboard. Click Home to
  67 return to the "RT at a glance" page and you'll see your new dashboard is in the
  68 Dashboards portlet on the right side of the page.
  69
  70 On dashboard pages, you can click on the title of any section and go to the
  71 search results page for the saved search. This makes it easy to find the saved
  72 search and update it, or modify it ad-hoc for a one-off search based on the
  73 saved dashboard search.
  74
  75 In this example we're only adding one search, but you can add multiple searches
  76 to each individual dashboard to track different types of interrelated
  77 information and see it at a glance. For instance, two queries, "outstanding
  78 invoices" and "overdue invoices," could form a dashboard called "all
  79 outstanding invoices." Software engineers using RT might combine three queries,
  80 "bug fixes," "feature requests," and "documentation," into a dashboard
  81 called "our new release."
  82
  83 =head2 Charts in Dashboards
  84
  85 You can also display saved charts in dashboards, creating a powerful visual of
  86 ticket data in a convenient page. To add a chart, start with a search, refine
  87 your query, then click Chart in the submenu in the Query Builder or Search
  88 Results page. Configure your chart as described in L<charts>, select a Privacy
  89 setting, name it "Outstanding Invoices", and click Save.
  90
  91 Return to the dashboard, click Content, and you'll see a new "Chart:
  92 Outstanding Invoices" option in the Available column. Select it and click the
  93 arrow to add it to the dashboard. Now when you load the dashboard, the chart
  94 will be rendered right below the saved search.
  95
  96 =for html <img alt="Dashboard chart" src="images/dashboard-chart.png">
  97
  98 =for :text [Dashboard chart F<docs/images/dashboard-chart.png>]
  99
 100 =for :man [Dashboard chart F<docs/images/dashboard-chart.png>]
 101
 102 =head2 Dashboard Menu Entries
 103
 104 In addition to having dashboards available on the "RT at a glance" page, you
 105 can also add them to the Home menu. To modify the Home menu, select Home >
 106 "Update This Menu" or "Logged in as" > Settings > "Dashboards in menu". You'll
 107 see the Customize dashboard page which is similar to the Dashboard Content page.
 108
 109 =for html <img alt="Customize dashboard menu"
 110 src="images/customize-dashboards-menu.png">
 111
 112 =for :text [Customize dashboard menu
 113 F<docs/images/customize-dashboards-menu.png>]
 114
 115 =for :man [Customize dashboard menu F<docs/images/customize-dashboards-menu.png>]
 116
 117 Select the dashboard you want, click the arrow to move it to the righthand
 118 column, then check your Home menu. You'll see your dashboard is now available
 119 from the menu.
 120
 121 As an RT administrator, you can populate the dashboard menu for other users on
 122 the system. Find a user using Search > Users or Admin > Users > Select, then
 123 click on the user to open the modify user page. In the submenu, you'll see a
 124 "Dashboards in menu" option, and it works the same as the personal setting.
 125
 126 =head2 Group Dashboards
 127
 128 You're enjoying your new dashboard but it's time for some vacation and it would
 129 be nice for someone else in the accounting department to be able to use your
 130 dashboard while you're gone. RT makes this easy with group-level dashboards.
 131
 132 As we've seen, the dashboard is based on a saved search, so you first need to
 133 make that available. Go to the ticket search page (Query Builder), find your
 134 saved search in the "Load saved search" dropdown, and click Load. If you are in
 135 a group, like the Accounting group, there will be an option in the Privacy
 136 dropdown called "Accounting's saved searches". Select that option and click
 137 Update to make the search available to the Accounting group.
 138
 139 To update your dashboard, select it from the menu to view it, then click Basics
 140 in the submenu. Like on Query Builder page, you'll see your group listed in the
 141 Privacy dropdown. Assuming your group is Accounting, select "Accounting's
 142 Dashboards" and click Save Changes.
 143
 144 Click on Content and you'll see a message that a query has been deleted and
 145 removed from the dashboard. This is because RT has detected that you have moved
 146 the saved search from personal to group privacy. Select "Outstanding Invoices"
 147 from the Available column and click the arrow to add the group-based search to
 148 the dashboard.
 149
 150 All members of the Accounting group should now have access to your dashboard.
 151 They can now add it to their Home menu if they want. If other members can't see
 152 it, make sure you have granted sufficent rights to the group (see L</"Dashboard
 153 Rights">).
 154
 155 =head2 System-wide Dashboards
 156
 157 You can also set up dashboards for all users on your RT system. Follow the
 158 steps above for group dashboards, but for Privacy, select "RT System" for the
 159 saved search and dashboard.
 160
 161 If you want to make sure everyone has the dashboard in their Home menu, you can
 162 set this globally as well if you are the RT administrator. The Admin > Global >
 163 "Dashboards in menu" opens a page similar to the personal dashboard menu page,
 164 but it puts the selected dashboards into everyone's dashboard menu.
 165
 166 =head2 Dashboard Subscriptions
 167
 168 RT's dashboard subscription feature allows you to email dashboards based on a
 169 schedule you set. These scheduled dashboards can be particularly useful for
 170 time-based reports that you want to see on a regular basis.
 171
 172 To set up a subscription, go to the dashboard you'd like to have emailed and
 173 click on Subscription in the submenu. This will take you to the subscription
 174 page.
 175
 176 =for html <img alt="Dashboard subscription"
 177 src="images/dashboard-subscription.png">
 178
 179 =for :text [Dashboard subscription F<docs/images/dashboard-subscription.png>]
 180
 181 =for :man [Dashboard subscription F<docs/images/dashboard-subscription.png>]
 182
 183 Select the frequency and timing you want and enter the email address the
 184 dashboard should go to. You can leave it blank to send mail to your RT email
 185 address. Click Subscribe and that's it, you'll start getting dashboards via
 186 email.
 187
 188 This feature requires the F<rt-email-dashboards> script to be scheduled in
 189 C<cron> as described in RT's F<README> file.
 190
 191 =head2 Dashboard Rights
 192
 193 There are several rights you can selectively grant to allow users access to
 194 dashboard features. As with any RT rights, you can grant these to individual
 195 users (usually difficult to maintain over time), to system roles like
 196 Privileged, or to groups you define.
 197
 198 Since dashboards rely on saved searches, you need to grant "Allow loading of
 199 saved searches" (LoadSavedSearch) for users to see the searches. You may want
 200 to also grant "Allow creation of saved searches" (CreateSavedSearch) to allow
 201 users to create their own and "View saved searches" (ShowSavedSearches)
 202
 203 For dashboards themselves, there are See, Create, Modify, and Delete rights for
 204 each of personal, group, and system dashboards. This allows you to select the
 205 right combination of rights for users and groups on your system. For
 206 subscriptions, there is a "Subscribe to dashboards" (SubscribeDashboard) right.