| 1 | = The Trac Ticket Workflow System = |
| 2 | [[TracGuideToc]] |
| 3 | |
| 4 | The Trac issue database provides a configurable workflow. |
| 5 | |
| 6 | == The Default Ticket Workflow == |
| 7 | If you do not configure a custom workflow, the default workflow is described in `contrib/workflow/original-workflow.ini` '''FIXME'''. |
| 8 | |
| 9 | [[Image(htdocs:../common/original-workflow.png)]] |
| 10 | |
| 11 | You will probably want to look at the additional ticket workflows available, and `contrib/workflow/simple.ini` in particular. |
| 12 | |
| 13 | == Additional Ticket Workflows == |
| 14 | |
| 15 | There are several example workflows provided in the Trac source tree; look in `contrib/workflow` for `.ini` config sections. One of those may be a good match for what you want. |
| 16 | |
| 17 | == Basic Ticket Workflow Customization == |
| 18 | |
| 19 | Create a `[ticket-workflow]` section in `trac.ini`. |
| 20 | Within this section, each entry is an action that may be taken on a ticket. |
| 21 | For example, consider the `accept` action from `simple-workflow.ini`: |
| 22 | {{{ |
| 23 | accept = new,accepted -> accepted |
| 24 | accept.permissions = TICKET_MODIFY |
| 25 | accept.operations = set_owner_to_self |
| 26 | }}} |
| 27 | The first line in this example defines the `accept` action, along with the states the action is valid in (`new` and `accepted`), and the new state of the ticket when the action is taken (`accepted`). |
| 28 | The `accept.permissions` line specifies what permissions the user must have to use this action. |
| 29 | The `accept.operations` line specifies changes that will be made to the ticket in addition to the status change when this action is taken. In this case, when a user clicks on `accept`, the ticket owner field is updated to the logged in user. Multiple operations may be specified in a comma separated list. |
| 30 | |
| 31 | The available operations are: |
| 32 | - del_owner -- Clear the owner field. |
| 33 | - set_owner -- Sets the owner to the selected or entered owner. |
| 34 | - ''actionname''`.set_owner` may optionally be set to a comma delimited list or a single value. |
| 35 | - set_owner_to_self -- Sets the owner to the logged in user. |
| 36 | - del_resolution -- Clears the resolution field |
| 37 | - set_resolution -- Sets the resolution to the selected value. |
| 38 | - ''actionname''`.set_resolution` may optionally be set to a comma delimited list or a single value. |
| 39 | - leave_status -- Displays "leave as <current status>" and makes no change to the ticket. |
| 40 | '''Note:''' Specifying conflicting operations (such as `set_owner` and `del_owner`) has unspecified results. |
| 41 | |
| 42 | {{{ |
| 43 | resolve_accepted = accepted -> closed |
| 44 | resolve_accepted.name = resolve |
| 45 | resolve_accepted.permissions = TICKET_MODIFY |
| 46 | resolve_accepted.operations = set_resolution |
| 47 | }}} |
| 48 | |
| 49 | In this example, we see the `.name` attribute used. The action here is `resolve_accepted`, but it will be presented to the user as `resolve`. |
| 50 | |
| 51 | For actions that should be available in all states, `*` may be used in place of the state. The obvious example is the `leave` action: |
| 52 | {{{ |
| 53 | leave = * -> * |
| 54 | leave.operations = leave_status |
| 55 | leave.default = 1 |
| 56 | }}} |
| 57 | This also shows the use of the `.default` attribute. This value is expected to be an integer, and the order in which the actions are displayed is determined by this value. The action with the highest `.default` value is listed first, and is selected by default. The rest of the actions are listed in order of decreasing `.default` values. |
| 58 | If not specified for an action, `.default` is 0. The value may be negative. |
| 59 | |
| 60 | There are a couple of hard-coded constraints to the workflow. In particular, tickets are created with status `new`, and tickets are expected to have a `closed` state. Further, the default reports/queries treat any state other than `closed` as an open state. |
| 61 | |
| 62 | While creating or modifying a ticket workfow, `contrib/workflow/workflow_parser.py` may be useful. It can create `.dot` files that GraphViz understands to provide a visual description of the workflow. |
| 63 | |
| 64 | == Advanced Ticket Workflow Customization == |
| 65 | |
| 66 | If the customization above is not extensive enough for your needs, you can extend the workflow using plugins. These plugins can provide additional operations for the workflow (like code_review), or implement side-effects for an action (such as triggering a build). Look at `sample-plugins/workflow` for a few simple examples to get started. |
| 67 | |
| 68 | But if even that is not enough, you can disable DefaultTicketActionController, and create a plugin that completely replaces it. |