= The Trac Ticket Workflow System = [[TracGuideToc]] The Trac issue database provides a configurable workflow. == The Default Ticket Workflow == === Environments upgraded from 0.10 === When you run `trac-admin upgrade`, your `trac.ini` will be modified to include a `[ticket-workflow]` section. The workflow configured in this case is the original workflow, so that ticket actions will behave like they did in 0.10. Graphically, that looks like this: [[Image(source:trunk/trac/htdocs/original-workflow.png)]] There are some significant "warts" in this; such as accepting a ticket sets it to 'assigned' state, and assigning a ticket sets it to 'new' state. Perfectly obvious, right? So you will probably want to migrate to "basic" workflow; `contrib/workflow/migrate_original_to_basic.py` may be helpful. === Environments created with 0.11 === When a new environment is created, a default workflow is configured in your trac.ini. This workflow is the basic workflow (described in `basic-workflow.ini`), which is somewhat different from the workflow of the 0.10 releases. Graphically, it looks like this: [[Image(source:trunk/trac/htdocs/basic-workflow.png)]] == Additional Ticket Workflows == 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. == Basic Ticket Workflow Customization == Create a `[ticket-workflow]` section in `trac.ini`. Within this section, each entry is an action that may be taken on a ticket. For example, consider the `accept` action from `simple-workflow.ini`: {{{ accept = new,accepted -> accepted accept.permissions = TICKET_MODIFY accept.operations = set_owner_to_self }}} 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`). The `accept.permissions` line specifies what permissions the user must have to use this action. 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. The available operations are: - del_owner -- Clear the owner field. - set_owner -- Sets the owner to the selected or entered owner. - ''actionname''`.set_owner` may optionally be set to a comma delimited list or a single value. - set_owner_to_self -- Sets the owner to the logged in user. - del_resolution -- Clears the resolution field - set_resolution -- Sets the resolution to the selected value. - ''actionname''`.set_resolution` may optionally be set to a comma delimited list or a single value. - leave_status -- Displays "leave as " and makes no change to the ticket. '''Note:''' Specifying conflicting operations (such as `set_owner` and `del_owner`) has unspecified results. {{{ resolve_accepted = accepted -> closed resolve_accepted.name = resolve resolve_accepted.permissions = TICKET_MODIFY resolve_accepted.operations = set_resolution }}} 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`. For actions that should be available in all states, `*` may be used in place of the state. The obvious example is the `leave` action: {{{ leave = * -> * leave.operations = leave_status leave.default = 1 }}} 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. If not specified for an action, `.default` is 0. The value may be negative. 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. While creating or modifying a ticket workfow, `contrib/workflow/workflow_parser.py` may be useful. It can create `.dot` files that [http://www.graphviz.org GraphViz] understands to provide a visual description of the workflow. == Advanced Ticket Workflow Customization == 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. But if even that is not enough, you can disable the !ConfigurableTicketWorkflow component and create a plugin that completely replaces it.