ステートマシンルール

ステートマシンルールのサンプル

これは、状態カスタムフィールドの値間の可能な遷移を定義するステートマシンルールです。

オープン状態が初期として設定されます。これは、すべての新しい課題がこの状態で作成されることを意味します。

このステートマシンルールが定義する遷移のリストは次のとおりです。

このルールがアクティブな場合、定義された遷移のみに従って、課題の状態カスタムフィールドの値を変更できます。ある状態値から別の状態値への特定の遷移がルールで定義されていない場合、この状態からターゲットの状態に直接課題を移動することはできません。未定義の状態遷移は、手動での課題の更新、コマンドの使用、自動化を含むすべてのレベルで禁止されています。

ステートマシンエディターでの作業方法とステートマシンルールの作成方法の詳細については、状態マシンを参照してください。

基本的なステートマシンルール

基本的なステートマシンルールは、ワークフローを使用するプロジェクトのすべての課題について、カスタムフィールドのある値から別の値への遷移を規制します。遷移ごとに、1 つ以上のアクションを追加できます。各遷移の追加のプロパティは、これらのアクションがどのように適用されるかを決定します。

• onEnter および onExit プロパティを使用する遷移は、フィールドの値が設定されたときにアクションを実行します。これらのアクションは、フィールドの値を変更したユーザーによって実行されます。

• after プロパティを使用する遷移は、指定された時間枠の後にアクションを実行します。これらのアクションは、ワークフローのユーザーアカウントによって実行されます。

以下の例は、単純化されたステートマシン規則を示しています。この規則は、状態フィールドに許可される遷移を定義します。

この規則では、次の遷移が定義されています。

• 初期のオープン状態から、値は進行中に変更できます。reminder という名前の追加の遷移には、課題が 2 日以上オープン状態のままである場合にプロジェクト所有者に通知する after プロパティが含まれています。

• 課題がオープンから進行中に移行すると、In progress 状態の onEnter プロパティは、状態フィールドの値を変更するユーザーに課題を自動的に割り当てます。

• 実行中から、値は Fixed またはオープンに変更できます。課題が進行中からオープンに移行すると、この移行の自動化によってユーザーに課題の割り当てを解除するよう求められます。それ以外の場合、遷移はブロックされます。

• 最終的な状態は修正済みです。この値に対して定義されている追加の遷移はありません。一度設定した値は変更できません。

次のダイアグラムは、この規則の抽象表現を示しています。

このステートマシンをサポートするワークフロールールは、次のように記述されています。

このステートマシン規則を定義するコンポーネントは次のとおりです。

• require ステートメントは、ワークフロー API の entities モジュールと workflow モジュールを参照します。

• exports.TWO_DAYS プロパティは、オープンステータスの課題のリマインダーを送信するために使用されるローカル変数を設定します。この変数には、ミリ秒単位で 2 日に等しい値が割り当てられます。

• exports.rule プロパティは、Issue.stateMachine メソッドを使用して、宣言に続くスクリプトをステートマシン規則としてエクスポートします。

• ルール本体には、次のプロパティの定義が含まれています。

  プロパティ	説明
  タイトル	人間が読めるオプションのタイトル。
  フィールド名	ステートマシンルールによって管理されるカスタムフィールドの名前。
  状態	フィールド値のリストとそれらの間の遷移の定義。スペースと特殊文字を含む値は一重引用符で囲みます。
  要件	ルールがエラーなしで実行されるために必要なエンティティのリスト。このプロパティにより、ルールをプロジェクトに安全にアタッチできるようになります。 この例では、ルールが関連付けられているプロジェクトに user タイプを格納する担当者フィールドがあることだけが必要です。このフィールドがないと、ワークフローリストにエラーが表示されます。必須フィールドがアタッチされるまで、ルールを有効にすることはできません。 ステートマシンルールの場合、ステートマシンによって管理されるフィールドを要件に追加する必要はありません。このフィールドとその値は、states プロパティから取得されます。

• states プロパティで定義されている各値には、次の追加プロパティの定義が含まれています。

  プロパティ	説明
  初期	アーティファクトの作成時にリスト内のどの値を設定するかを決定するブール型プロパティ。厳密に 1 つの値でこのプロパティを true に設定する必要があります。初期値として設定されていない他の値の場合、このプロパティはオプションであり、省略することができます。
  onEnter	対応する値が issue に割り当てられたときに呼び出されるオプションの関数宣言。これらの機能は、他の種類のルールのアクションと同じように動作します。
  onExit	フィールド値が現在の値から別の値に変更されたときに呼び出されるオプションの関数宣言。これらの機能は、他の種類のルールのアクションと同じように動作します。
  遷移	リスト内の各値に設定できる可能なターゲット値のリスト。 この例では、ルールが関連付けられているプロジェクトに user タイプを格納する担当者フィールドがあることだけが必要です。このフィールドがないと、ワークフローリストにエラーが表示されます。必須フィールドがアタッチされるまで、ルールを有効にすることはできません。 ステートマシンルールの場合、要件でステートマシンによって管理されるフィールドによって使用される値をリストする必要はありません。このフィールドとその値は、states プロパティから取得されます。

• transitions プロパティで定義されている各値には、name プロパティが含まれています。この名前は、コマンドでこの値を設定するために使用され、カスタムフィールドの値のリストにも表示されます。各トランジション名には、次の追加プロパティの定義が含まれています。

  プロパティ	説明
  targetState	name プロパティで指定されたコマンドが適用されたときに設定される値の実際の名前。
  後	アクションを実行する間隔を設定するオプションのプロパティ。アクション自体は action プロパティで指定されています。
  アクション	他のタイプのルールのアクションに似た動作をする任意の遷移のオプションのプロパティ。
  ガード	遷移が許可されるタイミングを決定するオプションの条件。ガード条件が満たされていない場合、カスタムフィールドの値は、この遷移に対して定義されている値に変更できません。 この例では、課題を実行中からオープン状態に戻すには、課題の割り当てを解除する必要があります。ガードには、workflow モジュールの message メソッドを使用して、最初に割り当てを解除せずに課題を再開しようとするユーザーにフィードバックを提供する機能が含まれています。

JavaScript でのワークフローの作成の詳細については、開発者ポータルのドキュメントを参照してください。

課題タイプごとのステートマシンルール

課題タイプごとのステートマシンルールにより、基本的なステートマシンに追加の次元が追加されます。このルールは、カスタムフィールド内の値の単一セットの遷移を規制するのではなく、個別のフィールド内の可能な値ごとに個別のステートマシンを提供します。

デフォルトの状態フィールドだけでなく、任意のカスタムフィールドにステートマシンルールを適用できるのと同じように、デフォルトのタイプフィールドだけでなく、列挙型フィールドの値によって型固有の遷移を依存させることができます。最も一般的な使用例は、発行タイプの現在の値に基づいて状態フィールドの値間の遷移を調整することです。

発行タイプごとのステートマシンルールは、基本的なステートマシンルールと同様に記述されますが、次の変更があります。

• 新しいステートマシン規則のテンプレートでは、fieldName プロパティはエイリアス stateFieldName に置き換えられます。このプロパティの値は、どのフィールドがステートマシンルールによって管理されるかを決定します。

• typeFieldName の個別のプロパティを使用すると、どのステートマシンルールを状態フィールドに適用するかを指定するフィールドを指定できます。このプロパティの存在は、基本的なステートマシンルール（それを使用しない）と発行タイプごとのステートマシンルールの主な違いです。

• states プロパティは、エイリアス defaultMachine に置き換えられます。このプロパティは、管理対象フィールドの値のデフォルトの遷移セットを記述します。このステートマシンルールは、代替のステートマシンルールが定義されている値が割り当てられていない課題に適用されます。

• alternativeMachines プロパティは、typeFieldName プロパティに設定されているカスタムフィールドの指定値に対するステートマシン遷移のコレクションを格納します。

typeFieldName の値を指定し、defaultMachine を構成し、ルールの alternativeMachines セクションの値に少なくとも 1 つのステートマシンを定義すると、発行タイプごとにステートマシンルールが作成されます。typeFieldName プロパティに指定するフィールドは、デフォルトのステートマシンルールと代替のステートマシンルールのコレクション間のスイッチとして機能します。

次の例は、課題の種類ごとにステートマシンルールを作成する方法を示しています。以下の各タブは、タイプフィールドの可能な値の 1 つに対応するステートマシンルールを説明しています。

まず、上記の基本的なステートマシンルールで適用されるロジックを採用し、プロジェクト内のあらゆるタイプの課題にデフォルトとして適用します。その結果、タスクタイプが割り当てられた課題の状態フィールドの値は、上記のモデルに従って規制されます。このステートマシンルールは、代替のステートマシンルールが割り当てられていないタイプが割り当てられている課題にも適用されます。

次に、バグタイプが割り当てられている課題に対してのみ、代替のステートマシンルールを追加します。

• このアーティファクトタイプでは、値再現できないを状態項目に割り当てることができます。

• デフォルトのステートマシンルールよりも少し柔軟にし、Fixed からオープンに戻すことができるようにします。これは、同じ課題を複数回報告する代わりに、リグレッションが発生したときに課題を再開できることを意味します。

• また、再現できないからオープンに戻すことも可能にします。

特定の状態や遷移に自動化を追加します。

• 課題がオープンから進行中に移動すると、課題は、課題の状態を変更したユーザーに割り当てられます。これは、基本ステートマシンの In progress 状態に使用される onEnter プロパティの定義と同じです。

• 進行中から再現できないへの移行のために、action を追加します。これにより、バグを再現するためにどのようなステップを踏んだかをユーザに説明するように求めるアラートが表示されます。

• 修正済みから、課題はオープン状態にのみ戻ることができます。その結果、onExit プロパティの自動化を Fixed フィールドの定義に追加できます。この自動化により、課題が再開されたことを通知する通知が担当者に送信されます。

もう 1 つの代替ステートマシンを追加し、これを機能タイプが割り当てられている課題に適用します。

• これらのタイプの課題については、課題をオープン状態から拒否に直接移動する可能性を追加します。チームが製品のビジョンに合わないと判断した機能を誰かが提案した場合、彼らはそれを捨てることができます。

• 方向転換の可能性を受け入れるために、課題を拒否からオープンに戻すことを許可します。

• 他のすべての遷移は、バグのステートマシンに似ています。

簡単にするために、このステートマシンには自動化を追加していません。これは、この課題タイプのプロセスを自動化または強化する機会がないことを意味するものではありません。可能な拡張機能は次のとおりです。

• オープン状態の一連の遷移に対して after イベントを使用して、6 か月以上この状態のままである課題にタグを付けます。その後、次のバックロググルーミングセッションでタグ付けされたすべての課題を確認できます。

• onEnter イベントを進行中状態に追加して、ロードマップの特定のマイルストーンまたはパイプラインに機能を割り当てるようにユーザーに促します。

• 拒否からオープンへの移行に action イベントを追加し、将来の検討のために機能要求を再開する理由を正当化するようにユーザーに促します。

基本的なステートマシンルールのサンプルコードを取得し、わずかな変更を加えるだけで、課題の種類ごとにステートマシンルールにすばやく変換できます。

• 必須ではありませんが、fieldName プロパティの名前をそのエイリアス stateFieldName に置き換えました。基本的なステートマシンルールのサンプルと同様に、State と呼ばれるフィールドの値間の遷移を管理しています。このプロパティの値は変更しません。

• プロパティ typeFieldName を追加し、その値として 'Type' を指定しました。これは、タイプフィールドをスイッチとして使用して、デフォルトのステートマシンを適用するか、このフィールドの可能な値の 1 つに割り当てられている代替のステートマシンを適用するかを決定できることを意味します。

• states プロパティの名前をそのエイリアス defaultMachine に置き換えて、化粧目的のためだけに別の変更を適用しました。このプロパティの値は変更しません。代わりに、基本的なステートマシンルールを再利用します。これは、ルールの alternativeMachines セクションで定義されているタイプのいずれにも割り当てられていない課題に適用されます。

• alternativeMachines の新しいセクションを追加しました。ここでは、タイプカスタムフィールドで値バグおよび機能が割り当てられている課題のステートマシンを指定します。

これが修正されたステートマシンのルールです。

このステートマシン規則を定義するコンポーネントは次のとおりです。

• require ステートメントは、ワークフロー API の entities および workflow モジュールを参照します。

• exports.TWO_DAYS プロパティは、オープンステータスの課題のリマインダーを送信するために使用されるローカル変数を設定します。この変数には、ミリ秒単位で 2 日に等しい値が割り当てられます。

• exports.ONE_WEEK_IN_MS プロパティは、1 週間以上進行中であったバグのリマインダを送信するために使用されるローカル変数を設定します。この変数には、ミリ秒単位で 1 週間に相当する値が割り当てられています。

• exports.rule プロパティは、Issue.stateMachine メソッドを使用して、宣言に続くスクリプトをステートマシン規則としてエクスポートします。

• ルール本体には、次のプロパティの定義が含まれています。

  プロパティ	説明
  タイトル	人間が読めるオプションのタイトル。
  stateFieldName	ステートマシンルールによって管理されるカスタムフィールドの名前。
  typeFieldName	管理対象フィールドに適用されるステートマシンを規制するカスタムフィールドの名前。
  defaultMachine	デフォルトのステートマシンのフィールド値とそれらの間の遷移の定義のリスト。デフォルトのステートマシンは、ルールの alternativeMachines セクションで定義されているタイプの 1 つが割り当てられていないすべての課題に適用されます。 スペースと特殊文字を含む値は一重引用符で囲みます。
  alternativeMachines	typeFieldName プロパティに設定されているカスタムフィールドに、指定された値のステートマシン遷移のコレクションを格納します。
  要件	ルールがエラーなしで実行されるために必要なエンティティのリスト。このプロパティにより、ルールをプロジェクトに安全にアタッチできるようになります。 この例では、ルールが関連付けられているプロジェクトに user タイプを格納する担当者フィールドがあることだけが必要です。このフィールドがないと、ワークフローリストにエラーが表示されます。必須フィールドがアタッチされるまで、ルールを有効にすることはできません。 発行タイプ別のステートマシンルールの場合、ステートマシンによって管理されるフィールドを要件に追加する必要はありません。このフィールドとその値は、defaultMachine プロパティと、ルールの alternativeMachines セクションの値ごとに定義されているフィールドのコレクションから派生します。typeFieldName プロパティに設定されたフィールドも、ワークフロールールの要件に暗黙的に追加されます。

• defaultMachine プロパティで定義された各値、およびルールの alternativeMachines セクションで各値に対して定義された各フィールドには、次の追加プロパティの定義が含まれています。

  プロパティ	説明
  初期	アーティファクトの作成時にリスト内のどの値を設定するかを決定するブール型プロパティ。厳密に 1 つの値でこのプロパティを true に設定する必要があります。初期値として設定されていない他の値の場合、このプロパティはオプションであり、省略することができます。
  onEnter	対応する値が issue に割り当てられたときに呼び出されるオプションの関数宣言。これらの機能は、他の種類のルールのアクションと同じように動作します。
  onExit	フィールド値が現在の値から別の値に変更されたときに呼び出されるオプションの関数宣言。これらの機能は、他の種類のルールのアクションと同じように動作します。
  遷移	リスト内の各値に設定できる可能なターゲット値のリスト。 この例では、ルールが関連付けられているプロジェクトに user タイプを格納する担当者フィールドがあることだけが必要です。このフィールドがないと、ワークフローリストにエラーが表示されます。必須フィールドがアタッチされるまで、ルールを有効にすることはできません。 ステートマシンルールの場合、要件でステートマシンによって管理されるフィールドによって使用される値をリストする必要はありません。このフィールドとその値は、states プロパティから取得されます。

• transitions プロパティで定義されている各値には、name プロパティが含まれています。この名前は、コマンドでこの値を設定するために使用され、カスタムフィールドの値のリストにも表示されます。各トランジション名には、次の追加プロパティの定義が含まれています。

  プロパティ	説明
  targetState	name プロパティで指定されたコマンドが適用されたときに設定される値の実際の名前。
  後	アクションを実行する間隔を設定するオプションのプロパティ。アクション自体は action プロパティで指定されています。
  アクション	他のタイプのルールのアクションに似た動作をする任意の遷移のオプションのプロパティ。
  ガード	遷移が許可されるタイミングを決定するオプションの条件。ガード条件が満たされていない場合、カスタムフィールドの値は、この遷移に対して定義されている値に変更できません。 この例では、課題を実行中からオープン状態に戻すには、課題の割り当てを解除する必要があります。ガードには、workflow モジュールの message メソッドを使用して、最初に割り当てを解除せずに課題を再開しようとするユーザーにフィードバックを提供する機能が含まれています。

• alternativeMachines プロパティは、typeFieldName プロパティで参照されるフィールドからの一連の値を格納します。専用のステートマシンに割り当てられた各値は、名前で参照されます。

JavaScript でのワークフローの作成の詳細については、開発者ポータルのドキュメントを参照してください。