---
schema: rendered-html/v1
title: "Automate Work Handoffs | Developer Portal for YouTrack and Hub Documentation"
source_url: https://www.jetbrains.com/help/youtrack/devportal/automate-work-handoffs.html
generated_at: 2026-06-11T15:02:09.178113+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
- Transactions
- Use Cases for Workflows
- Restrict Issue Visibility with Workflows
- Prevent Unwanted Updates
- Prevent Issue Deletion with Workflows
- Streamline Issue Reporting
- [Automate Work Handoffs](automate-work-handoffs.html)
- Generate Issues Automatically
- Update Fields on Issue Update
- Propagate Values Between Issues
- Track Spent Time
- Generate Time Reports
- Enhance Helpdesk Support
- Send Internal Newsletters
- Deactivate Voting for Issues
- 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. Use Cases for Workflows
3. [Automate Work Handoffs](#0)

# Automate Work Handoffs﻿

Last modified: 13 May 2026

You can use workflows to support a team process where each issue moves through a fixed sequence of states. This lets your team use issue states as a queue and as a record of who is responsible for the next step.

Suppose your team is setting up a process for handling user requests. This process is reflected in the columns of the agile board that is used by the development team.

[![Workflow agile statemachine](https://crawler.prototype.prolicht.digital/l/KoOA1W)](https://resources.jetbrains.com/help/img/youtrack/workflow-agile-statemachine.png)

For example, suppose your team uses the following process:

- New issues are assigned the Submitted state.
- The team decides that the issue has to be addressed and changes the state to Open. Issues in this state are added to the work queue.
- When developers have time to work on an issue, they assign it to themselves. The workflow then moves the issue to the In Progress state.
- After the problem is fixed, the developer changes the state to Fixed. The workflow assigns the issue to a QA engineer.
- When the tests are passed, the QA engineer sets the state to Verified.

This process can be implemented with two workflow rules. A state-machine rule enforces the order of state transitions, while an on-change rule moves open issues to In Progress when a developer assigns an issue to themselves.

## Define the State Transitions﻿

The first rule defines the allowed transitions for the State field. It also assigns the issue to the configured QA engineer when a developer moves the issue to Fixed.

Before you use this sample, replace `qa.engineer` with the login of the QA engineer who should verify fixed issues. This user must be available in the set of values for the Assignee field in every project that uses the workflow.

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

const getQAEngineer = (ctx) => {
  const assigneeField = ctx.issue.project.findFieldByName(ctx.Assignee.name);
  return assigneeField && assigneeField.findValueByLogin(ctx.QAEngineer.login);
};

const assignToQAEngineer = (ctx) => {
  const qaEngineer = getQAEngineer(ctx);
  workflow.check(qaEngineer,
      'Add the QA engineer to the set of values for the Assignee field.');
  ctx.issue.fields.Assignee = qaEngineer;
};

const currentUserIsQAEngineer = (ctx) => {
  const isQAEngineer = ctx.currentUser.login === ctx.QAEngineer.login;
  if (!isQAEngineer) {
    workflow.message('Only the QA engineer can complete this transition.');
  }
  return isQAEngineer;
};

exports.rule = entities.Issue.stateMachine({
  title: 'Manage work handoffs by state',
  fieldName: 'State',
  states: {
    Submitted: {
      initial: true,
      transitions: {
        open: {
          targetState: 'Open'
        }
      }
    },
    Open: {
      transitions: {
        start: {
          targetState: 'In Progress'
        }
      }
    },
    'In Progress': {
      onEnter: (ctx) => {
        if (!ctx.issue.fields.Assignee) {
          ctx.issue.fields.Assignee = ctx.currentUser;
        }
      },
      transitions: {
        fix: {
          targetState: 'Fixed'
        },
        reopen: {
          targetState: 'Open'
        }
      }
    },
    Fixed: {
      onEnter: assignToQAEngineer,
      transitions: {
        verify: {
          targetState: 'Verified',
          guard: currentUserIsQAEngineer
        },
        reopen: {
          targetState: 'Open',
          guard: currentUserIsQAEngineer
        }
      }
    },
    Verified: {
      transitions: {
        reopen: {
          targetState: 'Open'
        }
      }
    }
  },
  requirements: {
    Assignee: {
      type: entities.User.fieldType
    },
    QAEngineer: {
      type: entities.User,
      login: 'qa.engineer'
    }
  }
});
```

## Start Work on Assignment﻿

The second rule supports a pull-based queue. When an issue is Open and a developer assigns it to themselves, the rule moves the issue to In Progress.

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

exports.rule = entities.Issue.onChange({
  title: 'Start work when a developer assigns an open issue to themselves',
  guard: (ctx) => {
    const issue = ctx.issue;
    return issue.isReported &&
        issue.fields.is(ctx.State, ctx.State.Open) &&
        issue.fields.isChanged(ctx.Assignee) &&
        issue.fields.Assignee &&
        issue.fields.Assignee.login === ctx.currentUser.login;
  },
  action: (ctx) => {
    ctx.issue.fields.State = ctx.State.InProgress;
  },
  requirements: {
    State: {
      type: entities.State.fieldType,
      Open: {},
      InProgress: {
        name: 'In Progress'
      }
    },
    Assignee: {
      type: entities.User.fieldType
    }
  }
});
```

- [Automate Work Handoffs](/help/youtrack/devportal/automate-work-handoffs.html)
- [Define the State Transitions](/help/youtrack/devportal/automate-work-handoffs.html#define-state-transitions)
- [Start Work on Assignment](/help/youtrack/devportal/automate-work-handoffs.html#start-work-on-assignment)

Streamline Issue ReportingGenerate Issues Automatically

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

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