[[PageOutline]]
= Workflow Discussion =

The original proposal is at NewWorkflow. The [source:/sandbox/workflow workflow sandbox] is an attempt to implement an API for making the ticket system more generic.

== Tasks ==
=== Done ===
 * Add a `disabled` attribute to fields so that workflow hooks can disable fields but still leave them visible.
 * Add a `hidden` attribute for the same reason. I've actually already done this, simply by renaming the `skip` attribute to `hidden`. Did this to be more consistent with HTML.
 * Add a `fullrow` attribute which signifies that the form element will span both columns of the ticket property fieldset. eg. summary, type, description and reporter would all be `fullrow=1`. [2833]
 * Remove code specific to individual fields from ticket.cs/newticket.cs. The summary, type, description and reporter would be converted to use the the same generic code as the rest of the fields. [2833]
 * Remove large `if/elif` statement from ticket.cs/newticket.cs. Currently there is a large if/then/else style block which is used to display all fields other than the four described above. This could be removed and replaced with a call to form_control(). [2833]
 * In order to specify the order the generic field display code would use, the above changes would probably require the ticket.fields.* HDF branch to be changed to an array (currently it is a dict). This change would be in api.py (return fields in the correct display order) and the .cs files, possibly elsewhere. [2832].
 * If possible I would also like to factor out the ticket field display/edit code from both ticket.cs and newticket.cs into ticket_fields.cs, as the template code is basically functionally identical. [2833]
 * Need a clean way to differentiate between fields that should not be displayed in the summary and those that should not be displayed at all. eg. `summary` should be hidden in the ticket summary (as it is used for the title), and should only be editable by users with `TICKET_ADMIN` privileges. Perhaps the logic should be that if a field is `hidden` it is not displayed anywhere, unless it is also `editable`, in which case it is only displayed in the ticket properties. [2837]

=== TODO ===
 * Add an `.onchange` option for javascript field validation.
 * Add a `.title` option, or maybe `.tooltip`, though I think for the sake of consisteny it should be `.title`.
 * Add a `checkboxes` field type. This differs from the `checkbox` type in that it is a set of related checkboxes. It would store the data in the field value as `check1|check2|check4`. I'm not sure about this one, or how it would be presented in the query module, but I figured that people might find it useful. Similarly, a `multi_select` type could be useful.
 * Remove `ticket_custom_props()` macro? It does not appear to be referenced.
 * There are a number of locations in the ticket code where permissions are hard coded. As an example, the `TICKET_CREATE` permission is required to create a new ticket. Should this be overridable by `ITicketWorkflow` implementors?
 * 

== Basic Configurable Workflow ==
Basic workflow configuration is possible in TracIni through two new sections,
`ticket-status` and `ticket-actions`. This configurability is limited to defining
ticket actions and status states and their transitions with basic permission
enforcement.

=== Defining available actions for a status ===
Each key under the `ticket-status` section is a ticket status and the value associated with each key is the actions available.

{{{
[ticket-status]
assigned = leave resolve reassign
closed = leave reopen retest
new = leave resolve reassign accept
reopened = leave resolve reassign
resolved = leave reassign reopen verify
verified = leave reassign reopen retest close
}}}

=== Mapping actions to resulting statuses ===

The `ticket-actions` section defines what the ticket status will be for each action,
in addition to the permission required for that action.

{{{
[ticket-actions]
accept = assigned
close = closed
close.permission = TRAC_ADMIN
reassign = new
reopen = reopened
reopen.permission = TICKET_ADMIN
resolve = resolved
retest = resolved
retest.permission = TICKET_ADMIN
verify = verified
}}}

== Plugabble Workflow ==
For more complex ticket workflow requirements an extension point is available,
allowing full control of the ticket workflow process.

{{{
#!python
class ITicketWorkflow(Interface):
    """ This interface controls what actions can be performed on a ticket and
        also a list of the available ticket fields. """

    # Control ticket actions
    def get_ticket_actions(req, ticket):
        """ Return the actions that are available given the current state of
            ticket and the request object provided. """

    def get_ticket_action(req, ticket, action):
        """ Return a trac.ticket.field.Field object for ticket action. """

    def apply_ticket_action(req, ticket, action):
        """ Perform action on ticket. """

    # Control ticket fields
    def filter_ticket_fields(req, ticket, fields):
        """ Given a list of ticket.Field objects and a ticket, return the
            filtered list of fields. This method must enforce permission
            control on all fields. """

    def update_ticket_fields(req, ticket):
        """ Apply changes in req to ticket. By default this should simply be
            `ticket.populate(req.args)`. """
}}}

== Available Field Types and Options ==
Common options:
 * '''label''': Descriptive label.
 * '''value''': Default value.
 * '''order''': Sort order placement. (Determines relative placement in forms.)
 * '''hidden''': Field is not displayed. Useful for storing extra ticket attributes programmatically (false by default).
 * '''fullrow''': Field spans a full row when displayed in the ticket properties.
 * '''editable''': Field is editable (true by default if field is not hidden). If a field is hidden but editable, it will not display in the ticket summary but will be displayed and editable in the ticket properties.

Types and type-specific options:
 * '''text''': A simple (one line) text field.
   * size: Size of text field.
 * '''checkbox''': A boolean value check box.
   * value: Default value (0 or 1).
 * '''select''': Drop-down select box. Uses a list of values.
   * options: List of values, separated by '''|''' (vertical pipe).
   * value: Default value (Item #, starting at 0).
 * '''radio''': Radio buttons. Essentially the same as '''select'''.
   * options: List of values, separated by '''|''' (vertical pipe).
   * value: Default value (Item #, starting at 0).
 * '''textarea''': Multi-line text area.
   * cols: Width in columns.
   * rows: Height in lines.