Changes between Version 19 and Version 20 of FlexibleAssignToPlugin


Ignore:
Timestamp:
Mar 7, 2015, 5:24:25 PM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes, tagged with license

Legend:

Unmodified
Added
Removed
Modified

  • FlexibleAssignToPlugin

    v19 v20  
    11[[TOC]]
    2 = !FlexibleAssignTo =
     2= !FlexibleAssignTo
    33
    4 == What is it? ==
    5 !FlexibleAssignTo finally gives long-suffering Trac admins a way to
    6 easily customize the 'assign to' field on tickets.  It provides several
    7 base classes for you to override and implement your own methods for
    8 providing lists of valid users -- you can even customize valid users for
    9 each state in your workflow.
     4== Description
     5
     6!FlexibleAssignTo gives Trac admins a way to easily customize the 'assign to' field on tickets. It provides several base classes for you to override and implement your own methods for providing lists of valid users. You can even customize valid users for each state in your workflow.
    107
    118Key features:
    … …  
    1411 * provides !SimpleUser base class and helper methods (getlist, getbool) to streamline implementation of your IValidOwnerProvider component(s)
    1512
    16  * data-source agnostic -- !FlexibleAssignTo abstracts the nastiness of building a customized 'assign to' select box.  All your custom code has to do is decide what users are valid for a particular state and then return them.
     13 * data-source agnostic -- !FlexibleAssignTo abstracts the nastiness of building a customized 'assign to' select box. All your custom code has to do is decide what users are valid for a particular state and then return them.
    1714
    18  * optional 'ensure_user_data' capability so that users who appear as valid 'assign to' targets get their key data (username, fullname, email) stored in the Trac session_attribute table.  The motivation for this was so notification emails could be sent to these users even if they've never logged in and set their preferences.
     15 * optional 'ensure_user_data' capability so that users who appear as valid 'assign to' targets get their key data (username, fullname, email) stored in the Trac session_attribute table.  The motivation for this was so notification emails could be sent to these users, even if they've never logged in and set their preferences.
    1916
    20  * optional get_known_users() replacement that changes Trac's 'known users' concept such that users' name & email data is retrieved from the session_attribute table (designed to work in concert with the 'ensure_user_data' capability).
     17 * optional get_known_users() replacement that changes Trac's 'known users' concept such that users' name and email data is retrieved from the session_attribute table, designed to work in concert with the 'ensure_user_data' capability.
    2118
    2219 * !FlexibleAssignTo processing can be selectively disabled for individual workflow states
    … …  
    2421 * Example plugin implementation included (!SampleValidOwnerProvider.py)
    2522
    26 == Installation ==
     23== Installation
    2724
    28 === How do I install it? ===
     25This plugin requires '''Trac 0.11+''', and it was built and tested against [http://trac.edgewall.org/browser/trunk?rev=10668 0.13dev-r10668] on Python 2.7.1.
     26
     27To install this plugin:
    2928
    3029{{{
    … …  
    3231}}}
    3332
    34 Activate the plugin either with webadmin or in trac.ini:
     33Activate the plugin either with WebAdmin or in `trac.ini`:
     34
    3535{{{
     36#!ini
    3637[components]
    3738flexibleassignto.* = enabled
    3839}}}
    3940
    40 '''NOTE:''' the plugin ''by itself'' doesn't do anything -- you have to write your own plugin/component that implements IValidOwnerProvider (see 'Create your IValidOwnerProvider component' under 'How do I use it?' below).
     41'''Note:''' The plugin by itself doesn't do anything. You have to write your own plugin/component that implements IValidOwnerProvider, see 'Create your IValidOwnerProvider component' under 'How do I use it?' below.
    4142
    42 === Prerequisites ===
    43  * '''Trac 0.11+''' (Built and tested most recently against [http://trac.edgewall.org/browser/trunk?rev=10668 0.13dev-r10668] on Python 2.7.1)
     43=== How do I use it?
    4444
    45 === How do I use it? ===
    4645'''1. Try out the sample plugin''' [[BR]]
    47     Once you've installed the base !FlexibleAssignTo plugin, copy the !SampleValidOwnerProvider.py file from the install package into your Trac environment's plugin directory (alongside the !FlexibleAssignTo .egg).  Restart your server and note the new (bogus) entries in your 'assign to' dropdowns.
     46    Once you've installed the base !FlexibleAssignTo plugin, copy the !SampleValidOwnerProvider.py file from the install package into your Trac environment's plugin directory (alongside the !FlexibleAssignTo .egg). Restart your server and note the new (bogus) entries in your 'assign to' dropdowns.
    4847
    4948'''2. Create your IValidOwnerProvider component'''
    5049         a. Create a .py file in your Trac environment's plugins directory [[BR]]
    51           This module is where you'll write your own class that implements the IValidOwnerProvider Extension point provided by !FlexibleAssignTo.  This is where your custom logic goes for deciding what users should appear as valid 'assign to' targets for each state -- whether that logic involves querying a database, searching an LDAP directory, or getting some sort of data from your custom-built array of highly trained homing pigeons.  See the !SampleValidOwnerProvider.py module included with this plugin for a simple example on how it works. 
     50          This module is where you'll write your own class that implements the IValidOwnerProvider Extension point provided by !FlexibleAssignTo. This is where your custom logic goes for deciding what users should appear as valid 'assign to' targets for each state, whether that logic involves querying a database, searching an LDAP directory, or getting some sort of data from your custom-built array of highly trained homing pigeons.  See the !SampleValidOwnerProvider.py module included with this plugin for a simple example on how it works. 
    5251         b. Implement IValidOwnerProvider component requirements [[BR]]
    5352          This module must contain a class that:
    5453            * declares that it implements IValidOwnerProvider
    55             * provides a getUsers method that takes a 'next_action_obj' as it's sole param and returns a list of instances of !SimpleUser (or a subclass) representing valid owners of that next state.  Keep reading for details on the getUsers() method and the !SimpleUser class.  If this sounds confusing and/or you just want to jump in and get your hands dirty, go check out the source for !SampleValidOwnerProvider.py. 
     54            * provides a getUsers method that takes a 'next_action_obj' as it's sole param and returns a list of instances of !SimpleUser (or a subclass) representing valid owners of that next state.  Keep reading for details on the getUsers() method and the !SimpleUser class. If this sounds confusing and/or you just want to jump in and get your hands dirty, go check out the source for !SampleValidOwnerProvider.py. 
    5655         c. the getUsers() method [[BR]]
    57           The sole param to getUsers(), next_action_obj, represents a workflow state that is available from the current ticket state AND that implements the "set_owner" operation (if you really want to get into the nitty gritty, next_action_obj is identical to the objects in the !ConfigurableTicketWorkflow.actions list in trac/ticket/default_workflow.py).  next_action_obj is provided to getUsers for the sole purpose of providing a way to look up custom workflow state params.  For example, if you had a workflow state defined in your trac.ini like this:
     56          The sole param to getUsers(), next_action_obj, represents a workflow state that is available from the current ticket state AND that implements the "set_owner" operation (if you really want to get into the nitty gritty, next_action_obj is identical to the objects in the !ConfigurableTicketWorkflow.actions list in trac/ticket/default_workflow.py). next_action_obj is provided to getUsers for the sole purpose of providing a way to look up custom workflow state params. For example, if you had a workflow state defined in your `trac.ini` like this:
    5857{{{
     58#!ini
    5959mystate = oldstate -> mystate
    6060mystate.name = my whoopass state
    6161mystate.operations = set_owner
    6262mystate.permissions = TICKET_MODIFY
    63 ; .valid_user_groups is a param that you add -- it's not part of the
    64 ;    default Trac workflow syntax
     63; .valid_user_groups is a param that you add and is not part of the default Trac workflow syntax
    6564mystate.valid_user_groups = Development Managers, Admins
    6665}}}
    … …  
    6968allowed_groups = getlist(next_action_obj, 'valid_user_groups')
    7069}}}
    71           You could then use the 'allowed_groups' list to query a database (or do whatever else you need to do) to get back a list of user information -- in this case, (presumably) return the users who are members of either the "Admins" or "Development Managers" group.  Each user's info should be packed into an instance (or subclass) of !SimpleUser.  The final return from getUsers() should be a *unique* list of !SimpleUser instances (no checks for uniqueness are guaranteed to be performed on the list of returned users).  Again, see !SampleValidOwnerProvider.py for a hopefully straightforward example. Note that individual workflow states can be disabled; see item 4, "Enable/disable individual workflow states", below.
     70          You could then use the 'allowed_groups' list to query a database to get back a list of user information; in this case, return the users who are members of either the "Admins" or "Development Managers" group. Each user's info should be packed into an instance (or subclass) of !SimpleUser. The final return from getUsers() should be a *unique* list of !SimpleUser instances (no checks for uniqueness are guaranteed to be performed on the list of returned users). See !SampleValidOwnerProvider.py for an example. Note that individual workflow states can be disabled; see item 4, "Enable/disable individual workflow states", below.
    7271         d. the !SimpleUser class [[BR]]
    73           There are three fields in !SimpleUser that you *must* set.  Not having these set (e.g., left as their default, None) will lead to assert exceptions from !FlexibleAssignTo:
     72          There are three fields in !SimpleUser that you *must* set. Not having these set, eg left as their default None, will lead to assert exceptions from !FlexibleAssignTo:
    7473{{{
    7574SimpleUser.username
    … …  
    7776SimpleUser.option_display
    7877}}}
    79           There are standard get/set methods for these; see the !SimpleUser class for specific method prototypes.  '''NOTE:''' the format of username values *must* match the format of usernames for logged-in users -- if John Doe logs in with the username "jdoe", then a !SimpleUser instance representing John Doe should get its username attribute set to "jdoe". If you don't do this, !FlexibleAssignTo will not work correctly.
     78          There are standard get/set methods for these; see the !SimpleUser class for specific method prototypes. [[BR]]'''Note:''' the format of username values *must* match the format of usernames for logged-in users -- if John Doe logs in with the username "jdoe", then a !SimpleUser instance representing John Doe should get its username attribute set to "jdoe". If you don't do this, !FlexibleAssignTo will not work correctly.
    8079
    8180'''3. Config options''' [[BR]]
    82      (All of the following options should be specified in the {{{[flexibleassignto]}}} section of your trac.ini)
    83      * ensure_user_data [[BR]]
     81     The following options should be specified in the {{{[flexibleassignto]}}} section of your `trac.ini`.
     82     * `ensure_user_data` [[BR]]
    8483       Defaults to false. [[BR]]
    85        !FlexibleAssignTo also provides functionality to ensure that key user data (username, fullname, email) is added to the trac session_attribute table as said user data is retrieved for "assign to" use, so that ticket assign/modification emails will be sent to the assigned user's email address.  '''NOTE:''' this feature will not overwrite session_attribute data already present.
     84       !FlexibleAssignTo also provides functionality to ensure that key user data (username, fullname, email) is added to the trac session_attribute table as said user data is retrieved for "assign to" use, so that ticket assign/modification emails will be sent to the assigned user's email address. [[BR]]'''Note:''' this feature will not overwrite session_attribute data already present.
    8685
    87      * use_custom_get_known_users [[BR]]
     86     * `use_custom_get_known_users` [[BR]]
    8887       Defaults to false.  [[BR]]
    89        Overrides the default get_known_users capability provided by default Trac (trac.env) method of the same name: whereas the Trac default get_known_users returns info only for those users who have logged in, this method returns info for every user who has data in the session_attribute table and is flagged authenticated (e.g., session_attribute.authenticated = 1).  This functionality was designed to work in concert with the "ensure_user_data" feature, which autopopulates user email & name in the session_attribute table. Generates one tuple for every user, of the form (username, name, email), ordered alphanumerically by username.  [[BR]]
    90        '''NOTE:''' Changes to this setting ''require'' a server restart to take effect!  [[BR]]
    91        '''NOTE:''' It is recommended that you also enable the ensure_user_data option if you use this method -- otherwise the behavior will be superficially no different than the default Trac get_known_users functionality.
     88       Overrides the default get_known_users capability provided by default Trac (trac.env) method of the same name: whereas the Trac default get_known_users returns info only for those users who have logged in, this method returns info for every user who has data in the session_attribute table and is flagged authenticated, eg session_attribute.authenticated = 1. This functionality was designed to work in concert with the "ensure_user_data" feature, which autopopulates user email & name in the session_attribute table. Generates one tuple for every user, of the form (username, name, email), ordered alphanumerically by username.  [[BR]]
     89       '''Note:''' Changes to this setting require a server restart to take effect.  [[BR]]
     90       '''Note:''' You should also enable the `ensure_user_data` option if you use this method, otherwise the behavior will be superficially no different than the default Trac `get_known_users` functionality.
    9291
    93 For your cutting-and-pasting pleasure, here's the section that should be added to your trac.ini:
     92Here is the section that should be added to your `trac.ini`:
    9493{{{
     94#!ini
    9595[flexibleassignto]
    9696ensure_user_data = false
    … …  
    9999
    100100'''4. Enable/disable individual workflow states''' [[BR]]
    101     Finally, note that by default !FlexibleAssignTo operates on EVERY state in your workflow, replacing the "assign to" field for every state with a "set_owner" operation.  To disable !FlexibleAssignTo for particular states (without having to disable the entire plugin), add the following key to your workflow state:
     101    Finally, note that by default !FlexibleAssignTo operates on every state in your workflow, replacing the "assign to" field for every state with a "set_owner" operation. To disable !FlexibleAssignTo for particular states without having to disable the entire plugin, add the following key to your workflow state:
    102102{{{
    103103mystate.use_flexibleassignto = false
    104104}}}
    105105
    106 
    107 == Bugs/Feature Requests ==
     106== Bugs/Feature Requests
    108107
    109108Existing bugs and feature requests for FlexibleAssignToPlugin are [query:status!=closed&component=FlexibleAssignToPlugin&order=priority here].
    … …  
    112111[/newticket?component=FlexibleAssignToPlugin&owner=gt4329b new ticket].
    113112
    114 '''NOTE''': the !FlexibleAssignTo framework does not modify the fields on the "New Ticket" page - it only operates on the fields as rendered on existing tickets. This is a common misunderstanding, and has in fact been filed as a bug/feature request (#2634). Make sure to verify your install is working by installing the included !SampleValidOwnerProvider plugin and examining ''an existing ticket''.
     113[[TicketQuery(component=FlexibleAssignToPlugin,group=type,format=progress)]]
    115114
    116 == Download & Source ==
     115'''Note''': the !FlexibleAssignTo framework does not modify the fields on the "New Ticket" page - it only operates on the fields as rendered on existing tickets. This is a common misunderstanding, and has in fact been filed as a bug/feature request (#2634). Make sure to verify your install is working by installing the included !SampleValidOwnerProvider plugin and examining ''an existing ticket''.
     116
     117== Download and Source
    117118
    118119 * '''Source'''
    … …  
    122123   * Trac 0.11+ on Python 2.7: [attachment:FlexibleAssignTo-0.7.13-py2.7.zip FlexibleAssignTo-0.7.13-py2.7]
    123124
    124 == Example ==
     125== Example
    125126
    126 See the 'How to install section' above for details.  For an example of how to implement IValidOwnerProvider, see the included sample plugin !SampleValidOwnerProvider.py.
     127See the 'How to install section' above for details. For an example of how to implement IValidOwnerProvider, see the included sample plugin !SampleValidOwnerProvider.py.
    127128
    128 == Recent Changes ==
     129== Recent Changes
    129130
    130131[[ChangeLog(flexibleassigntoplugin, 3)]]
    131132
    132 == Author/Contributors ==
     133== Author/Contributors
    133134
    134135'''Author:''' [wiki:gt4329b rfmorris (aka gt4329b)] [[BR]]
     136'''Maintainer:''' [[Maintainer]] [[BR]]
    135137'''Contributors:''' osimons, chris