Context Navigation

What It Is

NotifyPlugin is a Trac plugin that "notifies" (calls) a PHP (or any other web-based page) script when a ticket is created, modified or deleted. It also passes along various bits of information about the ticket that was altered.

Useful Info

The data can be sent to any web-based that can be accessed from the server on which Trac lives. It was intended for it to call a PHP script, but it can call anything; CGI, Python, Perl, ASP *spit*, etc.

It sends ten bits of information with it:

action:
- Explains what happened to the ticket to trigger the notification. EG: whether a new ticket was created, a ticket was modified, or one was deleted.
- Values: created, changed and deleted.

project:
- The human-readable name of the project/instance. Since this plugin can be installed on many different instances of Trac, it is very useful to know from which instance the ticket came. It will be something like Virtual Planner.

trac_id:
- ID/number of the ticket that triggered the notification. This will be an integer.

owner:
- The current owner of the ticket. It will probably start off as something like somebody or anonymous. When someone accepts a ticket, it will then contain their username. EG: sam.

title:
- Title of the ticket. EG: Uploads Do Not Work. Also called a summary in Trac.

status:
- Status of the ticket. It defaults to new, but will change once the ticket is modified.
- Values: new, closed (probably more - but I don't know).

desc:
- Full description of the ticket.

ticket_url:
- Full web-accessible path to the ticket within Trac. Something like http://trac.palepurple.co.uk/projects/virtual-planner/ticket/1.

estimated_hours:
- How long the ticket is estimated to take (in hours). Float: "1.5" == one and a half hours.

total_hours:
- Number of hours the ticket has taken so far. Float: "1.5" == one and a half hours.

The data is sent via POST, not GET.

Technical Server Stuff

Building

Trac accepts plugins in the form of Python Eggs. These are just glorified zip files with some config information and are easy to create. One important note is that they must be compiled for the version of Python on which the target Trac system is running. That is; if you want the plugin to work on a Trac instance which is running on-top of Python 2.5, the egg must be built with Python 2.5. The same goes for version 2.4.

At the time of writing, the Pale Purple Trac systems run on Python 2.4. So make sure the version of Python you're running is v2.4.x (any version of Python 2.4 will do).

You will need something called Setup Tools. If you don't have this, fret not - if you're running Ubuntu. Simply run:

sudo apt-get install python-setuptools

Next, change to the directory where the NotifyPlugin (fetch from http://virtual-planner.palepurple.co.uk/svn/trunk/trac-python-plugin/ using svn) code lives. You should see something like this:

sam@mort:~/src/notify-plugin$ ls -1
build.sh
notify
setup.py
TracNotify.egg-info

System wide installation

If you wish to install the Plugin system wide, run:

sh build.sh

Then edit (or create) /usr/share/trac/conf/trac.ini, it should look like (or at least contain):

[components]
notify.* = enabled

You may need to restart Apache, for Trac to discover this plugin.

The end ?

That's it. Enjoy the plugin. Live long and prosper. You may want to check it works, though. Go to the Trac instance of the project in which you installed the plugin and make sure you see what you normally see. If you do; try creating a new ticket (it can be anything you want and can be deleted when done). You should see what you normally see.

If you see the red box along the top of the screen, saying something along the lines of "Internal Trac Error", contact the last person who changed the code (or Sam). Unless you want to fix it yourself...

You may also wish to monitor the web server logs for the target of the plugin's action - to see if a request has been sent to the remote server.

Hacking

Changing The Target Page

You'll most likely be hacking the plugin to change the script it calls when run. This is very simple and just requires modifying one line - although you will need to rebuild the egg as described above (but you need to do that for all modifications).

Go into the NotifyPlugin code directory and find the file notify/notify.py. Look down to line 19; the line beginning with self.path = , followed by an URL. Change that URL to whatever you need to to be, save the script, then rebuild the egg as described above.

Changing Authentication Details

The target page should be protected by Apache's simple htpasswd authentication system, so the plugin needs to be given a user name and password which it can use to gain access to the target.

Open the source file (notify/notify.py) and find the first two lines of the open_page function - you'll see two strings defined: username (line 46) and password (line 47). Change the values of these strings to contain the correct data, then save the script and rebuild the egg (see above).

Changing Other Stuff

All of the plugin's functionality is in a single file: notify/notify.py. It's a small file with very little code, so the plugin is simple.

Adding new files or GUI stuff is beyond the scope of this page, so you'll have to look into that yourself.