Workflow Discussion

The original proposal is at NewWorkflow. The workflow sandbox contains a refactored ticket API which aims to allow plugins control over most aspects of the ticketing system.

Obviously the workflow branch does not exist. (Which is pitty when JTrac has it already implemented as is proposed here.) I also downloaded the dev branch and custom workflow is not implemented there either. So do not bother looking for it. / radek See [4457]

WorkFlow has been re-started at the PyCon sprints. Not much there yet, but it's at sandbox/pycon/workflow.

Development

Current Version

Work on the workflow branch has recently restarted, on top of 0.11dev (Genshi). Refer to the change log and the differences from mainline.

Depending on how things are going, the branch may be integrated in 0.11, otherwise it will be just in the next one.

Previous Version

See source:sandbox/workflow@3378 for the previous incarnation of the WorkFlow branch, based on 0.10dev (last sync with trunk was with r3377, i.e. June 2006).

API Requirements

Control of action transitions

• This interface should be stackable (useful eg. with a DeleteTicket plugin which adds a single 'delete' action, which can be used in conjunction with a full workflow replacement plugin).
• Plugins should register which actions they handle, and then handle them when requested to do so.
• Ensure that the user has sufficient permission to perform this action.

Control of ticket fields

• Manipulate custom/built-in fields via plugin architecture. eg. hiding existing fields, changing their attributes, etc. An example of this is the DuplicateField plugin which removes the "duplicate" status from the "resolve" action and adds a new action "resolve as xxx".
• Pluggable field types, eg. percentage bar, checkbox set, numeric input field, dollar field, etc.

Validation

• Validation of ticket date before being committed to the database.

Trunk Ticket Action Flowchart​

These two flowcharts represent the current trunk ticket creation and modification logic.

New Ticket Flowchart​

Modify Ticket Flowchart​

Proposed Unified Flowchart + Extension Points

This proposes a unification of the logic for both creating and modifying tickets. In addition it adds extension points where plugins can modify the behaviour of the ticketing system.

Taking the above requirements into consideration, I think the following extension points should cater for all (most?) aspects.

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]
• Add a .plaintext option which negates the default behaviour of WikiFormatting field labels and values (see #925, #1395 and #1791 for related information). [2849]
• Add a .title option, or maybe .tooltip, though I think for the sake of consisteny it should be .title. [2851]
• 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?
• It might be an idea to simply have a apply_ticket_changes() method instead of having apply_ticket_action() and update_ticket_fields().

TODO

• Remove ticket_custom_props() macro? It does not appear to be referenced.

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. We see no reason to remove 'leave' as an action because otherwise comments could not be made. 'leave' is assumed allowed, even if not specified.

[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

Default mappings

[ticket-status]
new=accept,resolve,reassign,accept
accepted=resolve,reassign
assigned=resolve,reassign
reopened=resolve,reassign
closed=reopen

[ticket-actions]
accept=assigned
resolve=closed
reassign=new
reopen=reopened

Pluggable Workflow

See the source for extension points.

Here is a brief summary of the current extension interfaces:

Interface	Description
ITicketChangeListener	Listen for changes in tickets.
ITicketAdjunctChangeListener	Listen for changes in adjunct types (component, status, etc.)
ITicketAdjunctContributor	Contribute values to adjunct types.
ITicketFieldProvider	Programmatically add fields to tickest.
ITicketFieldTypeProvider	Add new field types (built in types are text, select, checkbox, etc.)
ITicketManipulator	General manipulation of tickets, including validation.
ITicketActionController	Provide and control tickets actions.
ITicketSimilarityDetector	Allows plugins to replace the default duplicate detection.

Available Field Types and Options

Common options:

• name: Field name.
• label: Descriptive label.
• value: Default value.
• order: Sort order placement. (Determines relative placement in forms.)
• visible: Whether field is visible. Useful for storing extra ticket attributes programmatically (false by default).
• editable: Field is editable (true by default if field is visible). 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.
• fullrow: Field spans a full row when displayed in the ticket properties.
• plaintext: Field labels and values use WikiFormatting by default. To display plain text set this option to true.
• title: HTML title (tooltip) for this field.

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.