タスクの I/O と書き戻しの契約を確立する

Maestro Case でタスクの入力、出力、および書き戻しのコントラクトを確立し、タスクが適切なフィールドを読み取って、ケース エンティティを一貫して更新するようにします。

概要

タスク入出力 (I/O) マッピングは、 ケースエンティティ [近日公開] とケースプランの各タスク間のデータコントラクトを定義します。入力マッピングは、タスクが受け取るケース エンティティ フィールドを制御し、出力マッピング (書き戻し) は、実行後にタスクがエンリッチメントするケース エンティティ フィールドを制御します。明確な I/O コントラクトを確立することで、すべてのタスクで正しいデータが読み取られ、適切なフィールドに結果が書き込まれ、ケース エンティティが信頼できる唯一の信頼できる情報源として維持されます。

対象者: 中級 — Studio Web でケース プランを作成するオートメーション開発者とソリューション アーキテクト。

前提条件

• Studio Web にアクセスします。
• 少なくとも 1 つのステージと 1 つのタスクが定義された、Studio Web で作成された ケース プロジェクト 。設定手順については、「 ケース プロジェクトを作成する 」をご覧ください。
• ネイティブの Data Fabric エンティティ、仮想データ オブジェクト (VDO)、またはケース トリガーを介して渡されるフィールドとして定義されたフィールドを持つケース エンティティ [近日公開]詳細については、「 ケース エンティティの概要 」をご覧ください。
• サポートされているタスクの種類 (ヒューマン アクション、RPA、API ワークフロー、実行コネクタ、AI エージェント、Maestro エージェンティック プロセス、子ケース) に精通していること。

手順 1: I/O 用のケース エンティティ スキーマを設計する

タスクの入力と出力をマッピングする前に、ケース エンティティ スキーマを定義して、ケースの作成時に入力されるフィールド (入力フィールド) と、処理中にタスクによって書き込まれるフィールド (出力フィールド) を区別します。

入力フィールドを識別する

入力フィールドは、ケースの作成時に、Data Fabric トリガー、コネクタ イベント、または API 呼び出しを使用して入力されます。これらのフィールドは、すべてのタスクの開始コンテキストを提供します。

入力フィールドの例:

• policyNumber — トリガー システムから渡されます。
• claimantName — ケース作成者が提供。
• lossDescription — 提出時に提供されるフリーテキストの説明。

出力フィールドを識別する

出力フィールドは、ケースの進行に応じてタスクによって書き込まれます。書き込みの競合を防ぐために、各出力フィールドには 1 つの所有タスクが必要です。

出力フィールドの例:

• validationResult — 「Validate Policy (ポリシーを検証)」コネクタ タスクによって記述されます。
• damageEstimate — 「Estimate Damage」エージェント タスクによって記述されます。
• adjusterDecision — 「アジャスターレビュー」の人間のタスクによって書かれました。

フィールドの所有権を文書化する

各出力フィールドに、その書き込みを担当するタスクのアノテーションを行います。スキーマは実行時に所有権を強制しませんが、このドキュメントでは、設計中に偶発的に衝突が発生するのを防ぎます。

{
  "entityName": "AutoInsuranceClaim",
  "fields": {
    "policyNumber":      { "type": "string",  "required": true },
    "claimantName":      { "type": "string",  "required": true },

    "policyValid":       { "type": "boolean", "writtenBy": "Validate Policy" },
    "extractedDetails":  { "type": "object",  "writtenBy": "Extract Details" },
    "damageEstimate":    { "type": "decimal", "writtenBy": "Estimate Damage" },
    "adjusterDecision":  { "type": "string",  "writtenBy": "Adjuster Review",
                           "enum": ["approve", "deny", "investigate_more"] },
    "payoutAmount":      { "type": "decimal", "writtenBy": "Calculate Payout" },
    "paymentReference":  { "type": "string",  "writtenBy": "Issue Payment" }
  }
}

注:

複数のタスクで構造的に類似した出力が生成される場合は、名前空間付きのフィールド名 ( validation.result と categorization.resultなど) を使用します。これにより、あいまいさが回避され、ラストライターウィンの問題が回避されます。

手順 2: タスクの入力マッピングを設定する

入力マッピングでは、特定のケース エンティティ フィールドが選択され、タスクの実装 (ワークフロー、フォーム、コネクタ、またはエージェント) にパラメーターとして渡されます。これにより、タスクが参照できるデータの種類が制御されます。

タスク設定パネルを開く

1. ケースプランデザイナで、ターゲットステージを選択します。
2. 設定するタスクを選択します。
3. タスク設定パネルの [入力/出力 ] セクションを開きます。

ケースのエンティティ フィールドをタスクのパラメーターにマッピングする

1. [入力] セクションで、[入力マッピングを追加] を選択します。
2. 各タスク パラメーターについて、対応する Case エンティティ フィールドをフィールド ピッカーから選択します。
3. タスクに必要なすべてのパラメーターに対して繰り返します。

たとえば、「領収書の検証」タスクでは、次の入力マッピングを使用できます。

タスク パラメーター	Case エンティティ フィールド
receipts	caseEntity.lineItems[*].receiptUrl
policyId	caseEntity.department
totalAmount	caseEntity.totalAmount
currency	caseEntity.currency

最小特権の原則に従う

タスクに必要なフィールドのみを渡します。ケース エンティティ [近日公開] 全体を 1 つのタスクにマッピングすることは避けてください。入力のスコープを設定すると、意図しないデータ漏洩のリスクが軽減され、タスクのコントラクトが明示されます。

手順 3: タスクの出力マッピング (書き戻し) を設定する

出力マッピングは、タスクの結果を受け取り、特定の値をケース エンティティ [近日公開] に書き戻します。これは、信頼できる唯一の情報源を充実させる書き戻しメカニズムです。

出力フィールドのマッピングを定義する

1. タスク設定パネルの同じ [入力/出力 ] セクションで、[ 出力 ] セクションを見つけます。
2. [ 出力マッピングを追加] を選択します。
3. タスクが生成する結果フィールドごとに、対象のケースエンティティフィールドを選択します。

たとえば、「領収書の検証」タスクでは、次の出力マッピングを使用できます。

Case エンティティ フィールド	タスクの出力フィールド
caseEntity.validationResult	taskOutput.validationResult
caseEntity.validationStatus	taskOutput.status
caseEntity.invalidReceipts	taskOutput.failedItems

フィールドごとに 1 人のライターを確保する

各 Case エンティティ出力フィールドを 1 つのタスクにのみ割り当てます。2 つのタスクが同じフィールドに書き込む場合、最後のライターが優先され、以前のデータは失われます。

読み取り専用フィールドを保護する

ケースの作成時に設定されたフィールド ( claimantName、 policyNumberなど) は、出力ターゲットとして表示しないでください。タスクの出力をこれらのフィールドにマッピングしないでください。

手順 4: ステージ間での書き戻しチェーンの確認

個々のタスクのマッピングを設定したら、ケース エンティティ [近日公開 ] をあるステージから次のステージにデータが正しく流れることを検証します。

データ フローのトレース

各ステージを順を追って確認します。

1. ステージ 1 のタスク A は、Case エンティティから入力フィールドを読み取ります。
2. タスク A は、出力マッピングを介して特定のケース エンティティ フィールドに結果を書き込みます。
3. Case Manager は、更新された Case エンティティ項目を使用して、ステージルール (ルールが最初、Case Manager エージェントのフォールバック) を評価します。
4. ステージ 2 のタスク B は、タスク A が書き込んだフィールドを独自の入力として読み取ります。

パターンは次のシーケンスに従います。

エンティティへのタスクの書き込み → エンティティの状態の変化 → ルールは 次のステージ→アクティブ化します →ダウンストリーム タスクは更新されたエンティティを読みます

ルールの依存関係を検証する

ステージの開始、完了、終了、および再エントリのルールごとに、 IF 句で参照する Case エンティティ フィールドにアップストリーム タスクの出力マッピングが入力されていることを確認します。タスクが書き込むことのないフィールドをルールが参照している場合、そのルールが true と評価されることはありません。

例:

• ステージエントリルール: IF caseEntity.adjusterDecision == "approve" — 「Adjuster Review」タスクが決定出力を caseEntity.adjusterDecisionにマッピングしていることを確認します。
• ステージ終了ルール: IF caseEntity.policyValid == false — 「ポリシーの検証」タスクがその結果を caseEntity.policyValidにマップすることを確認します。

手順 5: 再突入シナリオの処理

既定では、再入力されたステージ内のすべてのタスクが再実行され、Case エンティティ内の以前の出力が上書きされます。タスクごとの runOnlyOnce フラグを使用すると、特定のタスクの再実行を、以前の出力がまだ有効な場合にそのタスクの再実行 から 除外できます。

再入国時に再実行する必要があるタスク

再作業後に出力が変更される可能性があるタスクについては、 runOnlyOnce: false (既定) のままにします。これらのタスクは再実行され、Case エンティティ [近日公開] の以前の出力が上書きされます。

再実行してはならないタスクの出力を保持する

以前の出力がまだ有効であるタスクに runOnlyOnce: true を設定します (たとえば、修正されたデータに依存しない初期分類)。これらのタスクは再エントリ時にスキップされます。その Case エンティティ フィールドは変更されません。

タスク	runOnlyOnce	再突入時の動作
領収書を検証する	false (既定)	再実行と上書き validationResult
経費を分類	true	スキップ;以前の categories 値を保持する
ポリシーの制限を確認する	false (既定)	ポリシー チェックの出力を再実行して上書きします

期待される結果

これらの手順を完了したら、以下に進みます。

• ケースプラン内のすべてのタスクには、ケースエンティティから受け取るデータの範囲を指定する明示的な入力マッピングがあります [近日公開] 。
• すべてのタスクには明示的な出力マッピングがあり、指定されたケース エンティティ フィールドに結果を書き戻します。
• 各 Case エンティティ出力フィールドには、書き込みの競合を防止する所有タスクが 1 つ存在します。
• ステージルールは、アップストリームタスクが確実に設定するケースエンティティフィールドを参照します。
• 再入力動作は、タスクが必要に応じて新しい出力または保存された出力を生成するように構成されます。
• ケース エンティティは、ケースのライフサイクル全体を通じて信頼できる唯一の情報源として機能します。

ユース ケースの例

シナリオ: 自動車保険の請求処理は、FNOLの摂取、調査、評価、決済の4段階です。

ステージ	タスク	入力 (Case エンティティ [近日公開] から)	出力 (ケース エンティティに出力)
FNOLインテーク	ポリシーを検証	policyNumber	policyValid
FNOLインテーク	詳細を抽出	lossDescription, photos	extractedDetails
調査	写真を分析する	photos, vehicleInfo	photoAnalysis
調査	現場検査	claimId, vehicleInfo, lossDescription	fieldInspection
評価	ダメージを推定	photoAnalysis, fieldInspection, extractedDetails	damageEstimate
評価	Adjuster Review	damageEstimate, photoAnalysis, policeReport	adjusterDecision
Settlement	支払いの計算	damageEstimate, policyNumber	payoutAmount
Settlement	支払いを発行	payoutAmount, claimantName	paymentReference
Settlement	請求者への通知	claimantEmail, payoutAmount, paymentReference	—

この例では、Assessment ステージの "Estimate Damage" タスクが、前のステージの上流タスクによって書き込まれた 3 つのフィールド (photoAnalysis、 fieldInspection、 extractedDetails) を消費します。ケースマネージャーは、「査定人レビュー」タスクによって作成された adjusterDecision を使用して、決済ステージのエントリルールを評価します。

コード スニペット

次の JSON は、FNOL インテーク ステージ内の 2 つのタスクの完全な I/O マッピング設定を示しています。

{
  "stage": "FNOL Intake",
  "tasks": [
    {
      "name": "Validate Policy",
      "type": "connector",
      "required": true,
      "runOnlyOnce": false,
      "input": {
        "policyNumber": "caseEntity.policyNumber"
      },
      "output": {
        "caseEntity.policyValid": "taskOutput.isValid"
      }
    },
    {
      "name": "Extract Details",
      "type": "agent",
      "required": true,
      "runOnlyOnce": true,
      "input": {
        "description": "caseEntity.lossDescription",
        "photos": "caseEntity.photos"
      },
      "output": {
        "caseEntity.extractedDetails": "taskOutput.structuredData"
      }
    }
  ]
}

トラブルシューティング

症状	考えられる原因	解決方法
下流タスクが空または null の入力を受け取る	アップストリーム タスクの出力マッピングで、予期される [ケース エンティティ] フィールドに入力されない	アップストリーム タスクの出力マッピングが正しい Case エンティティ フィールド名を対象としていることを確認します。
ステージ ルールが true と評価されない	ルールで参照されている Case エンティティ フィールドは、どのタスクによっても書き込まれません	担当タスクから参照されるフィールドへの出力マッピングを追加します。
タスクは、別のタスクによって書き込まれたデータを上書きします	2 つのタスクの出力が同じ Case エンティティ フィールドにマッピングされます	各タスクに一意のケース エンティティ フィールドを割り当てます。競合を回避するには、名前空間付きのフィールド名を使用します。
再突入で古い結果が出る	タスクrunOnlyOncetrueに設定されているが、その出力は修正されたデータに依存している	更新されたデータを再検証または再処理する必要があるタスクの場合は、[ runOnlyOnce ] を [ false ] に設定します。
読み取り専用フィールドが処理中に上書きされる	タスクの出力マッピングは、不変である必要があるフィールド ( policyNumberなど) を対象とします	出力マッピングを削除します。入力専用フィールドを出力ターゲットとして使用しないようにします。
Agentic Case Manager の実行は成功するが、タスクはトリガーされない	エージェントの出力が必要な caseManagerDecisions.tasksToRun の形状 (タスク名のプレーンな配列など) に一致しない	Case Manager の入力コントラクトと出力コントラクトのコントラクトを正確に一致させます。

この警告は、caseManagerDecisionsが見つからない場合、または正しい値形式を返さない場合に、Case Manager エージェントのタスクのプロパティの「出力」セクションに表示されます。使用する正確な形状については、「 Case Manager の入出力コントラクト 」を参照してください。

制限事項

• [監視] ビューでの変数のフィルター処理は、フィルターを有効化した後に実行されるインスタンスにのみ適用されます。既存のインスタンスは過去にさかのぼってフィルター処理されません。
• エンティティ スキーマの writtenBy 注釈は、ドキュメント化を目的とした設計時の規則です。Maestro は、実行時に単一ライターのルールを強制しません。
• ケース エンティティ [近日公開] に対するフィールド レベルのアクセス制御は、このプレビュー リリースでは利用できません。フィールドに出力がマッピングされているすべてのタスクは、そのフィールドに書き込むことができます。

次のステップ

• ステージルールの設定方法 — エントリ、完了、終了、および再エントリルールでケースエンティティフィールドを使用する方法について説明します。
• 再エントリ動作の設定方法 — ケースが以前に完了したステージに戻ったときに再実行するタスクを定義します。
• ケースエンティティの概要 — 3 つの標準データオブジェクト (ケースエンティティ [近日公開]、[ ケースドキュメント]、[ケースコメント]) と、ケースにデータを取り込む方法を理解します。
• タスクの種類の参照 — サポートされているすべてのタスクの種類とその構成オプションを確認します。