---
schema: rendered-html/v1
title: "On-change Rules | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/on-change-rules.html
generated_at: 2026-06-11T15:03:03.885844+00:00
---

Feedback

Thanks for your feedback!

Was this page helpful?

YesNo

Developer Portal for YouTrack and Hub

- Developer Portal
- Apps
- MCP Tools
- YouTrack Workflows
- JavaScript Workflow Quick Start Guide
- Create a Workflow
- Edit a Workflow
- Workflow Rule Types
- [On-change Rules](on-change-rules.html)
- [On-schedule Rules](jetbrains__com__help__youtrack__devportal__on-schedule-rules.md)
- State-machine Rules
- Action Rules
- SLA Rules
- Custom Scripts
- Transactions
- Use Cases for Workflows
- Web-based Workflow Editor
- Using an External Code Editor
- Default Workflows
- Custom Workflow Repository
- JavaScript Workflow Reference
- YouTrack Import Scripts
- YouTrack Form API
- YouTrack REST API
- Hub REST API

1. YouTrack Workflows
2. Workflow Rule Types
3. [On-change Rules](#0)

# On-change Rules﻿

Last modified: 13 May 2026

An on-change rule defines the action that is performed when a change is applied to an issue or an article.

On-change rules don't have any special properties for initial triggers. They run any time a new issue or article is created or when any change is applied to an existing issue or article in the project where the rule is active.

For YouTrack versions 2024.1 and older, only issue-based on-change rules are available. Starting from YouTrack version 2024.2, on-change rules are available for issues and articles.

## Sample On-change Rule﻿

This rule performs the following actions when a change is applied to an issue:

- YouTrack checks for a change to the value in the Subsystem field.
- If the value in the Subsystem changes, the issue is automatically assigned to the owner of the subsystem.

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

exports.rule = entities.Issue.onChange({
  title: 'Set subsystem owner as assignee for unassigned issues',
  guard: (ctx) => {
    return !ctx.issue.fields.Assignee && ctx.issue.fields.Subsystem;
  },
  action: (ctx) => {
    const issue = ctx.issue;
    const fs = issue.fields;
    if ((issue.isReported && (fs.isChanged(ctx.Subsystem) || issue.isChanged('project'))) || issue.becomesReported) {
      if (fs.Subsystem.owner) {
        if (ctx.Assignee.values.has(fs.Subsystem.owner))
          fs.Assignee = fs.Subsystem.owner;
        else
          workflow.message(
              "{0} is set as the owner of the {1} subsystem but isn't included in the list of assignees for issues in this project. " +
              "The workflow that automatically assigns issues to the subsystem owner cannot apply this change.",
              fs.Subsystem.owner.fullName, fs.Subsystem.name);
      }
    }
  },
  requirements: {
    Assignee: {
      type: entities.User.fieldType
    },
    Subsystem: {
      type: entities.OwnedField.fieldType
    }
  }
});
```

> ### warning
>
> Localized Messages
>
> The original workflow script provided by YouTrack uses the `workflow.i18n` function. This is an internal function that is only meant to be used to reference localized message strings. To ensure that you can copy and customize this workflow code, we have removed this function from the sample. If you are editing the default workflow and want to customize any message text, we recommend that you remove these functions from your code as well.
>
> To learn more about localized messages in workflows, see Localized Workflow Messages.

The components that define this on-change 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.onChange` 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 | An optional human-readable title. The title is only visible in the administrative interface. |
  | guard | A function that determines the conditions for executing the rule. If the guard condition is not met, the action specified in the rule is not applied to an issue. |
  | action | The actions that should be applied to each issue. The action is declared as a function that accepts a context as an argument.  In this example, we check to see if the Subsystem field was set to a non-null value that has a non-null owner. If so, the rule sets the value of the Assignee field. |
  | runOn | Determines which issue events trigger the on-change rule. When not specified, rules are triggered on issue update. This property is extended with the following parameters:  - `change` — when `true`, the rule is triggered on issue change. - `removal` — when `true`, the rule is triggered when an issue is deleted. As the rule in this example is triggered when updates are applied, we don't need to specify values for this property.  For a complete sample of an on-change rule that reacts to issue deletion, see Prevent Issue Deletion with Workflows. |
  | 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 both the Subsystem and Assignee fields store the correct types and are available in the project to which the rule is attached. If either field is absent, an error is shown in the Workflows list. The rule cannot be enabled until the required fields are attached. |

For a sample of an on-change rule for articles, see the API reference.

- [On-change Rules](/help/youtrack/devportal/on-change-rules.html)
- [Sample On-change Rule](/help/youtrack/devportal/on-change-rules.html#sample-on-change-rule)

Workflow Rule Types[On-schedule Rules](jetbrains__com__help__youtrack__devportal__on-schedule-rules.md)

- Privacy & Security
- Terms Of Use
- Trademarks
- Legal

Copyright © 2000–2026 JetBrains s.r.o.
