[[PageOutline(2-5,Contents,pullout)]]
= Manage ticket queues via drag-and-drop
== Description
This plugin converts one or more reports into work "queues". A work queue allows you to drag-and-drop tickets into their relative priority order (similar to the Netflix Queue). Ticket positions in a queue get maintained in a custom field of your choosing. This plugin requires !JavaScript and [http://jqueryui.com/ jquery-ui] (included) for the sortable behavior.
The motivation for this plugin is for when you want to organize a work load in the order you intend to tackle it, ie as a work queue. Queues can be defined or segmented by milestone or any field(s) (or no fields). See the [wiki:QueuesPlugin#Examples examples below] for more details.
== Bugs/Feature Requests
Existing bugs and feature requests for QueuesPlugin are
[report:9?COMPONENT=QueuesPlugin here].
If you have any issues, create a
[/newticket?component=QueuesPlugin new ticket].
[[TicketQuery(component=QueuesPlugin&group=type,format=progress)]]
== Download
Download the zipped source from [export:queuesplugin here].
== Source
You can check out QueuesPlugin from [/svn/queuesplugin here] using Subversion, or [source:queuesplugin browse the source] with Trac.
== Installation / Configuration
1. Install the plugin. See TracPlugins for installation details and options. You will need to restart Trac's web server after installation.
2. Enable the plugin by adding the following to your `trac.ini` file:
{{{#!ini
[components]
queues.* = enabled
}}}
You can alternatively use the Trac Web Admin GUI to enable any or all rules.
3. Create a custom field to contain the position information, example `trac.ini` file:
{{{#!ini
[ticket-custom]
position = text
}}}
4. Create/modify reports to be used as ticket queues whose first column's name must match the (custom) field created in step 3 above:
* Can contain uppercase characters, which will get converted to lowercase.
* Can use spaces, which will get removed.
5. Tell the plugin which reports to convert to queues, example `trac.ini` file:
{{{#!ini
[queues]
reports = 13,14
}}}
See the [wiki:QueuesPlugin#Examples examples below] for more detailed configuration examples, options and capabilities.
== Examples
This plugin is built from many parts of Trac, such as reports and dynamic variables. This approach takes advantage of what Trac already offers natively, while still providing flexibility in how you configure the queues. However, this flexibility is traded off against ease-of-use. So this plugin is for advanced users/administrators only!
=== Team work queue for all tickets
The simplest example is a queue of all tickets. Assuming you already created a new custom {{{position}}} field as described [wiki:QueuesPlugin#Configuration above], you can create a new report like this:
{{{#!sql
SELECT s.value AS __color__,
p.value AS position, t.id AS ticket, summary,
t.type AS type, t.severity, t.owner
FROM ticket t
LEFT JOIN enum s ON s.name = t.severity AND s.type = 'severity'
LEFT OUTER JOIN ticket_custom p ON p.ticket = t.id AND p.name = 'position'
WHERE t.status <> 'closed'
ORDER BY CAST((CASE p.value
WHEN '' THEN '0'
ELSE COALESCE(p.value, '0') END) AS UNSIGNED) ASC,
t.changetime DESC
}}}
Notice that the first column is the {{{position}}} custom field and is defined as {{{p.value as position}}}, this is ''required''. The first column's name must always match the name of the custom field used to maintain the queue position. You can name them whatever you want; they just have to match. In the ORDER BY clause, we cast the position field to an integer. This example is for sqlite3; you'll need to check the syntax for the database you're using. If your database does not support casting, you can use position padding option described below. There are no other restrictions to the SQL you use for your reports, as far as I'm aware!
If the report above was created as, say, report {{{13}}}, then you would need to add it to the {{{[queues]}}} section of the `trac.ini` file:
{{{#!ini
[queues]
reports = 13
}}}
You may need to restart your Trac web server afterwards. Here is a screenshot of the result with a few sample tickets:
[[Image(example1.png, border=2)]]
To reorder the tickets, simply drag and drop them to their desired position in the queue.
=== Team work queue per milestone
To order your work queue within a milestone, you could create a single report that uses a {{{$MILESTONE}}} [http://trac.edgewall.org/wiki/TracReports#AdvancedReports:DynamicVariables report dynamic variable] to set the milestone field:
{{{#!sql
SELECT s.value AS __color__,
p.value AS position, t.id AS ticket, summary,
t.type AS type, t.severity, t.owner
FROM ticket t
LEFT JOIN enum s ON s.name = t.severity AND s.type = 'severity'
LEFT OUTER JOIN ticket_custom p ON p.ticket = t.id AND p.name = 'position'
WHERE t.status <> 'closed' AND t.milestone = '$MILESTONE'
ORDER BY CAST((CASE p.value
WHEN '' THEN '0'
ELSE COALESCE(p.value, '0') END) AS UNSIGNED) ASC,
t.changetime DESC
}}}
If this was created as report {{{14}}}, update the {{{trac.ini}}} file:
{{{#!ini
[queues]
reports = 13,14
}}}
Restart your web server as needed.
Here's the screenshot of the report:
[[Image(example2.png, border=2)]]
In this example, the optional DynamicVariablesPlugin is used, which converts the {{{MILESTONE}}} dynamic variable (aka argument) from a freeform textbox to a convenient dropdown menu at the right.
=== Team work queue per milestone with a Triage group
The problem with the above example is that new tickets without a {{{position}}} field will get ordered above your other tickets. This may not always be what you want. So instead you can group the tickets into those with a position and those without and then individually drag-and-drop the new tickets into the ordered queue at your leisure. Here's what the report could look like:
{{{#!sql
SELECT s.value AS __color__,
(CASE p.value
WHEN '' THEN 'Triage'
WHEN NULL THEN 'Triage'
ELSE '$MILESTONE'
END) AS __group__,
p.value AS position, t.id AS ticket, summary,
t.type AS type, t.severity, t.owner
FROM ticket t
LEFT JOIN enum s ON s.name = t.severity AND s.type = 'severity'
LEFT OUTER JOIN ticket_custom p ON p.ticket = t.id AND p.name = 'position'
WHERE t.status <> 'closed' AND t.milestone = '$MILESTONE'
ORDER BY (CASE p.value
WHEN '' THEN 'Triage'
WHEN NULL THEN 'Triage'
ELSE $MILESTONE END = 'Triage') DESC,
CAST((CASE p.value
WHEN '' THEN '0'
ELSE COALESCE(p.value, '0') END) AS UNSIGNED) ASC,
t.changetime DESC
}}}
In addition to updating `trac.ini` with the new report number, you now also need to describe what operation the plugin should take for each group:
{{{#!ini
[queues]
reports = 13,14,15
group.triage = clear
}}}
The {{{group.triage = clear}}} tells the plugin that the {{{Triage}}} group shouldn't reorder positions (reordering is the default operation). The group name {{{Triage}}} is just an example - you can use any name as long as you make the config match it. Here's the screenshot of the report:
[[Image(example3.png, border=2)]]
The tickets are now grouped with the Triage group at the top. You can drag-and-drop tickets from the {{{Triage}}} group to anywhere in the {{{milestone1}}} group. Furthermore, you can also clear the position from any ticket by dragging-and-dropping it from the {{{milestone1}}} group to anywhere in the {{{Triage}}} group (hence the full meaning of the {{{clear}}} operation described above). Note that currently a group must have at least one ticket in it to be able to drag-and-drop tickets into it.
The full list of operation directives is:
* {{{reorder}}} (the default)
* {{{clear}}}
* {{{ignore}}}
There must be only one {{{reorder}}} group per report but you can have any number of {{{clear}}} and {{{ignore}}} groups. The {{{ignore}}} operation will simply list the tickets that match your grouping, but tickets can't be moved out of or into it. This is useful, for example, if you want to show work in the queue that has been implemented but still in, say, a {{{verifying}}} state and not yet closed. The SQL syntax is left as an exercise to the reader.
'''Tip''': You can click on any {{{clear}}} or {{{ignore}}} group heading to toggle between hiding and showing its tickets.
=== Team work queue per custom field
Another use case is when you want to retain the use of milestones as an orthogonal, date-based means to manage work and use a separate custom field to define queues. For example:
{{{#!ini
[ticket-custom]
position = text
queue = select
queue.options = |Queue 1|Queue 2|Queue 3
}}}
You can simply re-write your SQL query to pivot on a {{{$QUEUE}}} dynamic variable, in this example, instead of (or perhaps in addition to) a {{{$MILESTONE}}} dynamic variable. The important thing is that the {{{position}}} custom field must only be used for one and only one queue.
=== Personal work queue
You can create a queue for any SQL report as long as the {{{position}}} custom field is used for one and only one queue. Another use case is if you want to use queues simply to let users manage their own work load. You can simply create a report that pivots on the special, built-in {{{$USER}}} dynamic variable. Viola! Personal work queues for everyone using a single report.
=== Team work queue ''and'' personal work queue
What if you wanted both a team work queue that pivoted on, say, a custom {{{queue}}} field and personal work queues as described above? We can't reuse the same {{{position}}} field for each queue. The answer is to create a second custom field to manage the personal work queue's position:
{{{#!ini
[ticket-custom]
position = text
myposition = text
queue = select
queue.options = |Queues 1|Queue 2|Queue 3
}}}
Now you can use the {{{position}}} field as before for the team work queues and the {{{myposition}}} field for the personal work queues using all of the techniques described above. So for instance, the personal work queue in this case may define the first column as {{{mp.value as "My Position"}}}. Any uppercase letters are converted to lowercase and any spaces are removed in order to determine the correct field name.
=== Development work queue ''and'' Product Management work queue
The same principle described above for simultaneously supporting team and personal work queues can be used to enable work queues for multiple stakeholders by using separate {{{position}}} fields. So for example, Product Management may want to express their preferred order of work (beyond what a {{{priority}}} field permits) while the development team can use a report/queue that shows Product Management's preferred ordering alongside their own ordering.
== Tips / Options
=== Position padding
Whether or not you cast the {{{position}}} field into an integer for report ordering, you still may want to pad your position numbers with leading {{{0}}}s so that they sort correctly in any report or custom query in which they appear. You set this up globally in `trac.ini`:
{{{#!ini
[queues]
pad_length = 2
}}}
A {{{pad_length}}} of {{{2}}} is the default. This means that position 1 will become position {{{01}}}, etc. Position 10 remains {{{10}}}, and 100 remains {{{100}}}. Set it to {{{1}}} for no padding.
=== Maximum position
Typically, the further down a queue you go, the less accurate the ordering becomes. This is natural. Which means that after a point, ordering doesn't really matter anymore. One way to help reinforce this is by defining a {{{max_position}}} value:
{{{#!ini
[queues]
max_position = 99
}}}
A {{{max_position}}} of {{{99}}} is the default. This means that positions 100 and beyond will get set to position {{{99}}} whenever they appear in a queue. Set it to {{{0}}} for no maximum.
=== "Max items per page"
Trac automatically paginates reports that contain more tickets than the defined "Max items per page". Depending on your usage of queues, you may want to either set this value lower (or higher) globally for all reports in `trac.ini`:
{{{#!ini
[report]
items_per_page = 100
}}}
.. or bookmark the report queue with a {{{max=N}}} argument as desired. For example, seeing a long queue can be overwhelming or intimidating to some, so you may want to encourage the team to only look at the first 10 or 20 tickets using this argument. However, note that queue reordering only works on the first page of a report queue (it's disabled for subsequent pages). So if you need to reorder items on the second or third page, increase the "Max items per page" argument as needed.
=== Enhanced user experience
Depending on how you use work queues, several complementary plugins may enhance the user experience:
* DynamicVariablesPlugin - as described above, this converts dynamic variable textboxes into dropdown menus for those fields which are select fields. This can make navigating amongst queues much easier.
* DynamicFieldsPlugin - allows you to clear the {{{position}}} field when the milestone/queue field changes and hide the {{{myposition}}} field from general view. These are just small examples of how the plugin can enhance the user experience of this queues plugin.
* HideChangesPlugin - can hide ticket changes that do not have comments thus reducing the noise from queue reordering changes. See the next audit section for other options.
* QuietPlugin - dynamically disables email sending when using the AnnouncerPlugin, which helps reduce low-value email noise when using the {{{ticket}}} audit option, see below.
=== Auditing ticket reorderings
Changing the value of custom fields would normally cause a ticket change which would show up on the ticket. This may be just what you want to audit queue reorderings, however it can be quite noisy. So this plugin allows you to select from several different methods to audit queue reorderings in `trac.ini`:
{{{#!ini
[queues]
audit = log
}}}
There are three valid values for the {{{audit}}} option:
* {{{ticket}}} - changes get written normally to tickets
* {{{log}}} (default) - changes get written to log (if/as enabled in the {{{[logging]}}} section)
* {{{none}}} - no auditing at all
Please note that the default audit option is {{{log}}}. It is recommended that you use and configure the HideChangesPlugin to hide commentless changes if you opt for the {{{ticket}}} auditing method. Why would anyone use the {{{none}}} option? You may want queue reorderings to be as lightweight as possible to encourage its use. Having no record of changes is the lightest weight option. The {{{ticket}}} option is the heaviest weight which may discourage its use and also may generate many emails depending on the notification system you're using (see QuietPlugin as one means to prevent these emails while using {{{ticket}}} audit mode). The {{{log}}} option is a middle-ground of the three.
== Recent Changes
[[ChangeLog(queuesplugin, 3)]]
== Author/Contributors
'''Author:''' [wiki:robguttman] [[BR]]
'''Maintainer:''' [[Maintainer]] [[BR]]
'''Contributors:'''