ワークフロー API を使用する

このページの情報を使用して、ワークフローリファレンスの他のセクションで説明されていないワークフロー API の特定のエンティティを操作する方法を学習します。

ワークフロースクリプトの記述場所

ワークフロースクリプトは、ワークフローに属する JavaScript モジュールです。YouTrack 内で作成および編集することも、外部の開発環境で管理することもできます。

YouTrack でワークフローを作成し、モジュールを追加するには、Web ベースのワークフローエディターを使用します。ガイド付きの例については、JavaScript ワークフロークイックスタートガイドを参照してください。
IDE でワークフローを作成するには、ワークフロースクリプトパッケージをインストールし、ワークフローを YouTrack にアップロードしてください。セットアップ手順については、外部コードエディターの使用を参照してください。

各モジュールは、1 つのワークフロールールまたは再利用可能なカスタムスクリプトを定義します。コードを実行するタイミング（たとえば、課題が変更されたとき、スケジュールに基づいて実行したとき、ユーザーがアクションを実行したときなど）に合わせて、モジュールタイプを選択してください。

プロパティ、カスタムフィールド、課題リンクへのアクセス

これらのガイドラインに従って、課題のプロパティ、カスタムフィールドの値、課題のリンクにアクセスします。

事前定義された課題フィールド

summary、description、reporter のような事前定義された課題フィールドは、すべて issue エンティティのプロパティです。

            const summary = issue.summary;
            issue.summary = "Just a bug";
        

カスタムフィールド値

カスタムフィールドの値への参照は、フィールドが単一の値を保存するか複数の値を保存するかによって異なります。

単一の値を格納するフィールドの場合、値を直接参照できます。
const state = issue.fields.State; if (state && issue.fields.is(ctx.State, ctx.State.Fixed)) { // Do stuff } issue.fields.State = ctx.State.Open;
複数の値を格納するフィールドの場合、値はセットとして格納されます。セットで使用できる操作については、次のセクションで詳しく説明します。
const versions = issue.fields["Fix versions"]; versions.forEach(function (v) { subtask.fields["Fix versions"].add(v); });

フィールド定義自体をインスペクションする必要がある場合は、プロジェクトから ProjectCustomField を取得し、その typeName を読み取ってください。複数値のカスタムフィールド型は、user[*] や version[*] などの [*] 接尾辞を使用します。単一値のバンドル、ユーザー、グループフィールド型は [1] を使用します。integer や string などのスカラーフィールド型は、カーディナリティ接尾辞を使用しません。

            const assigneeField = issue.project.findFieldByName('Assignee');
            if (assigneeField && assigneeField.typeName.endsWith('[*]')) {
                // Assignee stores multiple users in this project.
            }
        

この実行時プロパティは、ルール要件の multi プロパティとは異なります。ルールでフィールドに複数の値を格納する必要がある場合は multi: true を使用し、ルールで既存のフィールドをインスペクションする必要がある場合は typeName を使用してください。

Workflow API エンティティで表されるカスタムフィールド値を比較する場合は、表示名やオブジェクト参照を比較するのではなく、API ヘルパーメソッドを使用してください。issue.fields.is(ctx.Field, ctx.Field.Value) メソッドは現在の値をチェックし、issue.fields.was(ctx.Field, ctx.Field.Value) メソッドは前の値をチェックします。issue.fields.becomes(ctx.Field, ctx.Field.Value) メソッドは、現在のトランザクションでフィールドが変更され、その新しい値が期待値と一致する場合にのみ true を返します。

エイリアス

requirements ステートメントでカスタムフィールドに alias プロパティを設定した場合、このエイリアスを使用してフィールドの値にもアクセスできます。例: 修正バージョンフィールドのエイリアスが FV に設定されている場合:

            issue.fields.FV.forEach(function (v) {
                // Do stuff
            });
        

課題リンク

課題リンクタイプには、内部または外部の名前でアクセスします。例: relates to または parent for 課題リンクは常にセットとして扱われます。

            const parent = issue.links["subtask of"].first();
            parent.links["parent for"].add(issue);
        

スペースまたは他のアルファベット以外の文字を含むカスタムフィールドと課題リンクタイプは、引用符と括弧で設定する必要があることに注意してください。

セットオブジェクトの使用

複数の値（Set <value type> として返される）で実行できる操作のグループがいくつかあります。

それらに直接（first()、last()、get(index)）またはイテレータ（entries()、values()）でアクセスします。
Set のすべての値を forEach(visitor) でトラバースします。
find(predicate) で値を探し、値が has(value) で設定されているかどうかを確認します。
isEmpty()、isNotEmpty()、size プロパティでサイズを確認してください。
add(element)、delete(element)、clear() でコンテンツを変更します。
added、deleted、isChanged プロパティを使用して設定オブジェクトの現在の変更を取得します。

このオブジェクトの詳細な説明については、設定を参照してください。

メソッドの呼び出し

        // Call entity method:
        const stateCF = issue.project.findFieldByName('State');
        // Call static method:
        const p = entities.Project.findByKey('INT');
        // Call issue constructor:
        const newIssue = new entities.Issue(ctx.currentUser, issue.project, "Subtask");
    

特定のエンティティを見つける

課題やユーザーなどの特定のエンティティを見つけて、ワークフロースクリプトで使用するには、次の 2 つの方法があります。

要件に追加し、コンテキストで参照します。このアプローチは最も信頼性が高いため、できるだけ頻繁に使用してください。指定されたエンティティがデータベースに見つからない場合、スクリプトは実行されません。
最初のオプションが何らかの理由で適用できない場合、ワークフロー API から findBy* および find*By* メソッドを使用します。

findBy* メソッドを使用して、特定のエンティティの単一出現箇所を検索します。

        const issue = entities.Issue.findById('MP-23'); // an entities.Issue or null
        const projectByName = entities.Project.findByName('Music Production'); // an entities.Project or null
        const projectByKey = entities.Project.findByKey('MP'); // an entities.Project or null
        const user = entities.User.findByLogin('jane.smith'); // an entities.User or null
        const userGroup = entities.UserGroup.findByName('MP team'); // an entities.UserGroup or null
        const agiles = entities.Agile.findByName('MP Scrum'); // a Set of entities.Agile
        const tags = entities.IssueTag.findByName('production'); // a Set of entities.IssueTag
        const queries = entities.SavedQuery.findByName('MP Backlog'); // a Set of entities.SavedQuery
    

find*By* メソッドを使用して、子エンティティを検索します。

        const sprint = agiles.first().findSprintByName('Sprint 23'); // an entities.Sprint or null
        const priorityField = projectByKey.findFieldByName('Priority'); // an entities.ProjectCustomField or null
        const major = field.findValueByName('Major'); // an entities.Field or null
        const critical = field.findValueByOrdinal(1); // an entities.Field or null
        const assigneeField = projectByKey.findFieldByName('Assignee');
        const jane = assigneeField.findValueByLogin('jane.smith'); // an entities.User or null
        const groupField = projectByKey.findFieldByName('Requestors');
        const newBand = groupField.findValueByName('New Band'); // an entities.UserGroup or null
    

複数の課題を見つける

場合によっては、特定の基準に一致する一連の課題を検索し、1 つのルールの範囲内で処理したい場合があります。例: 課題のリストを作成し、メールメッセージとして送信できます。このような状況では、検索 API が役に立ちます。簡単な例を次に示します。

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

        exports.rule = entities.Issue.onChange({
          title: 'Do not allow developers to have more than 1 issue in progress per project',
          action: (ctx) => {
            const issue = ctx.issue;
            if (issue.isReported &&
                (issue.fields.becomes(ctx.State, ctx.State['In Progress']) ||
                    issue.fields.isChanged(ctx.Assignee)) &&
                (issue.fields.Assignee || {}).login === ctx.currentUser.login) {
              // First, we build a search query that checks the project that the issue belongs to and returns all the issues
              // that are assigned to current user except for this issue.
              const query = 'for: me State: {In Progress} issue id: -' + issue.id;
              const inProgress = search.search(issue.project, query, ctx.currentUser);
              // If any issues are found, we get the first one and warn the user.
              if (inProgress.isNotEmpty()) {
                const otherIssue = inProgress.first();
                const message = 'Dear ' + ctx.currentUser.login + ', please close <a href="' +
                    otherIssue.url + '">' + otherIssue.id + '</a> first!';
                workflow.check(false, message);
              }
            }
          },
          requirements: {
            State: {
              type: entities.State.fieldType,
              'In Progress': {}
            },
            Assignee: {
              type: entities.User.fieldType
            }
          }
        });
    

ワークフロースクリプトのデバッグ

ワークフロールールの実行中に値をインスペクションするには、スクリプトにログ記録ステートメントを追加します。

        console.log('Processing issue ' + ctx.issue.id);
        console.warn('Expected value was not found');
        console.error('External request failed');
    

ワークフロースクリプトメッセージは、ブラウザーの開発者コンソールではなく、ワークフローエディターのコンソールペインに表示されます。YouTrack サーバーのインストールの場合、これらのメッセージは workflow.log ファイルにも書き込まれます。

コンソールの詳細については、コンソールツールバーを参照してください。追加の診断ガイダンスについては、ワークフローのトラブルシューティングを参照してください。

2026 年 8 月 12 日