User Tools

Site Tools


extensions:itop-time-tracking

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

extensions:itop-time-tracking [2021/04/19 15:25]
vdumas [Revision history]
extensions:itop-time-tracking [2021/07/06 14:59]
Line 1: Line 1:
-====== Time Tracking ====== 
----- dataentry summary ---- 
-name             : Time Tracking 
-description_wiki : Track your time spent on Tickets, via a calendar view 
-index_hidden ​    : yes 
-version ​         : 2.1.2 
-release_dt ​      : 2021-01-08 
-itop-version-min :  
-download_hidden ​ : http://​www.combodo.com/​itop-extensions/​itop-time-tracking-2.1.2-672.zip 
-code             : itop-time-tracking 
-state            : stable 
-product_hidden ​  : not-included 
-module-lists_hidden : itop-time-tracking/​2.1.2,​ itop-legacy-search-base/​1.0.0 
-diffusion ​       : Client Store, iTop Hub 
----- 
- 
- 
-<​related_components>​Other versions of this component:</​related_components>​ 
- 
-This extension provides a way to track the time spent by the end-users in association with objects in iTop (like Tickets). 
-The user input is done via a Google-like calendar via (provided by [[http://​arshaw.com/​fullcalendar|FullCalendar JS]]), either directly as an extra tab on the target object, or via a special page (and its menu "Track my time"​). 
- 
-The module also provides two menus pointing to reports: "My time tracking report",​ and "Time tracking report"​. The first menu provides a report of the activities of the current user only, while the second takes into account the activities of all users. 
- 
-The implementation provided by this extension limits the time tracking to User Requests and Incidents tickets. 
- 
- 
-===== Features ===== 
- 
-  * Customized scopes for each time tracking feature 
-  * Interactive time tracking via a calendar or a stopwatch 
-  * Configure your calendar settings, activity colors etc.. 
-  * Activity customization per user 
-  * Daily / weekly / monthly reports with multiple filtering criteria 
-  * Cumulated bar chart grouped by User or Customer 
- 
-===== Revision history ===== 
- 
-^ Date ^ Version ^ Description ^ 
-|  2020-11-04 ​ |  2.1.1  | Fix installation issue  | 
-|  2020-08-03 ​ |  2.1.0  | * Fix data not being filtered by search on report page \\       * Add an overview for Time tracker manager in report page \\       * Add silo for managers in config \\       * Add configuration for report chart in config \\       * Align chart color with time tracking colors | 
-|  2019-09-18 ​ |  2.0.0  | Release 2 with a complete redesign and features set | 
-|  2018-08-02 ​ |  1.0.2  | Compatibility with iTop 2.5 | 
-|  2014-08-29 ​ |  1.0.0  | First version | 
- 
- 
-===== Limitations ===== 
- 
- 
-===== Requirements ===== 
- 
- 
- 
-===== Installation ===== 
- 
-Use the [[extensions:​installation|Standard installation process]] for this extension. 
- 
-<note warning> 
-If you were using the previous version 1.0 of this extension you have to follow the migration procedure describe below 
-</​note>​ 
- 
-The migration procedure consists in executing the SQL request below in order to migrate the former data structure to the new one. 
-You have to execute those queries before tracking time 
- 
-<code sql> 
- 
-CREATE TABLE activity_legacy AS  
-  SELECT id,​person_id,​start_date,​start_time,​duration,​end_time,​ticket_id,​description FROM activity; 
-  ​ 
-insert into activity (obj_id,​obj_class,​background_color,​text_color,​label) 
-  select distinct a.ticket_id,​ t.finalclass,'#​0000ff','#​ffffff',​t.ref from activity_legacy AS a JOIN ticket AS t ON a.ticket_id=t.id;​ 
-  ​ 
-INSERT INTO timespent (id,​user_id,​start_date,​end_date,​duration,​org_id,​title,​description,​contact_id,​activity_id) 
-  SELECT 
-    ts.id, 
-    u.id, 
-    concat(ts.start_date,"​ ",​ts.start_time),​ 
-    concat(ts.start_date,"​ ",​ts.end_time),​ 
-    TIMESTAMPDIFF(SECOND,​concat(ts.start_date,"​ ",​ts.start_time),​concat(ts.start_date,"​ ",​ts.end_time)),​ 
-    t.org_id, 
-    t.ref, 
-    ts.description,​ 
-    ts.person_id,​ 
-    a.id 
-  FROM activity_legacy AS ts  
-  LEFT JOIN priv_user AS u ON ts.person_id = u.contactid ​ 
-  JOIN ticket AS t ON ts.ticket_id=t.id ​ 
-  JOIN activity AS a ON a.obj_id=ts.ticket_id AND a.obj_class = t.finalclass;​ 
-  ​ 
-  ​ 
-ALTER TABLE activity 
-  DROP person_id, 
-  DROP start_date, 
-  DROP start_time, 
-  DROP duration, 
-  DROP end_time, 
-  DROP ticket_id, 
-  DROP description;​ 
-  ​ 
-UPDATE priv_changeop SET objclass = "​TimeSpent"​ WHERE objclass = "​Activity";​ 
- 
-DELETE FROM activity WHERE obj_id = 0; 
- 
-</​code>​ 
- 
- 
-===== Configuration ===== 
- 
-<code php> 
-'​itop-time-tracking'​ => array( 
-        '​allowed_classes'​ => array ( 
-                '​UserRequest'​ => array( 
-                        '​calendar-tab'​ => '​SELECT UserRequest WHERE status != "​closed"',​ 
- '​calendar-page'​ => '​SELECT UserRequest WHERE status != "​new"',​ 
- '​stopwatch'​ => '​SELECT UserRequest',​ 
- '​report-tab'​ => '​SELECT UserRequest WHERE status != "​closed"',​ 
- ), 
- '​Incident'​ => array( 
-                        '​stopwatch'​ => '​SELECT Incident'​ 
-                ) 
-           ), 
- ​ '​colors'​ => array( 
- '​default_stopwatch'​ =>  array('​text'​=>​ '#​ffffff',​ '​background'​=>​ '#​a6a6a6'​),​ 
- '​default_calendar'​ =>  array('​text'​=>​ '#​ffffff',​ '​background'​=>​ '#​FFCC80'​),​ 
- '​classes'​ => array( 
- '​UserRequest'​ => array('​text'​=>​ '#​ffffff',​ '​background'​=>​ '​shadeof:​blue'​),​ 
- '​Incident'​ => array('​text'​=>​ '#​ffffff',​ '​background'​=>​ '​shadeof:​green'​) 
- ) 
- ), 
- '​default_event_duration'​ => '​00:​30:​00',​ 
- '​day_start_time'​ => '​04:​00:​00',​ 
- '​day_end_time'​ => '​21:​00:​00',​ 
- '​excluded_days'​ => array('​Saturday','​Sunday'​),​ 
- '​first_day'​ => 1, 
- '​business_hours'​=>​ array( 
- '​days_of_week'​ => array('​1',​ '​2',​ '​3',​ '​4',​ '​5'​),​ 
- '​start'​ => '​04:​00:​00',​ 
- '​end'​ => '​21:​00:​00',​ 
- ), 
- '​minimum_event_duration_display'​ => '​00:​30:​00',​ 
- '​stopwatch_clean_periodicity'​ => 12, 
- '​stopwatch_max_time'​ => 12, 
- '​delete_max_event_age'​ => 30, 
- '​manager_report_silo'​ => '​SELECT Person',​ 
- '​weekly_report_time_spent_attribute'​ => '',​ 
- '​weekly_report_time_spent_default'​ => '​30hrs',​ 
- '​report_charts_definition'​ => array( 
- array('​group_by_attribute'​ => '​contact_id',​ '​label'​ => '​TimeTracking:​ReportActivityPerUser'​),​ 
- array('​group_by_attribute'​ => '​org_id',​ '​label'​ => '​TimeTracking:​ReportActivityPerCustomer'​) 
- ) 
-), 
-</​code>​ 
- 
-^ Parameter ^ Meaning ^ Sample value ^ 
-| allowed_classes| array of type of class for which time tracking is allowed. For each class you can define a array of time tracking mode you allow.| ​ | 
-| colors| array defining the default colors globaly and by type of object. The array default_stopwatch defines the default color for a stopwatch. The array default_calendar defines the default color for time tracked in a calendar view. The you can define an array for each type fo object (classes) to define a default color for this one |  | 
-|default_event_duration| duration of an activity by default| 30 minutes| 
-|clone_events| **Since 2.1.3** allow user to clone time spent via ctrl+click| false| 
-|day_start_time| start time in the calendar view | 6:00 | 
-|day_end_time| end time in the calendar view| 22:00 | 
-|excluded_days| days that are excluded from the calendar view| saturday, sunday| 
-|first_day| first day in the calendar view 0 is Sunday, 1 is Monday| 1:Monday | 
-|business_hours| array describing the business hours| Monday to Friday 8:00 - 18:00 | 
-|minimum_event_duration_display| minimum duration displayed in a calendar view even if the time spent is lower|30 minutes| 
-|stopwatch_clean_periodicity| periodicity to stop checking if a stop watch has to be stopped| 1 hour| 
-|stopwatch_max_time| max duration in hours of a stopwatch if it is not stop manualy by a user| 4 hours| 
-|delete_max_event_age| duration in days after which a user cannot modify or create a time spent| 30 days| 
-|default_report_query| **Since 2.1.3** Time spent scope for self report (available placeholder:​ contact_id, start| SELECT TimeSpent WHERE contact_id = :contact_id AND start_date >= :start_date AND end_date < :end_date | 
-|manager_report_query| **Since 2.1.3** Time spent scope for self report (available placeholder:​ contact_id, start| SELECT TimeSpent WHERE start_date >= :start_date AND end_date < :end_date | 
-|manager_report_silo| The silo describing what Contacts Time Tracking Managers will be able to see| SELECT Person| 
-|weekly_report_time_spent_attribute| Attribute describing the expected time shown in Time Tracking Manager Overview| //empty//| 
-|weekly_report_time_spent_default| Describe the default value in case `weekly_report_time_spent_default` is empty (can be a dictionary entry)| '​30hrs'​| 
-|report_charts_definition| Define the charts displayed at the bottom of Time Tracking report page|  array( array('​group_by_attribute'​ => '​contact_id',​ '​label'​ => '​TimeTracking:​ReportActivityPerUser'​),​ array('​group_by_attribute'​ => '​org_id',​ '​label'​ => '​TimeTracking:​ReportActivityPerCustomer'​))| 
-Time tracking modes 
-  * calendar tab : the user is allowed to set time tracking in a tab directly on the corresponding objects 
-  * calendar page : the user can track time in "My time tracking"​ page for the corresponding objects 
-  * stopwatch : the user cans track time using a stopwatch for the corresponding objects 
-  * report-tab : a reporting tab is displayed for the corresponding objects 
- 
- 
- 
- 
-==== Colors ==== 
- 
-Either use an hexadecimal color, or use a shadeof://​color//​ where //color// is one of the following value and will pick randomly for each object a corresponding color. 
- 
-^ blue |{{:​extensions:​time-tracking:​blue1.png?​direct&​300}}||{{:​extensions:​time-tracking:​blue2.png?​direct&​300}}|{{:​extensions:​time-tracking:​blue3.png?​direct&​300}}|{{:​extensions:​time-tracking:​blue4.png?​direct&​300}}|{{:​extensions:​time-tracking:​blue5.png?​direct&​300}}|{{:​extensions:​time-tracking:​blue6.png?​direct&​300}}|{{:​extensions:​time-tracking:​blue7.png?​direct&​300}}|{{:​extensions:​time-tracking:​blue8.png?​direct&​300}}|{{:​extensions:​time-tracking:​blue9.png?​direct&​300}}| | 
-^ bluegrey |{{:​extensions:​time-tracking:​bluegrey1.png?​direct&​300}}||{{:​extensions:​time-tracking:​bluegrey2.png?​direct&​300}}|{{:​extensions:​time-tracking:​bluegrey3.png?​direct&​300}}|{{:​extensions:​time-tracking:​bluegrey4.png?​direct&​300}}|{{:​extensions:​time-tracking:​bluegrey5.png?​direct&​300}}|{{:​extensions:​time-tracking:​bluegrey6.png?​direct&​300}}|{{:​extensions:​time-tracking:​bluegrey7.png?​direct&​300}}|{{:​extensions:​time-tracking:​bluegrey8.png?​direct&​300}}|{{:​extensions:​time-tracking:​bluegrey9.png?​direct&​300}}| | 
-^ cyan |{{:​extensions:​time-tracking:​cyan1.png?​direct&​300}}||{{:​extensions:​time-tracking:​cyan2.png?​direct&​300}}|{{:​extensions:​time-tracking:​cyan3.png?​direct&​300}}|{{:​extensions:​time-tracking:​cyan4.png?​direct&​300}}|{{:​extensions:​time-tracking:​cyan5.png?​direct&​300}}|{{:​extensions:​time-tracking:​cyan6.png?​direct&​300}}|{{:​extensions:​time-tracking:​cyan7.png?​direct&​300}}|{{:​extensions:​time-tracking:​cyan8.png?​direct&​300}}|{{:​extensions:​time-tracking:​cyan9.png?​direct&​300}}| | 
-^ green |{{:​extensions:​time-tracking:​green1.png?​direct&​300}}||{{:​extensions:​time-tracking:​green2.png?​direct&​300}}|{{:​extensions:​time-tracking:​green3.png?​direct&​300}}|{{:​extensions:​time-tracking:​green4.png?​direct&​300}}|{{:​extensions:​time-tracking:​green5.png?​direct&​300}}|{{:​extensions:​time-tracking:​green6.png?​direct&​300}}| | | | | 
-^ grey |{{:​extensions:​time-tracking:​grey1.png?​direct&​300}}||{{:​extensions:​time-tracking:​grey2.png?​direct&​300}}|{{:​extensions:​time-tracking:​grey3.png?​direct&​300}}|{{:​extensions:​time-tracking:​grey4.png?​direct&​300}}|{{:​extensions:​time-tracking:​grey5.png?​direct&​300}}|{{:​extensions:​time-tracking:​grey6.png?​direct&​300}}| | | | | | 
-^ lime |{{:​extensions:​time-tracking:​lime1.png?​direct&​300}}||{{:​extensions:​time-tracking:​lime2.png?​direct&​300}}|{{:​extensions:​time-tracking:​lime3.png?​direct&​300}}|{{:​extensions:​time-tracking:​lime4.png?​direct&​300}}|{{:​extensions:​time-tracking:​lime5.png?​direct&​300}}|{{:​extensions:​time-tracking:​lime6.png?​direct&​300}}|{{:​extensions:​time-tracking:​lime7.png?​direct&​300}}|{{:​extensions:​time-tracking:​lime8.png?​direct&​300}}| | | 
-^ orange |{{:​extensions:​time-tracking:​orange1.png?​direct&​300}}||{{:​extensions:​time-tracking:​orange2.png?​direct&​300}}|{{:​extensions:​time-tracking:​orange3.png?​direct&​300}}|{{:​extensions:​time-tracking:​orange4.png?​direct&​300}}|{{:​extensions:​time-tracking:​orange5.png?​direct&​300}}|{{:​extensions:​time-tracking:​orange6.png?​direct&​300}}|{{:​extensions:​time-tracking:​orange7.png?​direct&​300}}|{{:​extensions:​time-tracking:​orange8.png?​direct&​300}}|{{:​extensions:​time-tracking:​orange9.png?​direct&​300}}| | 
-^ purple |{{:​extensions:​time-tracking:​purple1.png?​direct&​300}}||{{:​extensions:​time-tracking:​purple2.png?​direct&​300}}|{{:​extensions:​time-tracking:​purple3.png?​direct&​300}}|{{:​extensions:​time-tracking:​purple4.png?​direct&​300}}|{{:​extensions:​time-tracking:​purple5.png?​direct&​300}}|{{:​extensions:​time-tracking:​purple6.png?​direct&​300}}|{{:​extensions:​time-tracking:​purple7.png?​direct&​300}}|{{:​extensions:​time-tracking:​purple8.png?​direct&​300}}|{{:​extensions:​time-tracking:​purple9.png?​direct&​300}}| | 
-^ red |{{:​extensions:​time-tracking:​red1.png?​direct&​300}}||{{:​extensions:​time-tracking:​red2.png?​direct&​300}}|{{:​extensions:​time-tracking:​red3.png?​direct&​300}}|{{:​extensions:​time-tracking:​red4.png?​direct&​300}}|{{:​extensions:​time-tracking:​red5.png?​direct&​300}}|{{:​extensions:​time-tracking:​red6.png?​direct&​300}}|{{:​extensions:​time-tracking:​red7.png?​direct&​300}}|{{:​extensions:​time-tracking:​red8.png?​direct&​300}}|{{:​extensions:​time-tracking:​red9.png?​direct&​300}}| | 
-^ rainbow |{{:​extensions:​time-tracking:​rainbow1.png?​direct&​300}}||{{:​extensions:​time-tracking:​rainbow2.png?​direct&​300}}|{{:​extensions:​time-tracking:​rainbow3.png?​direct&​300}}|{{:​extensions:​time-tracking:​rainbow4.png?​direct&​300}}|{{:​extensions:​time-tracking:​rainbow5.png?​direct&​300}}|{{:​extensions:​time-tracking:​rainbow6.png?​direct&​300}}|{{:​extensions:​time-tracking:​rainbow7.png?​direct&​300}}|{{:​extensions:​time-tracking:​rainbow8.png?​direct&​300}}|{{:​extensions:​time-tracking:​rainbow9.png?​direct&​300}}|{{:​extensions:​time-tracking:​rainbow10.png?​direct&​300}}| 
- 
- 
-===== Usage ===== 
- 
-A user can track her/his time in multiple way: 
-  * From the "Time Tracking"​ tab on the details of an object present in a "​calendar-tab"​ scope 
-  * From the "Track my time" menu if objects are present in a "​calendar-page"​ scope 
-  * From the stopwatch on the right of the screen on the details of an object present in a "​stopwatch"​ scope 
- 
- 
-Two new profiles are defined with this extension: 
-  * Time Tracker 
-  * Time Tracking Manager 
-<​note>​ 
-A user can track his time only if he has one of those 2 profils. ​ 
-</​note>​ 
-A user having the //Time Tracker// profil can only track time for himself and see only his time tracked 
- 
-A user having ​ the //Time tracking// Manager profil can track time for other and will have access to the time tracked by anybody 
- 
-==== From the details of a ticket ==== 
- 
-An extra tab "Time Tracking"​ appears once the extension is installed. Inside the tab a calendar shows the activities associated with the ticket. The activities of the current user are shown in color, whereas the activities of all other users (on this object) and stopwatches appear in ```default_calendar``` and ```default_stopwatch``` color (see configuration). Clicking on an item in the calendar displays a popup to edit this event. 
-To create a new activity, simply click and drag in the calendar. ​ 
-You also change the start date & time or the duration of an Activity by clicking it in the calendar. 
- 
- 
-{{:​extensions:​time-tracking:​tt2.png?​direct&​700|Time Tracking tab}} 
- 
- 
-==== From the "Track my time" menu ==== 
- 
-The same kind of editing is possible from the "Track my time" menu. 
-You need to select an activity in the combobox, from there you set your favorite activities and customize its color. 
- 
-  * The top search bare use auto-complete mecanism 
-  * To set your favorite activity, you just have to click on the "​heart"​ icon.  
-  * To customize the color, you have to click on the "​pencil"​ icon. 
-  * The drop down list display first your favorite activities, then other activities grouped by type (User Request, Customer Contract ...) 
- 
-{{:​extensions:​time-tracking:​tt3.png?​direct&​700|Select activity (classic mode)}} 
- 
-You can pick a "​classic mode" with the combobox always visible or a "modal mode" which prompts a modal each time to click and drag on the calendar. 
- 
-{{:​extensions:​time-tracking:​tt4.png?​direct&​700|Select activity (modal mode)}} 
- 
-Each calendar has multiple views: month, week, day ,list. 
- 
-^ Week view ^ Month view ^ List view ^ 
-|{{:​extensions:​time-tracking:​tt1.png?​direct&​700|Week view}}|{{:​extensions:​time-tracking:​tt5.png?​direct&​700|Month view}}|{{:​extensions:​time-tracking:​tt6.png?​direct&​700|List view}}| 
- 
- 
-==== From the stopwatch ==== 
- 
-A simple icon appears on the right of eligible object. The icon will be black if the stopwatch is not running or green if it's tracking time at the moment. 
- 
-{{:​extensions:​time-tracking:​tt7.png?​direct&​700|Right icon}} 
- 
-Clicking on this icon will display the stopwatch widget with buttons to start/​stop/​reset the stopwatch and the recent tracking history of the object with few information : Contacts whom tracked time on this object, the time spent and its date, the origin of this tracked time (stopwatch or calendar) 
- 
-{{:​extensions:​time-tracking:​tt8.png?​direct&​400|Opened widget}} 
- 
-If you start a stopwatch and go on another object, you'll be prompted by the widget that you are visiting an object while you track time on another object. 
- 
-{{:​extensions:​time-tracking:​tt9.png?​direct&​400|Opened widget}} 
- 
-====== Reporting ====== 
- 
-The extension provides some basic reporting capabilities via two menus: "Time tracking report"​ and "My time tracking report"​ and a "Time spent" tab on each object present in ```report-tab``` scopes (see configuration). ​ 
- 
-Those menus are available, only if the user has one of the time tracking profils. The "Time tracking report"​ menu is available only for the time tracking managers. 
- 
-The result is a list of "​TimeSpent"​ objects, which can be exported if needed. 
- 
-Both menus show the same information,​ the only difference is that the latter is limited to displaying the activities of the current user only. 
- 
-{{:​extensions:​time-tracking-report.png?​700|Time Tracking Report}} 
- 
-The report can be a daily / weekly or monthly report (use the "​prev."​ and "​next"​ buttons at the top left to navigate to the desired date), and the results can be filtered by additional criteria. 
- 
- 
-Moreover, at the bottom of the page, several bars charts display the total activity, per day, grouped on one given dimension (User, Customers...) 
- 
-The TimeSpent data can be retrieved by an OQL query and exported using the standard iTop export capability 
- 
-Here are some query example to extract time spent information:​ 
- 
- 
-//Time spent by the current user (My Time Spent)// 
-<code sql> 
-SELECT TimeSpent WHERE user_id=:​current_user_id 
-</​code>​ 
- 
-//Time spent by Claude Monet// 
-<code sql> 
-SELECT TimeSpent AS ts JOIN Person AS p ON ts.contact_id=p.id WHERE p.friendlyname='​Claude Monet' 
-</​code>​ 
- 
-//Time spent for a given organization//​ 
-<code sql> 
-SELECT TimeSpent AS ts JOIN Organization AS o ON ts.org_id=o.id WHERE o.name='​Demo'​ 
-</​code>​ 
-====== Notification Trigger ====== 
- 
-This extension brings a new Trigger: **Trigger (when a time tracking stopwatch times out)** 
-This one is triggered when a time spent stopwatch reach the threshold "​stopwatch_max_time"​ 
- 
-The class configured for this trigger is TimeSpentBackground ($this) and can be used as a placeholder in the related filter and Actions 
- 
-{{ :​extensions:​triggertimespent.png?​direct&​400 |}} 
- 
-You can use this trigger to inform a user that a TimeSpent stopwatch had been stopped automatically after a given delay 
- 
-====== Question and Answer====== 
-**Q: What happen if I suppress a ticket for which I tracked time? \\ 
-A:** The TimeSpent related to this ticket is not suppressed, just the id of the Ticket is reset to 0. 
- 
- 
-====== Customization ====== 
- 
-The class TimeSpent is defined in XML, so it can be edited to add additional attributes if required. 
- 
- 
  
extensions/itop-time-tracking.txt ยท Last modified: 2021/07/06 14:59 (external edit)

";