[[PageOutline]] = Workflow Discussion = The original proposal is at NewWorkflow. The [source:/sandbox/workflow workflow sandbox] contains a refactored ticket API which aims to allow plugins control over most aspects of the ticketing system. WorkFlow has been re-started at the PyCon sprints. Not much there yet, but it's at [source:/sandbox/pycon/workflow]. == Development == === Current Version === Work on the workflow branch has recently restarted, on top of 0.11dev (''Genshi''). Refer to the [log:sandbox/pycon/workflow change log] and the [diff:trunk//sandbox/pycon/workflow differences from trunk] and the [diff:trunk@4834//sandbox/pycon/workflow changes on the branch]. Depending on how things are going, the branch may be integrated in [milestone: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. == [source:trunk/trac/ticket/web_ui.py Trunk Ticket Action Flowchart] == These two flowcharts represent the current trunk ticket creation and modification logic. === [source:trunk/trac/ticket/web_ui.py@latest#L77 New Ticket Flowchart] === [[Image(workflow-new.png)]] === [source:trunk/trac/ticket/web_ui.py@latest#L181 Modify Ticket Flowchart] === [[Image(workflow-edit.png)]] === 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)]] 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. == 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. {{{ [ticket-status] assigned = leave,resolve,reassign,leave closed = leave,reopen,retest,leave new = leave,resolve,reassign,accept,leave reopened = leave,resolve,reassign,leave resolved = leave,reassign,reopen,verify,leave verified = leave,reassign,reopen,retest,close,leave }}} === 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] leave = 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,leave accepted = resolve,reassign,leave assigned = resolve,reassign,leave reopened = resolve,reassign,leave closed = reopen,leave [ticket-actions] accept = assigned resolve = closed reassign = new reopen = reopened leave = }}} == Pluggable Workflow == See the [source:sandbox/workflow/trac/ticket/api.py 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.