ツイートはてブ LINE Pocket

JavaScript ワークフロークイックスタートガイド

このクイックスタートガイドでは、JavaScript でワークフローの操作を開始するために必要な基本概念について説明します。

ウォームアップをスキップしたい場合は、API に直接飛び込むことができます。
YouTrack でワークフローを使用したことがない場合は、ワークフローリファレンスから始めて、背景情報を確認してください。
JavaScript に慣れていない場合は、代わりにワークフローコンストラクターを試してみてください。プログラミングの知識がなくても、コンストラクターを使用してワークフローを構築できます。

許可

開始する前に、ワークフローを作成および編集する権限があることを確認してください。プロジェクトの更新権限を付与されたユーザーは、独自のワークフローを作成して、プロジェクトにアタッチできます。

ワークフローを作成するためのコントロールは、管理メニューからアクセスできるワークフローページで利用できます。

ワークフローを作成する

ワークフロー自体は単なるコンテナーです。ワークフローを使用して、プロジェクトに適用する一連のルールを収集できます。

特定のビジネスロジックを実施するワークフローを構築するため、開始する前に座ってユースケースを計画することをお勧めします。

このガイドでは、プロジェクトマネージャーの立場になってください。課題をグループ化するために使用するフィールドをプロジェクトに追加したため、進行状況を上司に報告できます。フェーズという名前のフィールドを作成し、値開発、テスト、準備完了を追加しました。基本的に、あなたの上司は、ロードマップと照らし合わせて進捗を測定するために、開発またはテストでまだ抱えている課題の数を確認するだけです。

次に、プロジェクトの課題に適用される他の変更に基づいて、このフィールドの値を設定するワークフローを作成する必要があります。このフィールドの値を自動的に設定したいため、プロジェクトチームは自分で値を設定することを心配する必要はありません。

ワークフローを作成するには:

管理メニューからワークフローを選択します。
新しいワークフローボタンをクリックし、JavaScript エディターオプションを選択します。
- 新しいワークフローダイアログが開きます。
新しいワークフローダイアログで、名前とオプションのタイトルを入力します。ワークフロー名は、npm パッケージの標準の命名規則に従います。詳細については、https://docs.npmjs.com/files/package.json#name(英語) を参照してください。
このガイドでは、名前として phase-management を使用し、タイトルとしてフェーズ管理を使用します。
保存ボタンをクリックしてください。
- ワークフローがリストに追加されます。

ワークフローにモジュールを追加する

これは十分に簡単でしたが、まだ始まったばかりです。これで、スクリプトを保存できるコンテナーができました。さまざまなタイプのルールまたはカスタムスクリプトを含めることができるモジュールで、ワークフローにスクリプトを追加します。

このプロジェクトで自動化する最初のアクションは、チームがタスクを延期して製品バックログに移動することを決定したときに、フェーズフィールドの値をクリアすることです。チームがタスクを延期すると、修正バージョンフィールドの値をバックログに変更します。

このアクションは、変更が課題に適用されたときに実行されるため、変更時ルールを含むワークフローにモジュールを追加する必要があります。

ワークフローにモジュールを追加するには:

リストから空の phase-management ワークフローを選択します。
変更時ボタンをクリックしてください。
- 新規モジュールダイアログが開きます。
clear-phase-when-postponed などのモジュールの名前を入力し、保存ボタンをクリックします。
- 新しいモジュールがワークフローに追加されます。
- モジュール名はリンクとして表示されます。
- 変更時ルールのテンプレートがエディターにロードされます。

最初のルールを書く

これで、最初の単純なルールを作成する準備が整いました。続行する最善の方法は、テンプレートの TODO コメントから次のコメントに移動し、コードを行ごとに更新し、必要に応じて不要なコメントを削除することです。

最初のルールを作成するには:

テンプレートの最初のコメントブロックから開始します。
/** * 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/devportal/Quick-Start-Guide-Workflows-JS.html */
このコメントは、モジュールにコメントブロックを追加する方法を示すだけでなく、このテンプレートで定義されているルールのタイプを示し、このクイックスタートガイドを示します。ここまではすでに説明しており、このタイプのルールが何を行うかは理解しているため、先に進み、ブロック全体を削除してください。
コードの最初の行を参照してください。
const entities = require('@jetbrains/youtrack-scripting-api/entities');
この変数宣言は、ワークフロー API の entities モジュールを参照します。これは、entities モジュールに含まれるすべてのプロパティとメソッドがこのルールでアクセスできることを意味します。
workflow モジュールなど、他のモジュールに属するプロパティとメソッドがある場合は、require ステートメントを追加して、参照するモジュールを次のようにポイントします。
const workflow = require('@jetbrains/youtrack-scripting-api/workflow');
ここで最も重要な点は、ワークフロー API に精通し、ワークフローに必要なプロパティとメソッドがどのモジュールに含まれているかを知る必要があるということです。このルールでは、カスタムフィールドの値のみを更新します。課題とそのカスタムフィールドはすべて entities モジュールからアクセスできるため、テンプレートに組み込まれている require ステートメントを保持できます。
exports.rule プロパティを設定します。
スクリプトは、このプロパティに 1 つのルールのみをエクスポートできます。テンプレートでは、このプロパティは entities.Issue.onChange メソッドで設定されます。このメソッドは、変更が課題に適用されたときにトリガーされるルールを宣言するため、設定はすべて完了です。テンプレートをロードしたときに、このスクリプトが変更時ルールとして処理されることをすでに決定しています。
title プロパティの値を設定します。
変更時ルールの場合、このプロパティはオプションです。モジュール名に使用した値がタイトルにコピーされていることがすでにわかります。タイトルをユーザーフレンドリーにし、他のユーザーがこのルールの機能を認識できるようにする必要があります。この例では、タイトルを Clear Phase when Fix version is set to Backlog に変更します。
タイトルを設定した後、その前の行の TODO を削除します。
guard 条件を書く
これは、実際にコーディングを開始する場所です。guard プロパティを使用して、ルールを適用するために満たす必要がある条件を定義します。
テンプレートはすでに引数としてコンテキストを受け入れる関数としてガードを宣言しています:
guard: (ctx) => {
これは、guard プロパティに定義されたコードが関数として扱われることを意味します。後続のアクションを実行するには、この関数は true と評価される値を返す必要があります。
ユーザーが修正バージョンフィールドの値をバックログに変更した場合にのみ、このルールにアクションを適用する必要があります。この変更が課題に適用されると、次のガードは true を返します。
return ctx.issue.fields.becomes(ctx.FixVersion, ctx.FixVersion.Backlog);
このコードをテンプレートのガード条件に貼り付けてから、ガードプロパティ内の TODO ブロックを削除できます。
action を設定します。
action プロパティを使用して、ガード条件が満たされたときに適用される変更を定義します。
テンプレートは、アクションを引数としてコンテキストを受け入れる関数としてすでに宣言していることがわかります。
action: (ctx) => {
次に、ローカル変数 issue を宣言し、コンテキスト内の課題を参照する値を設定します。
const issue = ctx.issue;
または
let issue = ctx.issue;
複数の課題プロパティを更新する複雑なルールには変数宣言を使用する必要がありますが、ルールがこれほど単純な場合は必要ありません。ガード条件が満たされたときに適用するアクションを指定するだけで、フェーズフィールドの値をクリアできます。
ctx.issue.fields.Phase = null;
このコードブロックをコピーし、不要な変数宣言の上に貼り付けて、次の TODO を削除できます。
テンプレートは、関数の本体を右中括弧で閉じ、このブロックを次のプロパティからコンマ（},）で区切ります。
requirements を追加します。
requirements プロパティには、このルールが適切に実行されるために必要なコンポーネントがリストされます。これには、カスタムフィールド、課題リンクタイプ、プロジェクト、保存された検索などの定義が含まれます。要件の詳細については、「要件」を参照してください。
ルールでは、2 つのカスタムフィールド修正バージョンおよびフェーズの要件を定義する必要があります。
最初に、修正バージョンフィールドが ProjectVersion タイプとしてデータを保管することを定義してから、フィールドが値のセットに Backlog を含める必要があることを指定します。
FixVersion: { type: entities.ProjectVersion.fieldType, name: "Fix version", Backlog: {} },
まず、FixVersion はカスタムフィールドの実際の名前ではないことがわかります。これはエイリアスです。スペースやその他のアルファベット以外の文字を含むカスタム名にはエイリアスを使用します。これらの値を引用符や括弧で設定する必要がなくなるためです。カスタムフィールドの実際の名前は、name プロパティで指定されます。FixVersion の最終プロパティは、カスタムフィールドに値 Backlog を含める必要があることを指定します。
次に、フェーズフィールドの要件を設定します。
Phase: { type: entities.EnumField.fieldType, }
ここで必要なことは、フィールドが存在し、EnumField を保存することだけです。ルールにより値が null に設定されるため、このフィールドに値を要求する必要はありません。
これらのコードブロックをコピーして、最後の TODO コメントの上に貼り付けます。
保存ボタンをクリックして、変更を保存します。
ワークフローエディターでその他のアクションメニューを開き、コードの整形を選択します。完成したワークフローは次のようになります。
const entities = require('@jetbrains/youtrack-scripting-api/entities'); exports.rule = entities.Issue.onChange({ title: 'Clear Phase when Fix version is set to Backlog', guard: (ctx) => { return ctx.issue.fields.becomes(ctx.FixVersion, ctx.FixVersion.Backlog); }, action: (ctx) => { ctx.issue.fields.Phase = null; }, requirements: { FixVersion: { type: entities.ProjectVersion.fieldType, name: "Fix version", Backlog: {} }, Phase: { type: entities.EnumField.fieldType } } });

その後、別の書き込み !

それは十分に簡単でした。もう一度やってみましょう。最初のルールから学んだことを思い出して、ワークフローに 2 番目のモジュールを追加します。

自動化する次のアクションは、状態フィールドに変更が適用されたときにフェーズフィールドの値を設定することです。このアクションは、変更が課題に適用されたときにも発生するため、別の変更時ルールを追加する必要があります。

別のモジュールを追加して 2 番目のルールを定義するには:

phase-management ワークフローのサイドバーで、モジュールの追加アイコンをクリックして変更時を選択します。
新規モジュールダイアログで、sync-phase-with-state を入力し、保存ボタンをクリックします。
- 新しい変更時ルールのテンプレートがエディターにロードされます。
コメントブロックを削除します。
entities 変数の require 宣言はそのままにしておきます。
exports.rule プロパティの定義もそのままにしておきます。
title プロパティの値を Set value for Phase when State changes に設定し、それに先行する TODO を削除します。
guard プロパティの定義を追加して、次の TODO を置き換えます。次のガードは、ユーザーが状態フィールドの値を変更すると、true を返します。
guard: (ctx) => { return ctx.issue.fields.isChanged(ctx.State); },
action プロパティを設定します。
今回は、変数宣言を保持します。これにより、明示的な参照 entities.issue を使用せずに、コンテキスト内で entities モジュール内の issue オブジェクトのプロパティとメソッドを参照することができます。コンテキストの詳細については、「コンテキスト」を参照してください。
ただし、このルールはカスタムフィールドを更新するだけでよいため、fields オブジェクトを参照するようにコンテキスト変数宣言を変更できます。
const issueFields = ctx.issue.fields;
次に、ちょっとしたトリックを行います。このルールでは、ユーザーが状態フィールドを更新するときにフェーズフィールドの値を変更します。更新ごとにフェーズを個別に設定する必要がありますが、関数を 1 回宣言できます。この関数を action 関数の本体に挿入するだけです:
function setPhase(phase) { if ((ctx.issue.fields.Phase || {}).name !== phase.name) { ctx.issue.fields.Phase = phase; } }
これで、フェーズフィールドに値を割り当てるために使用できる setPhase という名前の関数ができました。
次に、フェーズフィールドの値を変更するための条件を記述します。条件とアクションを一連の if として構成します。
- 状態が Fixed に変更された場合、フェーズをテストに設定します。
- 状態が進行中または Reopened に変わる場合、フェーズを開発に設定します。
- 状態が Verified に変わる場合、フェーズを準備完了に設定します。
一連の制御フローステートメントに条件とアクションを入力します。上記の条件を比較して、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); }
このルールの requirements を追加します。
このルールでは、2 つのカスタムフィールド ( 状態およびフェーズ ) の要件を定義する必要があります。
最初に、状態フィールドが state タイプとしてデータを保管することを定義してから、このフィールドの値のセットに含める必要がある値を指定します。
State: { type: entities.State.fieldType, InProgress: { name: "In Progress" }, Fixed: {}, Verified: {}, Reopened: {} },
次に、このフィールドが enum タイプとしてデータを保管することを除いて、フェーズフィールドに対して同じことを行います。
Phase: { type: entities.EnumField.fieldType, Development: {}, Testing: {}, Ready: {} }
これらのコードブロックを最後の TODO コメントに貼り付けます。
保存ボタンをクリックしてください。
ワークフローエディターでその他のアクションメニューを開き、コードの整形を選択します。完成したワークフローは次のようになります。
const entities = require('@jetbrains/youtrack-scripting-api/entities'); exports.rule = entities.Issue.onChange({ title: 'Set value for Phase when State changes', guard: (ctx) => { return ctx.issue.fields.isChanged(ctx.State); }, action: (ctx) => { const 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: {} } } });

それでは、次は？

有効なワークフローが YouTrack に保存されたため、いくつかのオプションがあります。学ぶこととすることはまだたくさんあります。

このリストを使用して、次の登る丘または征服する山を見つけます。

ワークフローを機能させる !	ビジネスロジックを適用するには、1 つ以上のプロジェクトにワークフローをアタッチする必要があります。詳細については、プロジェクトへのワークフローのアタッチを参照してください。
ルールを知る	このガイドでは、1 つのルールタイプを導入しましたが、他のルールを学習して習得する必要があります。コマンドで設定されたスケジュールまたはオンデマンドで課題を更新し、カスタムフィールドの値間の遷移を管理します。詳細については、ワークフロールールタイプを参照してください。
可能性を探る	ワークフローの機能がわからない場合、ワークフローのすべての力を解き放つことはできません。想像力をかきたてる一般的なユースケースを集めました。詳細については、ワークフローのユースケースを参照してください。
外観	YouTrack ですでに利用可能で、有効に使用されるのを待っている多くのデフォルトワークフローがあります。多くのデフォルトワークフローはプロジェクトに自動的に関連付けられますが、ほとんどはオプションです。デフォルトのワークフローのリストを調べて、プロジェクトで使用する自動化があるかどうかを確認するか、ビジネスロジックに合わせて調整します。詳細については、デフォルトのワークフローを参照してください。
より深く掘る	まだ表層に触れただけです。ワークフロー API と、JavaScript でそのプロパティとメソッドを参照する方法について理解するほど、プロジェクトをより適切にカスタマイズできます。詳細については、JavaScript ワークフローリファレンスを参照してください。
統合	ワークフロー API の REST クライアント実装により、お気に入りのツールとプッシュスタイルの統合をスクリプト化できます。詳細については、JavaScript ワークフローでの REST API メソッドの使用を参照してください。
プロになる	WebStorm などの JavaScript をサポートする IDE でこのルールを編集用にエクスポートできます。エクスポートオプションは、運用環境にインポートする前に、テスト環境でワークフローを記述およびテストするのにも役立ちます。外部エディターで作成されたスクリプトをインポートすることもできます。詳細については、インポートおよびエクスポートのワークフローを参照してください。