Make It Workflow — Part 8: Helping the Helpdesk

Mariya Davydova

Many organizations use an issue tracker to support their helpdesk. YouTrack provides tools that let you communicate with your customers by email without creating accounts for every user. In this post, we describe how workflows help you further improve helpdesk support.

Core Components for Using YouTrack as a Helpdesk

YouTrack provides three main features that let you use it as a helpdesk:

• The Mailbox Integration, which pulls email messages from one or more email servers on a regular basis and processes them to create issues and comments.
• Email Notifications, which let you send messages to any email address.
• And, of course, Workflows, which help you glue it all together!

The basic flow that is supported in YouTrack works as follows:

• A customer sends an email message to your support inbox. This creates a new issue in YouTrack.
• A support engineer responds to the inquiry by adding a comment to the issue. This generates an email notification that is sent back to the customer as a reply to the original email.
• The custom replies to the email notification. The response is processed by YouTrack and added as a comment to the original issue.

You can find a detailed description of this feature in our Helpdesk Tutorial.

Service-level Agreements

An important element for an established product support team is the service-level agreement (SLA). This helps set the customers’ expectations for receiving an answer to their requests and comments.

Take a look at the YouTrack SLA as an example.

For the purposes of this blog post, we’ll simplify the rules a bit:

• Business hours are from 10:00 – 18:00 CET.
• Customers can expect a response to their initial support request within three hours.
• The response time for a follow-up request is four hours.

As you can see from our own SLA, the response times can differ based on customer plans, ticket priorities, and other factors.

You can support an SLA in YouTrack with a workflow. In YouTrack, we’ll customize the setup for our helpdesk project as follows:

• The project that we use for the helpdesk uses the following values for the State field: New (for tickets that are just created), Open (for tickets that are waiting for a reaction from the support team), Pending (for tickets that are waiting for a reaction from the customer), On hold (for tickets that require input from a developer), and Fixed (for resolved tickets).
• For New tickets that have not been answered by the support team, the Overdue tag is added three business hours after the issue was created.
• For Open tickets, the Overdue tag is added four business hours after the last comment from a customer was added.
• To sort tickets in the order that they should be answered, we add a private custom field: To reply before. This field stores values as a date and time.

When we set up these fields and attach the corresponding workflow rules, the support team can pull tickets from a queue that is ordered by response time using the following query:

“State: Open, New sort by: {To reply before} asc”

First, we need a utility function that defines our business hours. This is saved as a custom script with the name ‘time-operations’.

// Starting hour of the business day defined in the server time zone.
var START = 10;

// Finishing hour of the business day defined in the server time zone.
var FINISH = 18;

// Length of the business day in hours.
var BUSINESS_DAY_LENGTH = FINISH - START;

var HOUR_IN_MS = 60 * 60 * 1000;
var DAY_IN_MS = 24 * HOUR_IN_MS;

/*
 * @param {Date} [date] date to check to be inside business hours interval
 * @return {boolean} `true` is the date is within [START, FINISH) interval on
 * business days and `false` otherwise
 */
var isWithinBusinessHours = function(date) {
  var date1 = new Date(date);
  var dayOfWeek = date1.getDay();
  if (dayOfWeek === 0 || dayOfWeek === 1) {
    return false;
  }
  var hour = date1.getHours();
  return (hour >= START && hour < FINISH);
};

/*
 * @param {Number} [date] date in ms from the start of the epoch
 * @param {Number} [hours] number of hours to add to this date
 * @returns {Number} resulting date with respect to business hours, defined above
 */
var addBusinessHours = function(date, hours) {
  var result = date + hours * HOUR_IN_MS;
  if (!isWithinBusinessHours(new Date(result))) {
    // It's evening, let's skip the night.
    result += (24 - BUSINESS_DAY_LENGTH) * HOUR_IN_MS;
  }
  if (!isWithinBusinessHours(new Date(result))) {
    // It's the weekend, let's skip it too.
    result += 2 * DAY_IN_MS;
  }
  return result;
};

exports.addBusinessHours = addBusinessHours;

Now, we can set the value of the To reply before field according to our SLA. Here, we have two rules — one for the initial response and a second for the follow-up.

var entities = require('@jetbrains/youtrack-scripting-api/entities');
var timeOp = require('./time-operations');

// Number of business hours to reply to the new issue.
var NEW_ISSUE_SLA = 3;

exports.rule = entities.Issue.onChange({
  title: 'New Issue SLA',
  guard: function(ctx) {
    return ctx.issue.becomesReported;
  },
  action: function(ctx) {
    ctx.issue.fields.ToReply = timeOp.addBusinessHours(Date.now(), NEW_ISSUE_SLA);
  },
  requirements: {
    ToReply: {
      type: entities.Field.dateTimeType,
      name: 'To reply before'
    }
  }
});

var entities = require('@jetbrains/youtrack-scripting-api/entities');
var timeOp = require('./time-operations');

// Number of business hours to reply to the replied issue.
var REPLIED_ISSUE_SLA = 4;

exports.rule = entities.Issue.onChange({
  title: 'Replied Issue SLA',
  guard: function(ctx) {
    var comments = ctx.issue.comments;
    return comments.added.isNotEmpty() &&
      comments.added.last().author.login === ctx.helpdeskBot.login;
  },
  action: function(ctx) {
    ctx.issue.fields.ToReply = timeOp.addBusinessHours(Date.now(), REPLIED_ISSUE_SLA);
  },
  requirements: {
    ToReply: {
      type: entities.Field.dateTimeType,
      name: 'To reply before'
    },
    // This is the user which is set as reporter in mail rule settings:
    helpdeskBot: {
      type: entities.User,
      login: 'helpdesk-bot'
    }
  }
});

The following rule adds the Overdue tag to tickets when the SLA is violated:

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

exports.rule = entities.Issue.onSchedule({
  title: 'Set “Overdue” tag',
  cron: '0 * * * * ?',
  search: 'State: Open, New has: {To reply before} tag: -overdue',
  action: function(ctx) {
    var toReply = ctx.issue.fields.ToReply;
    if (toReply < Date.now()) {
      ctx.issue.addTag(ctx.overdue.name);
    }
  },
  requirements: {
    ToReply: {
      type: entities.Field.dateTimeType,
      name: 'To reply before'
    },
    overdue: {
      type: entities.IssueTag
    }
  }
});

And finally, we clear the value from the To reply before field and remove the Overdue tag when the ticket no longer requires a response from the support team:

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

exports.rule = entities.Issue.onChange({
  title: 'Clear "To reply before" field and remove “Overdue” tag when issue is not “New” or “Open”',
  guard: function(ctx) {
    var fs = ctx.issue.fields;
    return fs.isChanged(ctx.State) && fs.State &&
      fs.State.name !== ctx.State.New.name &&
      fs.State.name !== ctx.State.Open.name;
  },
  action: function(ctx) {
    var issue = ctx.issue;
    issue.fields.ToReply = null;
    if (issue.hasTag(ctx.overdue.name)) {
      issue.removeTag(ctx.overdue.name);
    }
  },
  requirements: {
    State: {
      type: entities.State.fieldType,
      Open: {},
      New: {}
    },
    ToReply: {
      type: entities.Field.dateTimeType,
      name: 'To reply before'
    },
    overdue: {
      type: entities.IssueTag
    }
  }
});

You can apply additional logic to these rules depending on the terms of your support SLA, for example:

• You can assign priorities to each ticket and change the SLA response times based on the priority.
• You can set up a state machine to restrict the legal transitions between values for the State field.
• If you have an international team that works in different time zones and business hours, you can tune the ‘time-operations’ script to take these into account for each member of the support team.

Round Robin Rotations

Another popular helpdesk practice is to assign new tickets based on a round-robin scheme. This balances the workload between members of the support team. The idea is simple — whenever a new ticket appears, it is assigned to the team member who is assigned the fewest New and Open tickets.

The implementation is straight-forward. When a new ticket is created, the workflow rule checks the workload of each support engineer. The member of the team with the fewest tickets is selected as the assignee.

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

exports.rule = entities.Issue.onChange({
  title: 'Set Assignee automatically via Round Robin scheme',
  guard: function(ctx) {
    var issue = ctx.issue;
    return issue.becomesReported && !issue.fields.Assignee;
  },
  action: function(ctx) {
    var assignees = ctx.Assignee.values;
    var numbers = {};
    assignees.forEach(function(assignee) {
      numbers[assignee.login] = 0;
    });
    
    var issues = search.search(ctx.issue.project, '#unresolved has: Assignee');
    issues.forEach(function(issue) {
      numbers[issue.fields.Assignee.login] += 1;
    });
  
    var min = Number.MAX_VALUE;
    var user = null;
    assignees.forEach(function(assignee) {
      if (numbers[assignee.login] < min) {
        min = numbers[assignee.login];
        user = assignee;
      }
    });
    
    ctx.issue.fields.Assignee = user;
  },
  requirements: {
    Assignee: {
      type: entities.User.fieldType
    }
  }
});

You can use this scheme not just for the helpdesk, but also for any process where you want to balance the workload. Also, the rules for balancing new assignments can be much more complex. For example, you can assign higher weights to overdue tickets.

We hope that these examples help you improve the effectiveness of your helpdesk support.

In our next article, we show you how you can use workflows for an unexpected use case — as an engine for sending newsletters. While you wait for the next installment, extend your knowledge by exploring 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!