Changes between Version 21 and Version 22 of FlexibleAssignToPlugin


Ignore:
Timestamp:
Aug 20, 2015, 9:53:30 AM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes, rearranged paragraphs to maintain consistency

Legend:

Unmodified
Added
Removed
Modified

  • FlexibleAssignToPlugin

    v21 v22  
    55== Description
    66
    7 !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.
     7This plugin 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.
    88
    99Key features:
    10  * adds new Extension point, IValidOwnerProvider, for plugging in your own components
     10 * Adds new Extension point, IValidOwnerProvider, for plugging in your own components.
     11 * Provides !SimpleUser base class and helper methods (getlist, getbool) to streamline implementation of your IValidOwnerProvider component(s).
     12 * Data source agnostic: this plugin removes the need to build 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 * 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 have never logged in and set their preferences.
     14 * 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.
     15 * Processing can be selectively disabled for individual workflow states.
     16 * Example plugin implementation !SampleValidOwnerProvider.py is included.
    1117
    12  * provides !SimpleUser base class and helper methods (getlist, getbool) to streamline implementation of your IValidOwnerProvider component(s)
     18'''Note:''' The plugin by itself doesn't do anything. You have to write your own plugin/component that implements IValidOwnerProvider, see [#Configuration Create your IValidOwnerProvider component].
    1319
    14  * 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.
     20'''Note''': The 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''.
    1521
    16  * 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.
     22== Bugs/Feature Requests
    1723
    18  * 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.
     24Existing bugs and feature requests for FlexibleAssignToPlugin are [query:status!=closed&component=FlexibleAssignToPlugin&order=priority here].
    1925
    20  * !FlexibleAssignTo processing can be selectively disabled for individual workflow states
     26If you have any issues, create a
     27[/newticket?component=FlexibleAssignToPlugin new ticket].
    2128
    22  * Example plugin implementation included (!SampleValidOwnerProvider.py)
     29[[TicketQuery(component=FlexibleAssignToPlugin,group=type,format=progress)]]
     30
     31== Download and Source
     32
     33 * '''Source'''
     34   * latest/trunk rev: download the zipped source from [download:flexibleassigntoplugin here].
     35 * '''Binaries''': all zips include sample plugin !SampleValidOwnerProvider.py:
     36   * Trac 0.13+ on Python 2.7: [attachment:FlexibleAssignTo-0.8.13-py2.7.zip FlexibleAssignTo-0.8.13-py2.7]: recommended version due to modernized Trac DB API usage
     37   * Trac 0.11+ on Python 2.7: [attachment:FlexibleAssignTo-0.7.13-py2.7.zip FlexibleAssignTo-0.7.13-py2.7]
    2338
    2439== Installation
    … …  
    2843To install this plugin:
    2944
    30 {{{
     45{{{#!sh
    3146easy_install http://trac-hacks.org/svn/flexibleassigntoplugin/0.13/trunk
    3247}}}
    3348
    34 Activate the plugin either with WebAdmin or in `trac.ini`:
     49Activate the plugin either with WebAdmin or by editing your `trac.ini` as follows:
    3550
    36 {{{
    37 #!ini
     51{{{#!ini
    3852[components]
    3953flexibleassignto.* = enabled
    4054}}}
    4155
    42 '''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.
    43 
    44 === How do I use it?
     56== Configuration
    4557
    4658'''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.
     59    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.
    4860
    4961'''2. Create your IValidOwnerProvider component'''
    … …  
    5567            * 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. 
    5668         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:
    58 {{{
    59 #!ini
     69          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`:
     70{{{#!ini
    6071mystate = oldstate -> mystate
    6172mystate.name = my whoopass state
    … …  
    6576mystate.valid_user_groups = Development Managers, Admins
    6677}}}
     78
    6779          Then in your getUsers method your code would look something like this, to retrieve these values from this workflow state:
    6880{{{
    6981allowed_groups = getlist(next_action_obj, 'valid_user_groups')
    7082}}}
    71           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.
     83
     84          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.
    7285         d. the !SimpleUser class [[BR]]
    7386          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:
    … …  
    7790SimpleUser.option_display
    7891}}}
    79           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.
     92          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.
    8093
    8194'''3. Config options''' [[BR]]
    … …  
    87100     * `use_custom_get_known_users` [[BR]]
    88101       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, 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]]
    90        '''Note:''' Changes to this setting require a server restart to take effect.  [[BR]]
     102       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 auto-populates 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]]
     103       '''Note:''' Changes to this setting require a server restart to take effect. [[BR]]
    91104       '''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.
    92105
    93106Here is the section that should be added to your `trac.ini`:
    94 {{{
    95 #!ini
     107{{{#!ini
    96108[flexibleassignto]
    97109ensure_user_data = false
    … …  
    101113'''4. Enable/disable individual workflow states''' [[BR]]
    102114    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:
    103 {{{
     115{{{#!ini
    104116mystate.use_flexibleassignto = false
    105117}}}
    106118
    107 == Bugs/Feature Requests
    108 
    109 Existing bugs and feature requests for FlexibleAssignToPlugin are [query:status!=closed&component=FlexibleAssignToPlugin&order=priority here].
    110 
    111 If you have any issues, create a
    112 [/newticket?component=FlexibleAssignToPlugin&owner=gt4329b new ticket].
    113 
    114 [[TicketQuery(component=FlexibleAssignToPlugin,group=type,format=progress)]]
    115 
    116 '''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''.
    117 
    118 == Download and Source
    119 
    120  * '''Source'''
    121    * latest/trunk rev: download the zipped source from [download:flexibleassigntoplugin here].
    122  * '''Binaries''' ''(all zips include sample plugin !SampleValidOwnerProvider.py)''
    123    * Trac 0.13+ on Python 2.7: [attachment:FlexibleAssignTo-0.8.13-py2.7.zip FlexibleAssignTo-0.8.13-py2.7] ''(recommended version due to modernized Trac DB API usage)''
    124    * Trac 0.11+ on Python 2.7: [attachment:FlexibleAssignTo-0.7.13-py2.7.zip FlexibleAssignTo-0.7.13-py2.7]
    125 
    126119== Example
    127120
    128 See the 'How to install section' above for details. For an example of how to implement IValidOwnerProvider, see the included sample plugin !SampleValidOwnerProvider.py.
     121For an example of how to implement IValidOwnerProvider, see the included sample plugin !SampleValidOwnerProvider.py.
    129122
    130123== Recent Changes