[[PageOutline]] = WorkFlow = '' '''Note:''' see also the TracWorkflow page which describes the Trac workflow features in Trac. The present page rather describes the proposal for workflow support in Trac. == Development == === Phase 1 === Phase 1 of the WorkFlow adds configurable workflow states to Trac. Thus you can have more ticket states, change what they are, and specify what happens when a ticket transitions from one state to another. WorkFlow is built on 0.11dev and can be found in trunk! It is integrated for [milestone:0.11]. === Phase 2 and beyond === Phase 2 and beyond will bring in more of the functionality developed on the original workflow branch, such as custom ticket fields and field types provided by plugins (see also FieldRefactoring). See source:sandbox/workflow@3378 for the original incarnation of the WorkFlow branch, based on 0.10dev (last sync with trunk was with r3377, i.e. June 2006). == Configurable Workflow == ''implemented in phase1'' Configurable workflow allows you to change the ticket states and state transitions. A common desire is to have a "testing" state where QA can get involved. The default WorkFlow implementation ([source:trunk/trac/ticket/default_workflow.py@5693#L111 ConfigurableTicketWorkflow]) allows you to configure that workflow from the trac.ini. There are several working [source:trunk/contrib/workflow configuration examples] available. (Along with a couple tools for working with workflow configurations.) There are also some pretty diagrams on WorkFlow/Examples. But you can do more than that with plugins. Plugins may augment the default WorkFlow, adding actions and side-effects to ticket state transitions. There are a few working [source:trunk/sample-plugins/workflow plugin examples] available. (They're simplistic, but should be useful nonetheless.) Plugins may also add actions that do not affect ticket state. If a drastically different WorkFlow is needed, !ConfigurableTicketWorkflow may be disabled and entirely replaced by a plugin. == Plugin Configurable Ticket Fields == ''unimplemented'' Plugins will be able to specify custom ticket fields without having to modify trac.ini. == Plugin Configurable Ticket Field Types == ''unimplemented'' Plugins will be able to provide new field types in addition to those provided in the core. So dates, progress bars, and the like can be added as new field types with their own rendering. This should also provide support for validating field input values. ---- = Old Workflow Discussion = == 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. == [source:trunk/trac/ticket/web_ui.py Trunk Ticket Action Flowchart] == These two flowcharts represent the current trunk ticket creation and modification logic. Left, the '''[source:trunk/trac/ticket/web_ui.py@latest#L77 New Ticket Flowchart]''' and right, the '''[source:trunk/trac/ticket/web_ui.py@latest#L181 Modify Ticket Flowchart]'''. [[Image(workflow-new.png, float=left)]] [[Image(workflow-edit.png, float=left)]] === 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. [[Image(workflow.png,width=90%)]] Taking the above [wiki:WorkFlow#APIRequirements 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. == Pluggable Workflow == See the source:sandbox/workflow/trac/ticket/api.py@3871 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 tickets.|| ||`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.