[[PageOutline(2-5,Contents,pullout)]] = Timing and Estimation Plugin User Manual [TimingAndEstimationPlugin Plugin description on TracHacks] | [https://trac-hacks.org/report/9?COMPONENT=TimingAndEstimationPlugin Open Tickets] | [https://trac-hacks.org/newticket?component=TimingAndEstimationPlugin New Ticket] | [https://trac-hacks.org/browser/timingandestimationplugin Web Browsable Source Code] == Abstract Design Goal The original design goal of this plugin was to use as much of the existing structure as possible and without adding extra structures that might make maintainability difficult. The largest downside to this is that there is no way to add more permissions to this plugin differentiated by feature. == Custom Ticket Fields In adhering to the design goal, rather than creating a new ticket interface, some custom fields and a small daemon to watch over them were created. === Fields * '''Hours to Add''' This field functions as a time tracker. When you add hours to it, those hours get added to the total hours field. The person who made the change is therefore credited with the hours spent on it. * '''Total Hours''' This field is the total number of hours that have been added to the project. This has been made non-editable by including Javascript which replaces the input box with a span containing its value. * Reports might not agree with each other if this is manually edited, which is possible if you disable Javascript. * '''Is this billable?''' An extra flag on tickets so that they can be marked as billable / not billable. * '''Estimated Hours''' A field that contains the estimated amount of work. === Future Fields * '''Ticket Rate''' The ability to attach a cost per hour or total amount to an individual ticket. == Billing / Management Page / Time Reports This page provides a small interface for querying the tickets and adding a bill date at the current time. This interface gives you links that match the interface to open any of the given reports, by providing it the correct set of input parameters. The direct url is '/Billing'. === No Permissions Branch The 'Management' button should be in the main title bar. It is possible that if you are viewing at a low resolution, it is pushed off the edge of the screen. Also if you are not logged in with `REPORT_VIEW` permissions, then it will not show that button. === Permissions Branch The 'Time Reports' button should be in the main title bar. The user sees this depending on whether (s)he has the `TIME_VIEW` permission. Note that Email notifications are currently unaffected, see #10318. === Set Bill Date This button will add today's date as a billing date. This is to make it easier to select the last time you billed. === Configuration ==== TimingAndEstimation {{{#!ini [timingandestimation] # change what permission is required to view the billing/management screen # default is REPORT_VIEW billing_permission = TRAC_ADMIN }}} == Reports === Report Types We provide a few different reports for querying different types of data: * '''Billing Reports''' Currently the billing reports are the only time based reports, and are therefore useful for getting an estimate what tickets had times (and totals), and which developers spent their time where. * Ticket Work Summary * Milestone Work Summary * Developer Work Summary * '''Ticket/Hour Reports''' These reports are useful for reviewing estimates on a large scale or getting an idea of the project at large. These reports currently ignore the time. * Ticket Hours * Ticket Hours with Description * Ticket Hours Grouped By Component * Ticket Hours Grouped By Component with Description * Ticket Hours Grouped By Milestone * Ticket Hours Grouped By Milestone with Description === Adding More Reports To add reports to the Management screen sections, you must run the following SQL against your Trac database: {{{#!sql INSERT INTO custom_report (id, uuid, maingroup, subgroup, version, ordering) VALUES ( (@reportID , @uuid, 'Timing and Estimation Plugin', 'Billing Reports', 1, 0), (@reportID , @uuid, 'Timing and Estimation Plugin', 'Ticket/Hour Reports', 1, 0) ); }}} Remember to fill in the @reportID of the report you want to insert, and to select the insert statement for the section of your choice. '''Note''': @uuid is a globally unique identifier created via a tool such as {{{uuidgen}}} on Linux or [http://www.famkruithof.net/uuid/uuidgen online tools]. It is used in this plugin to provide programmatic reference to specific reports such that they can be upgraded successfully on future revisions of the plugin. === Removing a Report To remove reports from the Management page, run the following query. * To remove for this version of the plugin (will be overwritten in future plugin upgrades): {{{#!sql UPDATE custom_report SET maingroup = 'x' || maingroup WHERE report = @reportID; }}} * To remove permanently (won't be overwritten in future plugin upgrades): {{{#!sql UPDATE custom_report SET version = 9999, maingroup = 'x' || maingroup WHERE report = @reportID; }}} Remember to fill in the @reportID of the report you want to modify. '''Notes''': * The 'x' part is not important, you just need to make the column read something other than 'Timing and Estimation Plugin'. * The reports can only be called from the Management Page. They will not work from the Trac View Tickets page. This is because of the custom variables that need values. == Permissions Branch A branch of this plugin was sponsored by [http://www.obsidiansoft.com/ Obsidian Software], so that it would support per field permissions. Note that Email notifications are currently unaffected, see #10318. This is accomplished with Genshi 5 stream filters in Trac 0.11. This code draws from the [https://trac-hacks.org/wiki/BlackMagicTicketTweaksPlugin BlackMagicTicketTweaksPlugin]. === Configuration There is a new `trac.ini` configuration section which is filled in by default as follows: {{{#!ini [field settings] # per field permissions # a list of all the fields to apply permissions to fields = billable, totalhours, hours, estimatedhours, internal # a bunch of: # field.permission = PERMISSION:consequence # # If PERMISSION=ALWAYS, then the consequence always occurs # eg: billable.permission = ALWAYS:hide # will always result in billable being hidden, irrespective of user permissions # # where consequence is one of: hide, remove, disable # hide - replaces with hidden input # remove - removes element # disable - removes input in favor of text billable.permission = TIME_VIEW:hide, TIME_RECORD:disable totalhours.permission = TIME_VIEW:remove, TIME_RECORD:disable hours.permission = TIME_RECORD:remove estimatedhours.permission = TIME_RECORD:disable internal.permission = TIME_RECORD:hide }}} It also adds an "Internal" checkbox which allows you to set a ticket as internal. For this policy to work correctly you need to add a line to the `trac` section of the `trac.ini` configuration file telling it which permission policies to use. The setup will attempt to put this line of configuration in place. The permission that looks at currently is `TIME_ADMIN`. To change that group set the `internalgroup` of the ticket section in the `trac.ini` file as follows: {{{#!ini [ticket] internalgroup = TRAC_ADMIN #or whatever group / permission you want [trac] permission_policies = InternalTicketsPolicy, DefaultPermissionPolicy, LegacyAttachmentPolicy }}} == Future Improvements * [https://trac-hacks.org/report/9?COMPONENT=TimingAndEstimationPlugin See tickets] at the [https://trac-hacks.org/wiki/TimingAndEstimationPlugin project Trac] == Sponsors [http://www.obsidiansoft.com/ Obsidian Software] {{{#!html
Obsidian software financed the development of the permissions branch. }}} [http://www.aquafold.com/ Aquafold] {{{#!html
Aquafold has provided a license to their excellent Aqua Data Studio application to help further development. }}}