Make It Workflow — Part 6: Tracking Spent Time

Mariya Davydova

Welcome back to our Make It Workflow series! In previous posts, we described solutions to problems like how to shield your issues from spying eyes and strategies for streamlining issue creation. From here on out, we’ll look at workflows that support specific use cases, like enhancing time tracking functionality or making your helpdesk more powerful.

Let’s start with time tracking.

The Time Tracking Feature

Time Tracking has been available in YouTrack for quite a long time. If you want to learn the fundamentals, there’s a tutorial in the documentation. 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:

• Spent time — displays the total amount of time that is recorded in all of 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.

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.

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.

You can read more about these workflows in our documentation.

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.

Fighting the Cheaters

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:

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

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

exports.rule = entities.Issue.onChange({
  title: 'Prohibit adding work items with dates in the past',
  guard: function(ctx) {
    return ctx.issue.workItems.added.isNotEmpty();
  },
  action: function(ctx) {
    ctx.issue.workItems.added.forEach(function(item) {
      var itemDate = new Date(item.date).setUTCHours(0, 0, 0, 0);
      var 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:

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

exports.rule = entities.Issue.onChange({
  title: 'Prohibit adding work items with dates in the future',
  guard: function(ctx) {
    return ctx.issue.workItems.added.isNotEmpty();
  },
  action: function(ctx) {
    ctx.issue.workItems.added.forEach(function(item) {
      var itemDate = new Date(item.date).setUTCHours(0, 0, 0, 0);
      var 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:

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

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

exports.rule = entities.Issue.onChange({
  title: 'Prohibit editing work items with dates in the past',
  guard: function(ctx) {
    return ctx.issue.editedWorkItems.isNotEmpty();
  },
  action: function(ctx) {
    ctx.issue.editedWorkItems.forEach(function(item) {
      var itemDate = new Date(item.date).setUTCHours(0, 0, 0, 0);
      var 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: {}
});

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

exports.rule = entities.Issue.onChange({
  title: 'Prohibit editing work items in future',
  guard: function(ctx) {
    return ctx.issue.editedWorkItems.isNotEmpty();
  },
  action: function(ctx) {
    ctx.issue.editedWorkItems.forEach(function(item) {
      var itemDate = new Date(item.date).setUTCHours(0, 0, 0, 0);
      var 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:

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

exports.rule = entities.Issue.onChange({
  title: 'Prohibit deleting work items',
  guard: function(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.

One last remark: these rules use functionality that is only available from YouTrack 2018.1.39916. If you haven’t upgraded your installation to the latest version, consider doing so today!

In our next article, we show you how to collect these work items and generate time tracking reports for employees and team leads. While we prepare the post for you, satisfy your curiosity by browsing other workflow-related resources:

• Watch our YouTrack Custom Workflow Repository in Git. We are uploading all of the workflows that we introduce in this series.
• Join our YouTrack Workflow Community in Slack. Interact directly with the YouTrack development team and see how other users support their business logic with workflows.
• Read the YouTrack documentation. We’ve got a wide range of topics for everyone from beginners to seasoned experts.

Subscribe to YouTrack Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!