| 3 | | = Manages ticket queues via drag-and-drop = |
| 4 | | |
| 5 | | == Description == |
| 6 | | |
| 7 | | 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. |
| 8 | | |
| 9 | | 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 (i.e.,segmented) by milestone or any field(s) (or no fields). See the [wiki:QueuesPlugin#Examples examples below] for more details. |
| 10 | | |
| 11 | | |
| 12 | | == Configuration == |
| | 3 | = Manages ticket queues via drag-and-drop |
| | 4 | |
| | 5 | == Description |
| | 6 | |
| | 7 | 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. |
| | 8 | |
| | 9 | 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. |
| | 10 | |
| | 11 | == Configuration |
| | 12 | |
| 65 | | == Examples == |
| 66 | | 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! |
| 67 | | |
| 68 | | === Team work queue for all tickets === |
| 69 | | 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: |
| | 66 | == Examples |
| | 67 | |
| | 68 | This plugin is built from many parts built into 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! |
| | 69 | |
| | 70 | === Team work queue for all tickets |
| | 71 | |
| | 72 | 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: |
| 84 | | 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!). |
| 85 | | |
| 86 | | 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: |
| | 87 | 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! |
| | 88 | |
| | 89 | 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: |
| 181 | | 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. |
| 182 | | |
| 183 | | === Personal work queue === |
| 184 | | It should be clear by now that you can create a queue for just about 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. |
| 185 | | |
| 186 | | === Team work queue ''and'' personal work queue === |
| 187 | | 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? Create a second custom field to manage the personal work queue's position: |
| | 189 | 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. |
| | 190 | |
| | 191 | === Personal work queue |
| | 192 | |
| | 193 | You can create a queue for just about 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. |
| | 194 | |
| | 195 | === Team work queue ''and'' personal work queue |
| | 196 | |
| | 197 | 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: |
| 196 | | 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. |
| 197 | | |
| 198 | | === Development work queue ''and'' Product Management work queue === |
| 199 | | 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. |
| 200 | | |
| 201 | | Hopefully it's clear that many variants of this use case are possible. |
| 202 | | |
| 203 | | |
| 204 | | == Tips / Options == |
| 205 | | === Position padding === |
| 206 | | 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}}}: |
| | 206 | 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. |
| | 207 | |
| | 208 | === Development work queue ''and'' Product Management work queue |
| | 209 | |
| | 210 | 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. |
| | 211 | |
| | 212 | == Tips / Options |
| | 213 | |
| | 214 | === Position padding |
| | 215 | |
| | 216 | 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`: |
| 212 | | 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. |
| 213 | | |
| 214 | | === Maximum position === |
| 215 | | 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: |
| | 222 | 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. |
| | 223 | |
| | 224 | === Maximum position |
| | 225 | |
| | 226 | 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: |
| 221 | | 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. |
| 222 | | |
| 223 | | === "Max items per page" === |
| 224 | | 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}}}: |
| | 232 | 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. |
| | 233 | |
| | 234 | === "Max items per page" |
| | 235 | |
| | 236 | 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`: |
| 230 | | .. 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. |
| 231 | | |
| 232 | | === Enhanced user experience === |
| | 242 | .. 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. |
| | 243 | |
| | 244 | === Enhanced user experience |
| | 245 | |
| 238 | | * QuietPlugin - dynamically disables email sending when using the AnnouncerPlugin which helps reduce low-value email noise when using the {{{ticket}}} audit option (see below). |
| 239 | | |
| 240 | | === Auditing ticket reorderings === |
| 241 | | 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}}}: |
| | 251 | * QuietPlugin - dynamically disables email sending when using the AnnouncerPlugin which helps reduce low-value email noise when using the {{{ticket}}} audit option, see below. |
| | 252 | |
| | 253 | === Auditing ticket reorderings |
| | 254 | |
| | 255 | 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`: |
