= Trac and !SlimTimer integration =
[[PageOutline(2-5,Contents,pullout)]]

== Description ==

Provides some rudimentary support for:

 * creating [http://www.slimtimer.com SlimTimer] tasks from trac tickets;
 * setting hours in trac tickets (such as the 'totalhours' field of the TimingAndEstimationPlugin) based on !SlimTimer data; and
 * backing up !SlimTimer data to an external database.

The plugin allows a group of users to be defined by trac username and !SlimTimer login providing some basic group sharing of !SlimTimer tasks.

There are two parts to its operation: synchronisation and reporting.

=== Synchronisation ===

When a trac ticket enters the '''assigned''' state (i.e. it is ''accepted'' by someone), !TracSlimTimer creates a corresponding task in !SlimTimer. The ID of the !SlimTimer task is then recorded with the trac ticket (as a custom field).

The operation is shown below.
{{{
#!html
<center><img src="http://trac-hacks.org/svn/tracslimtimerplugin/docs/images/sync.png" /></center>
}}}

More generally, synchronisation occurs when:

 * a ticket is assigned. Note that it is not just sufficient to put a name in the "assigned to" field. The assigned person also needs to '''accept''' the ticket before it enters the assigned state. Until then the ticket is in the "new" state.
 * a ticket is closed.
 * a ticket is reopened.
 * a ticket is deleted.
 * any of the following fields is changed while the ticket is in the ''assigned'' or ''reopened'' state:
   * summary,
   * keywords,
   * milestone,
   * CC

The following synchronisation is performed:

 * When tickets are assigned or reopened a corresponding task in !SlimTimer is created if it does not already exist.
 * When a !SlimTimer task is created the !SlimTimer ID is stored in a custom field of the trac ticket.
 * When a ticket is closed in trac the corresponding task is marked as complete in !SlimTimer.
 * When a ticket is reopened in trac the corresponding task is marked as incomplete in !SlimTimer.
 * When a ticket is deleted in trac the corresponding task is marked as complete in !SlimTimer.
 * The name of the !SlimTimer task is composed of the trac ticket ID followed by the trac summary, e.g. " #40: Plan & co-ordinate 0.4 release"
 * The tags of the !SlimTimer task will include the trac milestone and keywords.
 * The coworkers of the !SlimTimer task will include all the users configured in the !TracSlimTimer module who have the "default CC/coworker" property selected and any users listed in trac's CC field.
 * The total hours recorded in !SlimTimer are stored in the trac ticket using the custom field 'totalhours' (for compatibility with the TimingAndEstimationPlugin)

=== Reporting ===

The second function of !TracSlimTimer is to collect all the !SlimTimer data for the configured users and record it in a separate data store. This provides a backup of the !SlimTimer data and allows reporting for a whole group of users.

The operation is shown below.
{{{
#!html
<center><img src="http://trac-hacks.org/svn/tracslimtimerplugin/trunk/docs/images/dump.png" /></center>
}}}

Currently only MySQL is supported as a database. From MySQL the user can perform their own reporting (e.g. using Excel via MyODBC or some web-reporting tool.)

Not all users will require this function and it is possible to operate !TracSlimTimer without a database.

'''More information about the reporting module can be found on the [TracSlimTimerPluginReportingModule reporting module page].'''

'''If you're looking for screenshots, see [#screenshots Examples] below.'''

== Supported Versions ==

This plugin will currently only work with trac 0.10. This is because:

 * ITicketChangeListener is used so it will not work with 0.9
 * Only !ClearSilver templates are provided so it will not work with Genshi.

Some of the code has been written so that it might just work with 0.11 and Genshi if the templates were provided. For example, there is code in [source:tracslimtimerplugin/0.10/tracslimtimer/admin_ui.py admin_ui.py] to use the alternate IAdminPanelProvider vs IAdminPageProvider templates but it is entirely untested. (This code is courtesy of http://svn.edgewall.com/repos/trac/sandbox/spam-filter/tracspamfilter/admin.py)

== Installation ==

See the separate [TracSlimTimerPluginInstallation installation page].

== Developers Guide ==

A brief overview of the code is available in the [TracSlimTimerPluginDevelopersGuide developers guide].

== Bugs/Feature Requests == 

Existing bugs and feature requests for TracSlimTimerPlugin are 
[report:9?COMPONENT=TracSlimTimerPlugin here].

If you have any issues, create a 
[http://trac-hacks.org/newticket?component=TracSlimTimerPlugin&owner=tst new ticket].

== Download ==

Download the zipped source from [download:tracslimtimerplugin here].

== Source ==

You can check out TracSlimTimerPlugin from [http://trac-hacks.org/svn/tracslimtimerplugin here] using Subversion, or [source:tracslimtimerplugin browse the source] with Trac.

{{{
#!html
<a name="screenshots"/>
}}}
== Examples (screenshots) ==

'''Basic settings'''

{{{
#!html
<center><img src="http://trac-hacks.org/svn/tracslimtimerplugin/trunk/docs/images/basic-full.png" /></center>
}}}

'''Reporting options'''

{{{
#!html
<center><img src="http://trac-hacks.org/svn/tracslimtimerplugin/trunk/docs/images/reporting-full.png" /></center>
}}}

'''User configuration'''

{{{
#!html
<center><img src="http://trac-hacks.org/svn/tracslimtimerplugin/trunk/docs/images/users-full.png" /></center>
}}}

== External Resources ==

General:

 * [http://www.slimtimer.com SlimTimer]

== Recent Changes ==

[[ChangeLog(tracslimtimerplugin, 3)]]

== Author/Contributors ==

'''Author:''' [wiki:tst] [[BR]]
'''Maintainer:''' ''none'' [[BR]]
'''Contributors:'''