Merge branch '4.4-trunk' into 5.0-trunk

5 files changed, 112 insertions, 0 deletions

diff --git a/docs/UPGRADING-4.4 b/docs/UPGRADING-4.4
index 0893209a05..78b164f011 100644
--- a/docs/UPGRADING-4.4
+++ b/docs/UPGRADING-4.4
@@ -678,6 +678,18 @@ so batch runs only once for the outermost updates. All transactions
 performed for that batch are available from the C<TransactionBatch> method
 as expected.
 
+=item * Ambigious Owner order by option in search replaced with Owner.Name
+
+RT 4.4.5 adds a bunch of new order by and format options for users and roles
+to the Query Builder. For example, you can order by user fields on a user
+like Owner.EmailAddress, Owner.RealName, or even Owner.Organization.
+As part of this change, the previous Owner entry has been renamed to
+Owner.Name.
+
+The upgrade scripts include a step to make this change in any saved searches
+in the database automatically. If you have Owner as an order by field in
+searches stored elsewhere or as a link, you can update to Owner.Name manually.
+
 =back
 
 =cut
diff --git a/docs/charts.pod b/docs/charts.pod
index 658a97832e..242f42e72b 100644
--- a/docs/charts.pod
+++ b/docs/charts.pod
@@ -169,6 +169,27 @@ Now we can see that our culprit seems to primarily be the root user, who
 is getting a bunch of work done but isn't taking tickets. Maybe we just
 need to remind root to take tickets.
 
+=head2 Group By with Roles
+
+As shown in the example above, you can group by ticket roles to get a
+view of tickets based on how various users are attached to the tickets.
+Owner is a single-user role meaning a ticket can have only one Owner,
+so for that type of group-by, your ticket totals will be the same as
+your search result total.
+
+However, most roles allow multiple users. For example, AdminCc can have
+the users staff1 and staff1 both assigned, or even one or more groups. In
+this case, a group-by chart will show all tickets where staff1 and staff2
+are AdminCc's. If they are both on one ticket, it will be charted once for
+each, so for these types of group-by graphs, the ticket total isn't shown
+because it's no longer the same as the total tickets returned by your
+original search.
+
+Starting in RT 4.4.5, you can also group by custom roles. Note that these
+group-by charts do a "shallow" search, meaning they group by direct members
+of the role and do not go further down to chart members of groups who are
+assigned to a role.
+
 =head2 Using Multiple Group Bys
 
 As you can see in the previous example, RT's charts allow you to define
diff --git a/docs/images/user-time-worked-report.png b/docs/images/user-time-worked-report.png
new file mode 100644
index 0000000000..2ae34deca6
--- /dev/null
+++ b/docs/images/user-time-worked-report.png
diff --git a/docs/query_builder.pod b/docs/query_builder.pod
index 7e2be2ba36..bed320905f 100644
--- a/docs/query_builder.pod
+++ b/docs/query_builder.pod
@@ -163,6 +163,22 @@ this search:
 
 the results will contain that ticket.
 
+You can also search for group names on roles. For core roles, you can
+select from the dropdown with group names containing "Owner Group", etc.
+Following the example above, if you wanted to find tickets with
+the Helpdesk group assigned to the AdminCc role, you can use this search:
+
+    AdminCCGroup = 'Helpdesk'
+
+You can also search for groups on custom roles using the Name value.
+A search for a group on a custom role looks like:
+
+    CustomRole.{Department}.Name = 'Helpdesk'
+
+Note that if you also have a user with the name 'Helpdesk', the custom
+role search will return all matches, so you will see tickets with both
+username 'Helpdesk' and the group 'Helpdesk' assigned.
+
 =head2 Shallow Searches
 
 In some cases you may want to see tickets only when the user you are
@@ -280,6 +296,55 @@ tickets the transactions should be on. In our example, we probably only want
 to see active tickets, so in the bottom Ticket Fields section you can select
 Status "is" and "Active". This will then filter out inactive statuses.
 
+=head1 Advanced
+
+In addition to the graphical query builder, RT also has an Advanced page
+where you can write and modify queries and formats directly. For example,
+you can type the following query directly in the Query box:
+
+    Status = 'resolved' AND Resolved > '2019-04-01' AND Queue = 'RT'
+
+and then click "Apply" to let RT validate it. RT will display any syntax errors
+if you make any mistakes so you can fix them.
+
+=head2 Valid Search Values
+
+In the above example, search values like C<'resolved'>, C<'2019-04-01'>,
+and C<'RT'> are all literal search terms: a status, a date, and a string
+representing the name of a queue. These are all static values that will then
+return matching tickets. However, sometimes you want to compare 2 columns
+in RT tables without knowing exact values. This is also supported, for
+example:
+
+=over
+
+=item Search tickets where LastUpdated is after (later than) Resolved
+
+    LastUpdated > Resolved
+
+This finds tickets that have been commented on or otherwise updated after
+they were resolved. Note that C<Resolved> is not quoted, indicating that it's
+the relative date value from a ticket instead of the literal string "Resolved".
+
+=item Search tickets where the Requestor is also the Owner
+
+    Requestor.id = Owner
+
+=item Search tickets where custom fields Foo and Bar have the same value
+
+    CF.Foo = CF.Bar
+
+This is equal to:
+
+    CF.{Foo} = CF.{Bar}
+    CF.Foo = CF.Bar.Content
+
+To compare LargeContent instead:
+
+    CF.IP = CF.IPRange.LargeContent
+
+=back
+
 =head1 Learn More
 
 To use the query builder to build and save reports, see
diff --git a/docs/reporting/user_time_worked.pod b/docs/reporting/user_time_worked.pod
new file mode 100644
index 0000000000..af2d02bba6
--- /dev/null
+++ b/docs/reporting/user_time_worked.pod
@@ -0,0 +1,14 @@
+=head1 Introduction
+
+The User Time Worked report allows for users to see time worked on tickets
+for an open ended date range. Users can limit the data returned by either
+User or Queue value. The data by default is organized by the date that the
+time was worked, but can also be sorted by User, Queue or Ticket.
+
+=head2 Example
+
+=for html <img alt="Example User Time Worked Report" src="../images/user-time-worked-report.png">
+
+=for :text [Example User Time Worked Report F<docs/images/user-time-worked-report.png>]
+
+=for :man [Example User Time Worked Report F<docs/images/user-time-worked-report.png>]