JavaScript Workflow Quick Start Guide

From the Core Features section of the Administration menu, select Workflows.

• The New Workflow dialog opens.

For this guide, use phase-management as the name and Phase Management as the title.

• Your new workflow is added to the list.

Locate the new workflow in the list.

• The workflow opens in the workflow editor.

• The New Module panel opens in the editor window.

• Now, you can add a rule to the workflow using a template.

• The New Module dialog opens.

• The new module is added to the workflow.

• The module name is displayed as a link.

• The template for an on-change rule loads in the editor.

/**
* This is a template for an on-change rule. This rule defines what
* happens when a change is applied to an issue.
*
* For details, read the Quick Start Guide:
* https://www.jetbrains.com/help/youtrack/standalone/2017.4/Quick-Start-Guide-Workflows-JS.html
*/

Aside from showing you how to add comment blocks to your modules, this comment tells you what type of rule is defined in this template and points you to this quick start guide. Since you're already here and you know what this type of rule does, go ahead and delete the whole block.

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

This variable declaration references the entities module in the workflow API. This means that all of the properties and methods that are contained in the entities module can be accessed in this rule.

If there are properties and methods that belong to other modules, for example, the workflow module, just add a require statement and point to the module you want to reference, like this:

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

The most important point here is that you need to be familiar with the workflow API and know which modules contain the properties and methods that you need for your workflows. For this rule, you only want to update the value in a custom field. Issues and their custom fields are all accessible from the entities module, so you can keep the require statement that is built into the template.

A script can export exactly one rule to this property. In the template, this property is set with the entities.Issue.onChange method. This method declares a rule that is triggered when a change is applied to an issue, so you're all set. You already determined that this script will be handled as an on-change rule when you loaded the template.

For an on-change rule, this property is optional. You can already see that the value you used for the module name has been copied to the title. You want the title to be user friendly and help other users recognize what this rule does. For this example, change the title to Clear Phase when Fix version is set to Backlog.

After you set the title, remove the TODO on the line that precedes it.

This is where you actually start to code. With the guard property, you define the conditions that must be met for the rule to be applied.

The template has already declared the guard as a function that accepts a context as an argument:

guard: function(ctx) {

This simply means that the all of the code that is defined for the guard property is treated as a function. For the action that follows to be executed, this function must return a value that evaluates to true.

You want this rule to apply an action only when a user changes the value of the Fix version field to Backlog. The following guard returns true when this change is applied to an issue:

return ctx.issue.fields.becomes(ctx.FixVersion, ctx.FixVersion.Backlog);

You can paste this guard over the TODO inside the guard property.

With the action property, you define the changes that are applied when the guard condition is met.

You can see that the template has already declared the action as a function that accepts a context as an argument:

action: function(ctx) {

It then declares a local variable issue and sets the value to reference an issue in context:

var issue = ctx.issue;

You'll want to use a variable declaration for complex rules that update multiple issue properties, but for a rule this simple, you don't need it. All you need to do is specify the action that you want to apply when the guard condition is met, which is to clear the value in the Phase field:

ctx.issue.fields.Phase = null;

You can copy this block of code and paste it on top of the unnecessary variable declaration and remove the next TODO.

You'll notice that the template closes the body of the function with a right brace and separates this block from the next property with a comma(},).

The requirements property lists all of the components that this rule needs to run properly. This includes definitions for custom fields, issue link types, projects, saved searches, and so on. To learn more about requirements, see Requirements.

For your rule, you need to define the requirements for two custom fields: Fix version and Phase.

First, define that the Fix version field stores data as a ProjectVersion type, then specify that the field must include Backlog in the set of values.

FixVersion: {
  type: entities.ProjectVersion.fieldType,
  name: "Fix version",
  Backlog: {}
},

First, you'll notice that FixVersion is not the actual name of the custom field. This is an alias. Use an alias for custom names that contain spaces and other non-alpha characters, as it saves you from having to set these values in quotes and brackets. The actual name of the custom field is specified in the name property. The final property for the FixVersion specifies that the custom field must contain the value Backlog.

Then, set the requirements for the Phase field.

Phase: {
  type: entities.EnumField.fieldType,
}

Here, all you need to do is require that the field exists and stores an EnumField. You don't need to require any values for this field, as the rule sets the value to null.

Copy these blocks of code and paste them on top of the last TODO comment.

Click the Save button to store your changes.

Open the More actions menu in the workflow editor and select Reformat code. Your finished workflow should look like this:

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

exports.rule = entities.Issue.onChange({
  title: 'Clear Phase when Fix version is set to Backlog',
  guard: function(ctx) {
    return ctx.issue.fields.becomes(ctx.FixVersion, ctx.FixVersion.Backlog);
  },
  action: function(ctx) {
    ctx.issue.fields.Phase = null;
  },
  requirements: {
    FixVersion: {
      type: entities.ProjectVersion.fieldType,
      name: "Fix version",
      Backlog: {}
    },
    Phase: {
      type: entities.EnumField.fieldType
    }
  }
});

In the sidebar for your phase-management workflow, click the Add module icon and select On-change.

• The template for a new on-change rule loads in the editor.

Delete the comment block.

Leave the require declaration for the entities variable as is.

Leave definition for the exports.rule property alone as well.

Set the value for the title property to Set value for Phase when State changes and remove the TODO that precedes it.

Replace the next TODO with a definition for the guard property. The following guard returns true when a user changes the value of the State field:

guard: function(ctx) {
  return ctx.issue.fields.isChanged(ctx.State);
},

This time around, you'll keep the variable declaration. This helps you reference all of the properties and methods for the issue object in the entities module in context without having to use the explicit reference entities.issue. To learn more about context, see Context.

However, because this rule only needs to update a custom field, you can change the context variable declaration to reference the fields object:

var issueFields = ctx.issue.fields;

Next, you'll do a little trick. For this rule, you want to change the value in the Phase field when a user updates the State field. You're going to have to set the phase separately for each update, but you can declare the function once. Just insert this function into the body of the action function:

function setPhase(phase) {
  if ((ctx.issue.fields.Phase || {}).name !== phase.name) {
    ctx.issue.fields.Phase = phase;
  }
}

You can copy this block of code and paste it on top of the next TODO.

You now have a function named setPhase that you can use to assign a value to the Phase field.

Now write the conditions for changing the value of the Phase field. Frame the conditions and actions as a series of 'if's:

• If the State changes to Fixed, set the Phase to Testing.

• If the State changes to In Progress or Reopened, set the Phase to Development.

• If the State changes to Verified, set the Phase to Ready.

Enter the conditions and actions in a series of control flow statements. Compare the conditions that are listed above to see how they are translated into JavaScript:

if (issueFields.becomes(ctx.State, ctx.State.Fixed)) {
  setPhase(ctx.Phase.Testing);
} else if (issueFields.becomes(ctx.State, ctx.State.InProgress) ||
  issueFields.becomes(ctx.State, ctx.State.Reopened)) {
  setPhase(ctx.Phase.Development);
} else if (issueFields.becomes(ctx.State, ctx.State.Verified)) {
  setPhase(ctx.Phase.Ready);
}

For this rule, you need do define the requirements for two custom fields: State and Phase.

First, define that the State field stores data as a state type, then specify which values must be included in the set of values for this field.

State: {
  type: entities.State.fieldType,
  InProgress: {
    name: "In Progress"
  },
  Fixed: {},
  Verified: {},
  Reopened: {}
},

Then do the same for the Phase field, except that this field stores data as an enum type.

Phase: {
    type: entities.EnumField.fieldType,
    Development: {},
    Testing: {},
    Ready: {}
}

Paste these blocks of code over the last TODO comment.

Click the Save button.

Open the More actions menu in the workflow editor and select Reformat code. Your finished workflow should look like this:

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

exports.rule = entities.Issue.onChange({
  title: 'Set value for Phase when State changes',
  guard: function(ctx) {
    return ctx.issue.fields.isChanged(ctx.State);
  },
  action: function(ctx) {
    var issueFields = ctx.issue.fields;

    function setPhase(phase) {
      if ((ctx.issue.fields.Phase || {}).name !== phase.name) {
        ctx.issue.fields.Phase = phase;
      }
    }

    if (issueFields.becomes(ctx.State, ctx.State.Fixed)) {
      setPhase(ctx.Phase.Testing);
    } else if (issueFields.becomes(ctx.State, ctx.State.InProgress) ||
      issueFields.becomes(ctx.State, ctx.State.Reopened)) {
    setPhase(ctx.Phase.Development);
    } else if (issueFields.becomes(ctx.State, ctx.State.Verified)) {
      setPhase(ctx.Phase.Ready);
    }
  },
  requirements: {
    State: {
      type: entities.State.fieldType,
      InProgress: {
        name: "In Progress"
      },
      Fixed: {},
      Verified: {},
      Reopened: {}
    },
    Phase: {
      type: entities.EnumField.fieldType,
      Development: {},
      Testing: {},
      Ready: {}
    }
  }
});