Track Spent Time

Time Tracking is a standard feature in YouTrack. If you want to learn the fundamentals, read the Time Tracking Tutorial. Here’s a brief overview.

This feature lets you quantify the effort that is invested into an issue. This effort is recorded in work items. Each work item logs the amount of time spent working on an issue. These work items can be assigned different categories, like development, testing, or any other type of activity that you want to aggregate and track.

Time tracking data is recorded in custom fields:

Field	Description
Spent time	Displays the total amount of time that is recorded in all the work items that have been added to the issue.
Estimation	Stores the amount of time that you think would be required to complete the task.

By analyzing the difference between the values in these fields, you can measure the overall performance of your team.

Time tracking can also be used without estimations when you just want to record your activity in billable hours.

By default, these fields store values as a period. Period custom fields represent intervals of time in a human-readable form, so you record the estimation and view spent time in a number of weeks, days, and hours. The number of working days per week and working hours per day are configured at the global level. If you change these settings, the calculations are updated accordingly. For more information, see Time Tracking.

Default Workflows that Track Time

Work items are often used for billing, so it’s important that they are recorded accurately. However, employees who are obliged to add these work items tend to either forget about them or try to cheat the system. Both of these problems can be regulated with the help of workflows.

YouTrack supplies default workflows that add work items to issues automatically under specific conditions.

Default Workflow	Description
In Progress Work Timer	This workflow starts a time when an issue moves to the In Progress state. When the issue moves to a state that is marked as Resolved, the timer stops. The amount of elapsed time between these state changes is added as a work item.
Stopwatch-style Work Timer	Here, the timer is stopped and started manually based on the value in a custom field named Timer. This field stores two values: Start and Stop. Each time the value changes to Stop, the elapsed time is recorded in a work item on behalf of the current user. Switching the value back to Start resets the timer.
Pomodoro Timer	This workflow uses a state machine to imitate the Pomodoro technique. It changes the value in a dedicated Pomodoro state field so that you follow each 25-minute period of work with a 5-minute period of rest. The respective work items are added to the issue automatically.

These workflows help solve the problem of forgetting to record work items, but they don’t offer any solutions for users who try to cheat the system.

Set Limits for Time Tracking

Let’s take a look at a few tactics for enhancing the time tracking feature with rules that prohibit actions that violate your standard operating procedures.

Your business practice may differ, but let’s assume that your employees are expected to add the work items the same day the work is performed or at least within a few days. Adding work items with dates more than one week in the past is against the rules.

The corresponding rule is written as follows:

      const entities = require('@jetbrains/youtrack-scripting-api/entities');
      const workflow = require('@jetbrains/youtrack-scripting-api/workflow');

      const WEEK_IN_MS = 7 * 24 * 60 * 60 * 1000;

      exports.rule = entities.Issue.onChange({
        title: 'Prohibit adding work items with dates in the past',
        guard: (ctx) => {
          return ctx.issue.workItems.added.isNotEmpty();
        },
        action: (ctx) => {
          ctx.issue.workItems.added.forEach(function (item) {
            const itemDate = new Date(item.date).setUTCHours(0, 0, 0, 0);
            const today = new Date().setUTCHours(0, 0, 0, 0);
            workflow.check(itemDate >= today - WEEK_IN_MS,
                'Adding work more than one week in the past is not allowed!');
          });
        },
        requirements: {}
      });
    

When this rule is enabled, users cannot add work items with dates more than one week in the past. If you want to make the restriction more stringent, you can limit the date to one or two days in the past. It’s just a matter of setting the value for the constant. In our case, WEEK_IN_MS.

Adding work items for dates in the future is also frowned upon, as it is impossible to accurately predict how much time will be spent working on the issue.

Here’s a rule that clocks out the clairvoyants:

      const entities = require('@jetbrains/youtrack-scripting-api/entities');
      const workflow = require('@jetbrains/youtrack-scripting-api/workflow');

      exports.rule = entities.Issue.onChange({
        title: 'Prohibit adding work items with dates in the future',
        guard: (ctx) => {
          return ctx.issue.workItems.added.isNotEmpty();
        },
        action: (ctx) => {
          ctx.issue.workItems.added.forEach(function (item) {
            const itemDate = new Date(item.date).setUTCHours(0, 0, 0, 0);
            const today = new Date().setUTCHours(0, 0, 0, 0);
            workflow.check(itemDate <= today,
                'You can’t add work that hasn’t been performed yet!');
          });
        },
        requirements: {}
      });
    

If you have serious concerns about your employees’ intent to cheat, don’t forget about the ability to edit work items! Users can still game the system by creating a work item with today’s date and editing the work item to use any date they like.

Here’s a set of rules that apply the same restrictions used for adding work items in the past and future to block edits to work items that would violate the same policy:

      const entities = require('@jetbrains/youtrack-scripting-api/entities');
      const workflow = require('@jetbrains/youtrack-scripting-api/workflow');

      const WEEK_IN_MS = 7 * 24 * 60 * 60 * 1000;

      exports.rule = entities.Issue.onChange({
        title: 'Prohibit editing work items with dates in the past',
        guard: (ctx) => {
          return ctx.issue.editedWorkItems.isNotEmpty();
        },
        action: (ctx) => {
          ctx.issue.editedWorkItems.forEach(function (item) {
            const itemDate = new Date(item.date).setUTCHours(0, 0, 0, 0);
            const today = new Date().setUTCHours(0, 0, 0, 0);
            workflow.check(itemDate >= today - WEEK_IN_MS,
                'Editing work items to be earlier than a week ago is not allowed!');
          });
        },
        requirements: {}
      });
    

      const entities = require('@jetbrains/youtrack-scripting-api/entities');
      const workflow = require('@jetbrains/youtrack-scripting-api/workflow');

      exports.rule = entities.Issue.onChange({
        title: 'Prohibit editing work items in future',
        guard: (ctx) => {
          return ctx.issue.editedWorkItems.isNotEmpty();
        },
        action: (ctx) => {
          ctx.issue.editedWorkItems.forEach(function (item) {
            const itemDate = new Date(item.date).setUTCHours(0, 0, 0, 0);
            const today = new Date().setUTCHours(0, 0, 0, 0);
            workflow.check(itemDate <= today,
                'Editing work items to use a date in the future is not allowed!');
          });
        },
        requirements: {}
      });
    

Our last rule makes sure that nobody can cook the books. Once a work item has been added to an issue, this rule prevents anyone from removing it:

      const entities = require('@jetbrains/youtrack-scripting-api/entities');
      const workflow = require('@jetbrains/youtrack-scripting-api/workflow');

      exports.rule = entities.Issue.onChange({
        title: 'Prohibit deleting work items',
        guard: (ctx) => {
          return ctx.issue.workItems.removed.isNotEmpty();
        },
        action: function (/* ctx */) {
          workflow.check(false, 'Work items are not allowed to be removed!');
        },
        requirements: {}
      });
    

You can use these rules as a starting point and apply constraints that suit your business process. Here are a few alternative implementations:

You can let users remove work items that were added in the last week and only prohibit removing work items that with dates that are over one week in the past.
Instead of restricting adding and editing work items with dates more than a week in the past, you can limit the range to dates no earlier than the start of the work week.
You can modify the restrictions so that they are not applied to the project owner or team lead.

Last modified: 29 February 2024