マルチインスタンス マーカー

概要

マーカーを使用すると、List 型変数内の要素ごとにタスクを 1 回実行するように設定し、複数のシーケンシャル実行または並列実行を作成できます。表記法と概念のガイダンスについては、『BPMN 入門』の章の「マーカー」をご覧ください。

マルチインスタンス マーカーを使用する状況

マルチインスタンス マーカーは、項目のリストがあり、各項目に対して同じタスクを 1 回実行する必要がある場合に使用します。次に例を示します。

• 請求書 ID のリストに含まれる各請求書を検証する
• 一連のレコードを、レコードごとに外部 API を呼び出して強化する
• リスト内の各受信者に通知を送信する

マーカーを使用しない場合は、シーケンス フローを使用して手動ループを構築する必要がありますが、この方法は読みにくいうえに追跡が困難です。マルチインスタンス マーカーを使用することで、プロセス ダイアグラムをすっきりとした状態に保ち、[実行証跡] で項目ごとに確認できます。[実行証跡] には、各項目の実行が個別に、専用のステータスと出力とともに表示されます。

シーケンシャル モードは、順序が重要である場合や、各実行が前の実行に依存する場合に使用します。並列モードは、各項目が独立していて、高速なスループットが必要な場合に使用します。

サポートされるコレクション型

Maestro では、以下のコレクション型がマルチインスタンス実行でループ可能として扱われます。変数がこれらのいずれかの型である場合は、[項目] フィールドで直接使用できます。

• System.Collections.Generic.List<T>
• System.Collections.Generic.IList<T>
• System.Collections.Generic.IEnumerable<T>
• System.Collections.IEnumerable
• System.Data.DataTable
• Newtonsoft.Json.Linq.JArray
• collectionDataType が List で始まる型
• collectionDataType が Array で始まる型
• int[]、string[]、bool[]、double[]、decimal[]、long[] などのプリミティブ .NET 配列

項目ごとの作業は、べき等にして存続時間を短くしてください。すべての反復処理が完了した後に結果を 1 つの変数に収集する必要がある場合は、[出力] セクションと [変数を更新] セクションを使用します。

マルチインスタンス マーカーの追加方法

重要:

タスクをマルチインスタンスに変換する前に、タスクのアクションを設定します。マルチインスタンスの構成は、マーカーを適用するとすぐにタスクの出力にバインドされます。その時点でアクションが選択されていない場合、バインドは、アクションの実際の出力ではなくタスクの既定の出力プレースホルダーに関連付けられます。後でアクションを選択してもこのバインドは更新されません。そのため、各反復処理はバインドされていない出力に書き込みを行い、実行時に、集約された変数内に null エントリを生成します。タスクを最初にマルチインスタンスに変換済みの場合、設定を解除して再適用する回避策については、「集約変数に null が含まれる」をご覧ください。

1. キャンバスでタスクを選択し、[プロパティ] パネルでそのアクションを設定します。[出力] セクションに、選択したアクションが反映されることを確認します。たとえば、エージェント アクションでは、型指定された response 出力と Error 出力が公開されます。[出力] セクションがアクションと一致した後でのみ、次の操作に進みます。

2. タスクの上にある要素ツールバーで、[要素を変更] を選択します。

   

3. [シーケンシャル マルチインスタンス] または [並列マルチインスタンス] を選択します。

   マーカーがタスク図形の下部に表示されます。

   

4. [プロパティ] パネルで、[マルチインスタンス] を展開します。

   

5. [項目] で、反復処理するリスト変数を選択します (例: vars.invoiceList)。

   これにより、処理するコレクションを Maestro に指示します。[項目] の値がない場合、タスクは要素ごとに 1 回実行されるのではなく、通常のタスクとして 1 回実行されます。Maestro は、リスト内の要素ごとに 1 つの実行を作成します。

6. 必要に応じて、[エラー処理] を展開して [失敗時にリトライ] を有効化し、項目の個々の実行を個別にリトライします。設定オプションについては、「要素レベルのリトライ」をご覧ください。

注:

マルチインスタンスはタスクでのみサポートされます。実行順序は、選択したマーカーの種類 (シーケンシャルまたは並列) によって決まります。

現在の項目を参照する

[マルチインスタンス] セクションでは [項目] のリストだけが必要です。ここで、反復処理するコレクションを Maestro に指示します。反復子の式は別の場所、つまりタスクの [入力] セクションに入力します。ここで、現在の項目を実行ごとに特定の入力にマッピングします。

使用する式は、マーカーがタスクに直接適用されているか、それともタスクが、マルチインスタンス タスクから呼び出されるサブプロセス内で実行されるかによって異なります。

シナリオ	式	使用場所
マーカーがタスクに直接適用されている	iterator.item	タスクの [入力] フィールド
タスクが、マルチインスタンス タスクから呼び出されるサブプロセス内で実行される	iterator[0].item	サブプロセス タスクの [入力] フィールド

注:

iterator[0].item の [0] は、タスクがサブプロセス内で実行される場合に、最も外側の反復子のスコープを参照します。標準の単一レベルのマルチインスタンスでは、常に [0] を使用します。iterator[1] はありません。

現在の要素全体を渡すには、iterator.item を使用します。1 つのプロパティを渡すには、iterator.item.propertyName を使用します。以下に例を示します。

• iterator.item.invoiceId
• iterator.item.customer.email
• { id: iterator.item.id, flags: ["recheck"] }

タスクで現在の項目を参照する

マルチインスタンス マーカーがタスクに直接適用されている場合は、[プロパティ] パネルの [入力] セクションで iterator.item を使用して、現在の要素を各実行に渡します。

[プロパティ] パネルのリファレンス

• アクション: タスクの実行方法を選択します (Integration Service のアクション、エージェント アクション、またはモデリングのみが目的の場合は [なし])。

• 入力: 選択したアクションで定義されているパラメーターが表示されます。現在のリスト項目を設定するパラメーターごとに、その値を iterator.item (要素全体を渡す場合) または iterator.item.propertyName (特定のプロパティを渡す場合) に設定します。

  

• 出力: 各反復処理で返す内容を定義します。タスクにアクションを設定する際に、アクションの出力 (通常は response、エージェント アクションの場合は追加で Error) が自動的にここに表示され、それぞれが 値のチップを介してソースにバインドされます。アクションの出力に加えて、反復処理ごとに他の値を追加するには、[+ 新規追加] を選択して名前を付けます。ここに表示されているエントリがアクションによって公開される内容を反映していない場合 (たとえば、値のチップにアクションの実際の出力型ではなく汎用のプレースホルダーの種類が表示される場合) は、「集約変数に null が含まれる」をご覧ください。

• 変数を更新: すべての反復処理の完了後に集約された出力を格納するプロセス変数を指定します。[変数の値を設定] を選択し、対象の変数 (例: vars.validationResults) を選択します。この変数は、反復処理ごとに 1 つのエントリを含む配列を保持します。各反復処理で文字列が返される場合は文字列の配列、各反復処理でオブジェクトが返される場合はオブジェクトの配列になります。シーケンシャル モードでは、エントリは入力の順序に従います。並列モードでは、順序は反復処理の完了順序に一致し、保証されません。

サブプロセス内で現在の項目を参照する

タスクが、マルチインスタンス タスクから呼び出されたサブプロセス内で実行される場合、現在の項目を iterator.item として直接利用することはできません。代わりに、サブプロセス タスクの [入力] で iterator[0].item を使用し、親のマルチインスタンス タスクから渡された要素にアクセスします。

[プロパティ] パネルのリファレンス

• アクション: タスクが外部システム、API、またはエージェントとどのように対話するかを設定します。

• 入力: タスクに必要な値ごとに入力を追加します。現在の要素全体を渡すには値を iterator[0].item に設定し、特定のプロパティを渡すには iterator[0].item.propertyName に設定します。

  例 — id フィールドを持つオブジェクトがリストに含まれる場合は、[プロパティ] パネルの [入力] セクションに次のようにエントリを追加します。

  • 入力フィールド名: currentItemId
  • 値: iterator[0].item.id

  .id は、リスト オブジェクトの実際のプロパティ名に置き換えます。

例

例: 請求書のリストを検証する

この例では、サービス タスクを、リスト内の請求書ごとに 1 回実行するように設定する方法を示します。

1. リスト変数を準備する

1. データ マネージャーを開きます。
2. 変数を作成します。
   • Name (名前): invoiceList
   • 種類: オブジェクトの配列または文字列の配列
   • 既定値: ["INV-001", "INV-002", "INV-003"]

2. サービス タスクを追加し、アクションを設定する

1. キャンバスにサービス タスクを追加し、「Validate invoice」という名前を付けます。

2. タスクを選択した状態で、[プロパティ] パネルの [アクション] セクションを開き、各請求書に対して実行するエージェントを設定します。

   • アクション: [エージェントを開始して待機] を選択します。
   • エージェント: 請求書の検証を担当するエージェントを選択します。エージェントはすでにテナントに存在している必要があります。エージェントは Agent Builder で作成できます。

   

3. [出力] セクションにエージェントのアクションが反映されることを確認します。response 出力とその実際の出力の種類が Error とともに表示される必要があります。これが一致した後でのみ、次の操作に進みます。

3. タスクをマルチインスタンスに変換する

1. タスクを選択した状態で、要素ツールバーを開き、[要素を変更] → [シーケンシャル マルチインスタンス] を選択します。
2. [プロパティ] パネルで [マルチインスタンス] セクションを展開し、[項目] を vars.invoiceList に設定します。

4. 現在の項目を入力にマッピングする

アクションを選択すると、[入力] セクションにそのアクションで定義されているパラメーターが表示されます。たとえば、RPA ワークフローの入力引数やエージェントのパラメーターなどです。

現在のリスト項目を設定する各パラメーターに対して、その値フィールドを選択して、「iterator.item」と入力します。

• 現在の要素全体を渡すには、iterator.item を使用します。たとえば、リストに文字列が含まれる場合、文字列 "INV-001" とします。
• 特定のプロパティを渡すには、iterator.item.propertyName を使用します。たとえば、リストにオブジェクトが含まれる場合、iterator.item.id とします。

5. プロセスをデバッグする

1. [デバッグ] → [ステップごとにデバッグ] を選択します。
2. リストの項目ごとに Validate invoice が 1 回実行されます。

結果: [実行証跡] に、請求書ごとに 1 つの実行が表示されます。各請求書にはその項目の値のラベルが付けられています。

すべての項目を順次に実行するのではなく同時に実行するには、手順 2 で [並列マルチインスタンス] を選択します。以下の展開の例もご覧ください。

例: 展開して結果を収集する

シナリオ: 外部 API から請求書 ID のリストを受け取ります。各請求書を個別に検証してから、集計された結果を下流工程で使用する必要があります。

1. リスト変数 (例: vars.invoiceIds) が前のステップ (外部 API を呼び出すサービス タスクなど) で設定されるようにします。

2. 「Validate invoice」という名前のサービス タスクを追加し、通常のタスクに、1 つの請求書を検証するアクションを設定します。[出力] セクションにアクションが反映されることを確認します。response エントリにアクションの実際の出力の種類が表示される必要があります。

3. タスクを選択した状態で、[要素を変更] → [並列マルチインスタンス] を選択します。

4. [マルチインスタンス] セクションで、[項目] を vars.invoiceIds に設定します。

5. [入力] セクションで、iterator.item をアクションの請求書 ID パラメーターにマッピングします (例: 入力 invoiceId を iterator.item に設定します)。

6. [出力] セクションで、アクションの response 出力が表示されていて、アクションの結果にバインドされていることを確認します。反復処理ごとに追加の集約値が必要な場合は、[+ 新規追加] を選択して定義します。表示されている出力がアクションによって公開される内容と一致しない場合は、アクションを設定する前にマーカーが適用されています。詳しくは、「集約変数に null が含まれる」をご覧ください。

7. [変数を更新] セクションで、[変数の値を設定] を選択し、集計された結果を格納する変数を設定します (例: vars.validationResults)。すべての反復処理の完了後、この変数には請求書ごとに 1 つのエントリが格納されます。アクションが文字列を返す場合は文字列の配列、オブジェクトを返す場合はオブジェクトの配列が格納されます。

   

ランタイムの動作

1. 展開/集約: Maestro は、項目ごとに 1 つのアクティビティ インスタンスを作成し、すべてのインスタンスが完了した時点でそのグループを完了します。
2. 順序:シーケンシャル モードでは保証されます。並列モードでは保証されません。
3. 同時実行: 並列モードでは、項目は同時に実行されます。ただし、プラットフォームの制限とリソースの可用性が適用されます。
4. 失敗: 各項目の結果は別個のものです。部分的な失敗を処理する下流のロジックを定義します (例: 続行、リトライ、しきい値に基づいて停止)。
5. オブザーバビリティ: 各項目の実行は [実行証跡] で個別に追跡され、項目ごとのステータスと結果が表示されます。

トラブルシューティング

集約変数に null が含まれる

[変数を更新] によって生成される集計変数には、各反復処理が正常に実行された場合でも、すべての反復処理の null が格納されます (例: [null, null, null])。

これは、アクションを選択する前にタスクをマルチインスタンスに変換した場合に発生します。マルチインスタンスの設定は、アクションの実際の出力ではなく、タスクの既定の出力プレースホルダーにバインドされます。後でアクションを選択しても、このバインドは更新されません。各反復処理はバインドされていない出力と 集約レコード null に書き込みを行います。

既存のタスクを修正するには、以下の手順を実行します。

1. 要素ツールバーで [要素を変更] を選択し、タスクを通常のタスクに戻します。
2. アクションが選択されていて、[出力] セクションにアクションが反映されることを確認します (たとえば、アクションによって入力される response に加え、エージェントのアクションの場合は Error)。
3. [要素を変更] → [シーケンシャル マルチインスタンス] または [並列マルチインスタンス] を使用して、タスクを再度マルチインスタンスに変換します。
4. [出力] セクションで、エントリがまだアクションの出力と一致していることを確認します。

新しいタスクでこれを防ぐには、必ず、タスクをマルチインスタンスに変換する前にアクションを設定します。

項目の入力が無視され、タスクが一度だけ実行される

タスクは 1 回実行され、[項目] の値は通常の入力として扱われます。

これは、[項目] に渡される変数が、サポートされるコレクション型の 1 つではない場合に発生します。データ マネージャーで、サポートされるコレクションの型に照らして変数の型を確認します。リストをプレーンな文字列として定義した場合は、文字列の配列またはオブジェクトの配列に変換します。

出力のエントリにアクションの出力が反映されない

[出力] セクションに、選択したアクションに対して期待するエントリが表示されません。たとえば、エージェント アクションでは response と Error が公開される必要がありますが、汎用の response プレースホルダーのみが表示されます。

出力は、選択したアクションの反映が完了する前にキャプチャされています。[要素を変更] → 通常のタスクを使用してマルチインスタンス マーカーの設定を解除し、[出力] セクションにアクションが反映されることを確認してから、マーカーを再適用します。

ベスト プラクティス

1. 展開の前にコレクションを検証します。空、null、または大きすぎるリストがないか確認します。
2. 項目ごとの作業は、存続時間を短くしてフォールト トレラントな状態を保ちます。必要に応じてリトライを追加します。
3. 必要な情報だけを集計します。大量に集計すると、パフォーマンスや可読性に影響する可能性があります。
4. 達成基準を明確にします。マルチインスタンス タスクの後に、集計された出力変数を評価する排他的ゲートウェイを追加します (例: 成功した結果の数がしきい値を満たした場合にのみ、次のステップにルーティングします)。

注:

並列マルチインスタンスでは、要素は 50 個のバッチで実行されます。各項目が大きなオブジェクトまたは複雑なオブジェクト (複数のキーと値のペアまたは入れ子になった構造) である場合は、コレクションの合計サイズも 50 未満に保ちます。項目のサイズは同時に維持できる数に影響するためです。

表記法と概念のガイダンスについては「マーカー」 (BPMN 入門) をご覧ください。Maestro でサポートされているすべての BPMN 要素のリストについては「BPMN でサポートされている要素」をご覧ください。

サブプロセスまたはコール アクティビティで作業している場合、変数のスコープ、入出力のマッピング、終了イベント変数については、「サブプロセス」をご覧ください。