wiki:QueuesPlugin

Version 9 (modified by robguttman, 4 years ago) (diff)

--

Manages named queues via drag-and-drop

Description

This plugin converts one or more reports into ticket 'queues'. A ticket queue allows you to drag-and-drop tickets into your desired order (similar to the Netflix Queue). Ticket positions in a queue get maintained in a custom field of your choosing.

The motivation for this plugin is for when you want to organize a work load in the order you intend to tackle it - i.e., as a work queue. Queues can be defined by milestone or any field(s). See the examples below for more details.

Configuration

  1. Install the plugin (after downloading and unzipping):
    cd queuesplugin/0.12
    sudo python setup.py bdist_egg
    sudo cp dist/TracQueues*.egg /your/trac/location/plugins/
    

See TracPlugins for more installation details and options. You'll likely need to restart Trac's web server after installation.

  1. Enable the plugin:
    [components]
    queues.* = enabled
    

You can alternatively use the Trac Web Admin GUI to enable any or all rules.

  1. Create a custom field to contain the position information - example trac.ini config:
    [ticket-custom]
    position = text
    
  1. 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)
  1. Tell the queues plugin which reports to convert to queues - example trac.ini config:
    [queues]
    reports = 9,10
    

See the examples below for more detailed configuration examples, options and capabilities.

Bugs/Feature Requests

Existing bugs and feature requests for QueuesPlugin are here.

If you have any issues, create a new ticket.

Download

Download the zipped source from here.

Source

You can check out QueuesPlugin from here using Subversion, or browse the source with Trac.

Examples

This plugin is built from several simple parts many of which are built into Trac (e.g., reports, dynamic variables). This approach takes advantage of what Trac already offers while still providing a great deal of flexibility in how you configure the queues. However, this flexibility is traded off against ease-of-use. So consider this a warning that 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 above, you can create a new report like this:

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 INTEGER) 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 9, then you would need to add it to the [queues] section of the {trac.ini file:

[queues]
reports = 9

You may need to restart your Trac web server afterwards. Here's a screenshot of the result with a few sample tickets:

To reorder the tickets, simply drag and drop them to their desired location 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 report dynamic variable to set the milestone:

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 INTEGER) ASC,
         t.changetime DESC

If this was created as report 10, update the trac.ini file as so (and restart your web server if needed):

[queues]
reports = 9,10

Here's the screenshot of the report:

In this example, I'm using the optional DynamicVariablesPlugin 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:

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 INTEGER) ASC,
         t.changetime DESC

In addition to the updating trac.ini with the new report number, you now also need to describe what operation the plugin should take for each group as follows:

[queues]
reports = 9,10,11
group.triage = clear

The group.triage = clear tells the plugin that the Triage group shouldn't reorder positions (the default operation). The name Triage is just an example - you can use any name as long as you make the config match the name used in the SQL statement. Here's the screenshot of the report:

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 moving it from the milestone1 group to anywhere in the Triage group (hence the full meaning the the clear operation described above). If you don't want to see the tickets The full list of operation directives are:

  • reorder (the default)
  • clear
  • ignore

There should only be one reorder group but 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 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 contents.

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 projects and use a separate custom field to 'bucket' tickets into queues. For example:

[ticket-custom]
position = text
queue = select
queue.options = |Queues 1|Queue 2|Queue 3

You can simply re-write your SQL query to pivot on a QUEUE dynamic variable instead of (or perhaps in addition to) a MILESTONE dynamic variable. The important thing is that the position custom field should be used for one and only one queue.

Personal work queue

It should be clear now that you can create a queue for just about any SQL query 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 to 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 purpose. The answer? Create a second custom field to manage the personal work queue's position:

[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 in the team work queues and the myposition field in 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 p.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 supporting team and personal work queues simultaneously 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 creates report that shows Product Management's preferred ordering alongside their own ordering.

Hopefully it's clear that many variants of this use case are also possible.

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 so that they sort correctly in any report or custom query in which they appear. You set this up globally in trac.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.

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:

[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.

"Max items per page"

Trac automatically paginates reports longer 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:

[report]
items_per_page = 100

.. or bookmark reports setting max=N as desired. For example, seeing a long queue can be overwhelming or intimidating to some, so you may want to encourage them to only look at the first 10 or 20 using this param/argument. However, note that queue reordering only works on the first page (it's disabled for subsequent pages). So if you need to reorder items on the second or third pages, increase the "Max items per page" argument as needed.

Enhanced user experience

Depending on how you use work queues, several complementary plugins may be beneficial to you:

  • 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 queue changes, for example, and hide the myposition field from general view - as just examples of how it 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 next section for other options.

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 provides several different methods to audit queue reorderings that gets set in trac.ini as follows:

[queues]
audit = log

There are three valid values to the audit option:

  • ticket - normal ticket changes
  • log (default) - gets written to log file only (if enabled in logging sectipn)
  • 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.

Recent Changes

[14030] by rjollos on 2014-07-25 13:33:11
Changed license to 3-Clause BSD with permission of author. Refs #11832.
[13773] by rjollos on 2014-03-18 01:08:11
0.2.0dev: In Trac 1.0 and later, use jQuery UI that is bundled with Trac. Fixes #11192.

This also allows using a newer version of jQuery UI in Trac 1.0 and later, by setting the [trac] jquery_ui_location option to serve a file stored locally, or to serve it from a CDN.

[13772] by rjollos on 2014-03-18 01:08:08
0.2.0dev: Fixed URL.

Author/Contributors

Author: robguttman
Maintainer: robguttman
Contributors:

Attachments (3)

Download all attachments as: .zip