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.

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.

            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 variable entities and reference the entities module in the workflow API. This means that everything that is contained in this module can be accessed in this script with the entities variable.
Each script exports one rule to the exports.rule property. The rule is declared with the Issue.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. 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.

Last modified: 7 November 2024