SLA Rules
An SLA policy rule defines the set of time goals for tickets in a helpdesk project.
In the settings of a helpdesk project, you can build an SLA using various fields and controls. When the options for building an SLA policy in the UI are not enough for your scenario, you can write a custom policy. Custom SLA policy rules are written in JavaScript using the Workflow API.
note
Currently, the only way to create an SLA policy rule is from the project settings. It's not possible to create a JavaScript SLA rule from the script editor.
To learn how to create a JavaScript SLA rule, see YouTrack documentation.
Sample SLA Policy Rule
This SLA is applied to the tickets with the Type field set to Incident. YouTrack performs the following actions:
YouTrack checks the comments to the ticket and determines whether it has any comments from agents.
If the ticket doesn't have any comments from agents and if the SLA goals field is set to the High value, the value for the First reply field is set to 3 hours.
If the ticket becomes resolved, the SLA cycle ends and the First reply field is cleared.
When the SLA goal is breached, the responsible agent receives a notification that a high-priority ticket is overdue.
note
Tickets in the Workflow APIWhen an issue is created in a helpdesk project, YouTrack refers to it as a ticket. However, in the context of the Workflow API, a ticket and an issue are the same entity.
YouTrack uses the Workflow API for JavaScript SLA rules. This API is applicable to both issues and tickets in YouTrack.
const entities = require('@jetbrains/youtrack-scripting-api/entities');
const REPLY_TIME_IN_MIN = 3*60; //3 hours
const SLA_CALENDAR = entities.Calendar24x7.instance();
exports.rule = entities.Issue.sla({
title: "First Reply SLA for High Priority Incidents",
guard: (ctx) => {
const issue = ctx.issue;
return (issue.isReported || issue.becomesReported) && issue.fields.is(ctx.Type, ctx.Type.Incident);
},
onEnter: (ctx) => {
configureBreach(ctx);
},
action: (ctx) => {
const issue = ctx.issue;
if (issue.becomesResolved) {
issue.fields[ctx.firstReply.name] = null;
return;
}
if (issue.isChanged('comments') || issue.isChanged(ctx.slaTargetField)) {
configureBreach(ctx);
}
},
onBreach: (ctx) => {
const responsiblePerson = ctx.issue.fields.Assignee ? ctx.issue.fields.Assignee : ctx.project.owner;
responsiblePerson.notify(workflow.i18n('First reply is overdue for the ticket {0}', ctx.issue.id),
workflow.i18n('Please pay attention to the {0} high-priority incident pending a reply.', ctx.issue.id), true);
},
requirements: {
Type: {
type: entities.EnumField.fieldType,
name: "Type",
Incident: {
name: 'Incident'
}
},
slaTargetField: {
type: entities.EnumField.fieldType,
name: "Priority",
High: {
name: "High"
}
},
firstReply: {
type: entities.Field.dateTimeType,
name: 'First Reply'
},
Assignee: {
type: entities.User.fieldType,
name: 'Assignee'
}
}
});
function configureBreach(ctx) {
const issue = ctx.issue;
const isAgentComment = function(comment) {
return (comment.author.login !== ctx.issue.reporter.login) && comment.isVisibleTo(ctx.issue.reporter);
};
const hasAgentComments = setToArray(ctx.issue.comments).some(isAgentComment);
if (!hasAgentComments && issue.is(ctx.slaTargetField, ctx.slaTargetField.High)) {
ctx.issue.fields[ctx.firstReply.name] = ctx.issue.afterMinutes(
ctx.issue.created,
REPLY_TIME_IN_MIN,
SLA_CALENDAR,
true
);
} else {
ctx.issue.fields[ctx.firstReply.name] = null;
}
}
function setToArray(set) {
const arr = [];
set.forEach(it => arr.push(it));
return arr;
}
The components that define this SLA rule are as follows:
All scripts start with a list of
require
statements. In this rule, we declare a local variableentities
and reference theentities
module in the workflow API. This means that everything that is contained in this module can be accessed in this script with theentities
variable.Each script exports one rule to the
exports.rule
property. The rule is declared with theIssue.sla
method, which exports the script that follows the declaration as an on-change rule.-
The body of the rule itself contains three properties, as follows:
Property
Description
title
A human-readable title. This title is visible in the list of SLA rules in the helpdesk project settings.
guard
The condition that determines when the SLA rule is applied to a ticket.
note
When deciding which SLA policy to apply to a ticket, YouTrack checks existing policies following the order of the policies in the list in the project settings. If a ticket matches the
guard
condition in a custom SLA rule, but it has already matched another policy, the first matched policy will apply.onEnter
The changes that should be applied to the ticket when the SLA policy starts applying to it.
In this example, YouTrack checks the comments to the ticket and determines whether it has any comments from agents. If the ticket doesn't have any comments from agents and if the SLA goals field is set to the High value, YouTrack sets the value for the First reply field to 3 hours. The implementation for this logic is stored in a separate
configureBreach
function.action
The changes that should be applied to the ticket.
In this example, YouTrack ends the SLA cycle and clears the First reply field if the ticket becomes resolved. YouTrack also recalculates the SLA timer when there is a new comment or an update of the SLA goals field and uses the
configureBreach
function for this.onBreach
The changes that should be applied to the ticket if one of the SLA goals is breached.
In this example, YouTrack sends a notification to the responsible agent if the SLA goal is breached.
requirements
The list of entities that are required for the rule to execute without errors. This property ensures that rules can be attached to projects safely.
In this example, the requirements ensure that the Priority and Type fields store the correct type and have the required values. The requirements also guarantee that there is the Assignee field and a dedicated field for the First reply timer.
For more details about properties of JavaScript SLA rules, see SLA Rule Properties.