Re: FlexibleAssignTo plugin
Morris
FlexibleAssignTo - a Trac Plugin
**********************************
What is it?
===========
FlexibleAssignTo finally gives long-suffering 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 forproviding lists of valid users -- you can even based valid
users on each state in your workflow.
Key features:
* adds new Extension point, IValidOwnerProvider, for plugging in your
own components
* provides SimpleUser base class and helper methods (getlist, getbool)
to streamline implmentation of your IValidOwnerProvider component(s)
* 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.
* 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.
* FlexibleAssignTo processing can be selectively disabled for
individual workflow states
* Example implementation included (SampleValidOwnerProvider.py)
How do I install it?
====================
Just like any other Trac (0.11) plugin -- see step [1] in the "How do
I use it?" section below for details. Note that by itself,this plugin
doesn't do anything
Prerequisites
=============
- Trac 0.11+ (built and tested against 0.11dev trunk r6047)
- Python 2.5+
How do I use it?
================
[1] Install FlexibleAssignTo plugin
To get started, install the base FlexibleAssignTo plugin. Build
the .egg file following the plugin packaging instructions here:
http://projects.edgewall.com/trac/wiki/TracDev/PluginDevelopment
If you already have setuptools (v0.6+) installed, your command is
python setup.py bdist_egg
Once you've built the .egg, copy it into your Trac environment's
plugin directory. You still need to activate the plugin -- in
trac.ini:
[components]
flexibleassignto.* = enabled
** NOTE: the plugin by itself doesn't do anything -- you have to write
your own plugin/component that implements IValidOwnerProvider.
[1a] Try out the demo
Once you've install the base FlexibleAssignTo plugin, copy the
SampleValidOwnerProvider.py file from the install package into your
Tracenvironment's plugin directory (alongside the
FlexibleAssignTo .egg).Restart your server and note the new entries in
your "assign to" dropdowns.
[2] Create your IValidOwnerProvider component
Create a .py file in your Trac environment's plugins directory --this
module is where you'll write your own class that implements the
IValidOwnerProvider Extension point provided by FlexibleAssignTo.
This classis where your custom logic goes for deciding what users
should appear as valid"assign to" targets for each state. See the
SampleValidOwnerProvider.py module included with this plugin for a
simple example on how it works.
[2a] IValidOwnerProvider component requirements
If you just want to give it a go, then all you really need to know is
the following:
- The class should declare that it implements IValidOwnerProvider
- The class should provide a getUsers method that takes a
"next_action_obj" as it's sole param and returns a list of instancesof
SimpleUser (or a subclass) representing valid owners of that next
state. If this sound confusing, just look at the getUsers()method in
SampleValidOwnerProvider.py
[2b] the getUsers() method
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 an entry 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 like this:
mystate = oldstate -> mystate
mystate.name = my whoopass state
mystate.operations = set_owner
mystate.permissions = TICKET_MODIFY
mystate.valid_user_groups = Development Managers, Admins
Then in getUsers your code would look like:
allowed_groups = getlist(next_action_obj, 'valid_user_groups')
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 of SimpleUser (or a
subclass). The final return from getUsers() should be a *unique* list
of SimpleUser instances (no checks for uniqueness are performed on the
list of returned users). Again, seeSampleValidOwnerProvider.py for a
simple example.
[2c] the SimpleUser class
** NOTE: 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:
SimpleUser.username
SimpleUser.option_value
SimpleUser.option_display
There are standard get/set methods for these; see the SimpleUser class
for protos. Note that the format of username values should match the
format of usernames for logged-in users -- so if John Doe logs in with
the username "jdoe", then a SimpleUser instance representing John Doe
should be created with a username "jdoe".
[3] ensure_user_data functionality
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. This feature, disabled by default, can be enabled by
adding the following lines to your trac.ini:
[flexibleassignto]
ensure_user_data = true
** NOTE: this feature will not overwrite any data already present.
[4] Enable/disable for individual workflow states
Finally, note that by default FlexibleAssignTo operates on EVERY
statein your workflow, replacing the "assign to" field for every
statewith a "set_owner" operation. To disable FlexibleAssignTo for
particularstates (without having to disable the entire plugin), add
the followingkey to your workflow state:
mystate.use_flexibleassignto = false
Morris
trac-hacks.org is back up I'll create a proper page for it.