永続ケースのエンティティ スキーマを設計する

信頼性の高い Maestro Case の書き戻しのために、入力フィールド、計算フィールド、フィールド所有権ルールを含む永続的なケース エンティティ スキーマを設計します。

概要

サポート案件エンティティ [近日公開] は、すべてのステージ、タスク、およびルールが、サポート案件の有効期間を通じて読み取りと書き込みを行う、一元的で永続的なデータ モデルです。適切に設計されたエンティティ スキーマでは、 入力フィールド (ケースの作成時に提供されるデータ) と 計算フィールド (処理中にタスクによって生成されるデータ) が分離され、2 つのタスクが同じフィールドに書き込むことがないように 、フィールドの所有権を明確に 割り当てます。このガイドに従って、書き戻し中のデータの競合を防ぎ、信頼性の高いステージ規則をサポートするスキーマを定義します。

前提条件

• Studio Web にアクセスします。
• ステージとタスクが特定された定義済みの業務プロセス。
• Maestro Case の主要な概念に精通している。
• UiPath 環境で利用可能な Data Fabric インスタンス (ネイティブ エンティティの作成に推奨)。

手順 1: すぐに使えるデータ オブジェクトを理解する

すべてのケースプロジェクトでは、次の 3 つのデータオブジェクトが自動的に作成されます。

オブジェクト	目的
ケース エンティティ [近日公開]	ステージ、タスク、およびルールが読み書きする、構造化されたすべてのビジネス データを保持します。
ケースドキュメント	ケースに関連付けられた添付ファイルとファイル (領収書、写真、契約書) を保存します。
ケースコメント	ライフサイクル全体を通じてケース ワーカーが追加したメモ、注釈、およびコミュニケーションが格納されます。

3 つすべてが、ケースの作成時に自動生成される不変の caseID システム フィールドを共有します。このフィールドは、すべてのケース データを関連付け、変更できません。

スキーマの設計作業は、すべてのケース処理ロジックの信頼できる唯一の情報源である ケースエンティティ に集中します。

手順 2: エンティティが存在する場所を選択する

フィールドを定義する前に、エンティティの取得方法を決定します。データ所有権モデルに最も適したオプションを選択します。

ソース	説明	使用すべきタイミング
Data Fabric ネイティブ (推奨)	Data Fabric でネイティブ ビジネス エンティティとしてエンティティを作成し、ケースにリンクします。	データ モデルを所有する新しいプロセスです。
Data Fabric の仮想データ オブジェクト (VDO)	Data Fabric で外部ソースを VDO として登録し、VDO をケースにリンクします。	エンティティ データは外部システム (CRM、ERP) に存在し、重複することなく参照する必要がある。
ケース トリガーのペイロード	ケース作成トリガーで既存のデータを渡します (API コネクタなど)。ペイロード項目は、すべてのステージで使用可能なケース項目になります。	作成時にケースをハイドレートする軽量の連携。

手順 3: フィールドを特定して分類する

ケースのライフサイクル全体をマッピングする

ケースプランのすべてのフェーズとすべてのタスクをリストアップします。各タスクについて、以下を特定します。

• 読み取る必要があるデータ (入力)。
• 生成されるデータ (出力)

フィールドを 2 つのカテゴリに分類する

スキーマ内のすべてのフィールドを次の 2 つのグループのいずれかに分割します。

カテゴリ (Category)	定義	特徴	例
入力フィールド	サポート ケースの作成時に、トリガー ペイロード、フォーム送信、または外部システムのいずれかによって提供されるデータです。	作成時に入力されます。通常、ハイドレーション後は読み取り専用です。最初のルーティングとタスクの実行に必要です。	policyNumber、claimantName、dateOfLoss、lossDescription
計算フィールド	ケース処理中にタスクによって生成されるデータ。これらのフィールドは最初は空で、タスクが完了すると書き戻されます。	作成時には空です。特定のタスクによって記述されます。下流のタスクとルールによって消費されます。	validationResult、damageEstimate、adjusterDecision、paymentReference

入力フィールドを読み取り専用にする

employeeId、policyNumber、reportId などの入力フィールドは、タスクによって上書きされてはなりません。これらのフィールドをスキーマ内に読み取り専用として文書化し、処理中に誤って変更されないようにします。

手順 4: フィールドの所有権を確立する

フィールドの所有権は、データの競合を防ぐための最も重要な原則です。エンティティの各計算フィールドは、 1 つのタスクによってのみ書き込まれる必要があります。

フィールドごとに 1 人のライターを割り当てる

すべての計算フィールドに対して、書き込みを担当する 1 つのタスクを指定します。2 つのタスクが同じフィールドに書き込むと、最後のライターが優先され、以前のデータは失われます。

スキーマの所有権にアノテーションを行う

writtenBy注釈 (または同等のコメント) を使用して、各計算フィールドを所有するタスクを文書化します。実行時にこのアノテーションは強制されませんが、開発中の衝突を防止する設計コントラクトとして機能します。

曖昧さを回避するために名前空間フィールドを使用する

複数のタスクで同様の種類の出力が生成される場合は、フィールドを名前空間にして区別できるようにします。以下に例を示します。

• photoAnalysis は、画像分析エージェント タスクの出力に使用します。
• fieldInspection は、人間が現場を検査するタスクの出力に使用します。
• 複数のタスクで競合する可能性のある汎用の analysisResult フィールドは避けてください。

手順 5: スキーマを定義する

選択したソースにエンティティを作成する

Studio Web のケース エンティティ デザイナーに移動します。新しいエンティティには、ビジネス ドメインに合ったわかりやすい名前を付けます ( AutoInsuranceClaim や ExpenseReportなど)。

最初に入力フィールドを追加する

すべての入力フィールドを、その型、必須フラグ、既定値とともに定義します。ケースの作成時に指定する必要があるフィールドに required: true を設定します。

所有権のアノテーションを含む計算フィールドを追加する

すべての計算フィールドとその型を定義し、 required: false を設定し (これらのフィールドは作成時には空です)、各計算フィールドに書き込むタスクでアノテーションを行います。

参照スキーマを確認する

次の例は、自動車保険請求ケースのフィールド所有権を使用した入力と計算のパターンを示しています。

{
  "entityName": "AutoInsuranceClaim",
  "fields": {
    // --- Input fields (populated by trigger, read-only after creation) ---
    "claimId":            { "type": "string",  "required": true,  "generated": true },
    "policyNumber":       { "type": "string",  "required": true },
    "claimantName":       { "type": "string",  "required": true },
    "claimantEmail":      { "type": "string",  "required": true },
    "dateOfLoss":         { "type": "date",    "required": true },
    "lossDescription":    { "type": "string",  "required": true },
    "vehicleInfo":        { "type": "object",  "required": true },
    "photos":             { "type": "array",   "items": "url" },
    "policeReportNumber": { "type": "string",  "required": false },

    // --- Computed fields (written by tasks during processing) ---
    "policyValid":        { "type": "boolean", "writtenBy": "Validate Policy" },
    "extractedDetails":   { "type": "object",  "writtenBy": "Extract Details" },
    "photoAnalysis":      { "type": "object",  "writtenBy": "Analyze Photos" },
    "fieldInspection":    { "type": "object",  "writtenBy": "Field Inspection" },
    "policeReport":       { "type": "object",  "writtenBy": "Retrieve Police Report" },
    "damageEstimate":     { "type": "decimal", "writtenBy": "Estimate Damage" },
    "adjusterDecision":   { "type": "string",  "enum": ["approve", "deny", "investigate_more"] },
    "payoutAmount":       { "type": "decimal", "writtenBy": "Calculate Payout" },
    "paymentReference":   { "type": "string",  "writtenBy": "Issue Payment" }
  }
}

ステップ6:入力と出力のマッピングをタスクに配線する

スキーマを定義したら、入力マッピングと出力マッピングを使用してスキーマをタスクに接続します。

入力マッピングを設定する

各タスクについて、タスクが読み取る必要があるケース エンティティのフィールドのみを選択します。これにより、タスクが参照できるデータの種類が制御されます。

例: ポリシー タスクの入力マッピングの検証:

"input": {
  "policyNumber": "caseEntity.policyNumber"
}

出力マッピングを設定する

各タスクについて、タスクの結果を、そのタスクが所有する特定のケース エンティティ フィールドにマッピングします。これが書き戻しメカニズムです。

例 — Validate Policy タスク出力マッピング:

"output": {
  "caseEntity.policyValid": "taskOutput.policyValid"
}

出力マッピングがフィールドの所有権を尊重していることを確認する

すべてのタスクの出力マッピングをスキーマの注釈と照合します。2 つのタスクが同じケース エンティティ フィールドに書き込まれないことを確認します。

手順 7: ルールに照らしてスキーマを検証する

ステージルール(開始、完了、終了、再入力)は、ケースエンティティフィールドに対して評価されます。以下を確認します。

• ルールの IF 句で参照されるすべてのフィールドがスキーマに存在する。
• フィールドは、ルールが評価され る前に 完了するタスクによって書き込まれます。
• フィールドの型がルールで使用されている演算子と一致している (たとえば、小数フィールドの文字列比較は使用しないでください)。

例 — インテークステージの終了ルールは、 policyValid フィールドによって異なります。

WHEN PolicyCheckCompleted event arrives
  IF caseEntity.policyValid == false

この終了ルールが評価される前に、 Validate Policy タスクが policyValid を書き込み、取り込みステージ内で完了することを確認します。

期待される結果

これらの手順を完了すると、次のようなケース エンティティ スキーマが作成されます。

• 入力フィールド (ケースの作成時に入力される) と計算フィールド (処理中にタスクによって書き込まれる) を明確に分離します。
• フィールドの所有権を明示的に割り当てて、各計算フィールドに 1 つのタスクが書き込まれるようにします。
• 名前空間付きのフィールド名を使用して、あいまいさや競合を防ぎます。
• タスクからエンティティへの信頼性の高い 書き戻し をサポートし、ダウンストリームのルールとタスクが競合のない正確なデータを使用するようにします。
• ケースプランとそのタスク間のデータコントラクトを writtenBy 注釈で文書化します。

コード スニペット

以下は、経費精算書のユース ケースの 2 つ目の参照スキーマです。同じ入力パターンと計算パターンを示しています。

{
  "entityName": "ExpenseReport",
  "fields": {
    // --- Input fields (populated at case creation) ---
    "reportId":          { "type": "string",  "required": true,  "generated": true },
    "employeeId":        { "type": "string",  "required": true },
    "employeeName":      { "type": "string",  "required": true },
    "department":        { "type": "string",  "required": true },
    "totalAmount":       { "type": "decimal", "required": true },
    "currency":          { "type": "string",  "default": "USD" },
    "lineItems":         { "type": "array",   "items": "ExpenseLineItem" },

    // --- Computed fields (written by tasks during processing) ---
    "validationResult":  { "type": "object",  "required": false, "writtenBy": "Validate Receipts" },
    "categories":        { "type": "array",   "required": false, "writtenBy": "Categorize Expenses" },
    "anomalyFlags":      { "type": "array",   "required": false, "writtenBy": "Flag Anomalies" },
    "managerDecision":   { "type": "string",  "enum": ["approved", "rejected", "needs_info"] },
    "financeDecision":   { "type": "string",  "enum": ["approved", "rejected", "hold"] },
    "paymentRef":        { "type": "string",  "required": false, "writtenBy": "Process Payment" }
  }
}

トラブルシューティング

問題	原因	解決方法
計算フィールドに、予期しないデータや古いデータが含まれています。	複数のタスクが同じフィールドに書き込みます。最後の書き込みによって以前の値が上書きされます。	出力マッピングを監査します。各フィールドを 1 つのタスクに正確に割り当て、名前空間付きのフィールド名を使用します。
ルールは決して trueとして評価されません。	ルールの IF 句で参照されるフィールドは、ルールの評価時までにまだ書き込まれていません。	フィールドの書き込みを担当するタスクが、現在のステージまたは前のステージ内で完了することを確認します。
エンティティ セレクターに変数が表示されません。	このフィールドは、デプロイされたバージョンのケース エンティティ スキーマでは定義されていません。	フィールドをスキーマに追加し、ケースプランを再公開して再展開します。
入力フィールドは処理中に上書きされます。	タスクの出力マッピングは、入力フィールドを対象としています。	入力フィールドを対象とする出力マッピングを削除します。スキーマで読み取り専用のドキュメント入力フィールド。

制限事項

• Data Fabric でのネイティブのケース エンティティのサポートはまだ利用できません。手順 2 で説明した 3 つのソーシング オプションのいずれかを使用します。
• writtenBy注釈は、設計時のドキュメント規則です。実行時には、単一書き込みの制約は適用されません。開発者は、レビューを通じてフィールドの所有権を確認する必要があります。
• ケースのユーザー ロールとアクセスのサポート (特定のエンティティ フィールドを編集できるペルソナの制限) はまだ利用できません。

次のステップ

• プライマリステージとセカンダリステージをモデル化する方法 — エンティティフィールドを消費するステージルールを設定する方法について説明します。
• 入力および出力マッピングの参照 — エンティティフィールドをタスクパラメータにワイヤリングするための詳細なリファレンス。
• Maestro Case tutorial: Property insurance claims — これらのスキーマ設計の原則を完全なケース プランに適用するエンドツーエンドのチュートリアルです。