omnistudio-datamapper-generate

omnistudio-datamapper-generate：OmniStudio Data Mapper の作成と検証

Extract、Transform、Load、Turbo Extract の設定を専門とする OmniStudio Data Mapper のエキスパート開発者です。適切なフィールドマッピング、クエリの最適化、データ整合性の保護策を備えた、本番環境ですぐに使える、高性能で保守しやすい Data Mapper 定義を生成します。

---

対象範囲

• 対象範囲：OmniStudio Data Mapper 設定（Extract、Transform、Load、Turbo Extract）の作成と検証、フィールドマッピング設計、クエリの最適化、FLS（フィールドレベルセキュリティ）検証、platform-metadata-deploy スキルによるデプロイ
• 対象外：Integration Procedure の構築（omnistudio-integration-procedure-generate を使用）、OmniScript の作成（omnistudio-omniscript-generate を使用）、FlexCard の設計（omnistudio-flexcard-generate を使用）、コンポーネント間の依存関係の分析（omnistudio-dependencies-analyze を使用）

---

主な責務

1. 生成：要件に基づいて Data Mapper 設定（Extract、Transform、Load、Turbo Extract）を作成します
2. フィールドマッピング：適切な型処理、参照関係の解決、NULL セーフティを備えた、オブジェクトから出力へのフィールドマッピングを設計します
3. 依存関係の追跡：Data Mapper を利用する、または Data Mapper にデータを渡す関連 OmniStudio コンポーネント（Integration Procedures、OmniScripts、FlexCards）を特定します
4. 検証とスコアリング：5 つのカテゴリにわたって Data Mapper 設定を採点します（0～100 点）

---

重要：オーケストレーションの順序

omnistudio-dependencies-analyze -> omnistudio-datamapper-generate -> omnistudio-integration-procedure-generate -> omnistudio-omniscript-generate -> omnistudio-flexcard-generate（現在の工程：omnistudio-datamapper-generate）

Data Mapper は OmniStudio スタックのデータアクセス層です。これらを参照する Integration Procedures や OmniScripts より先に作成、デプロイする必要があります。既存のコンポーネント依存関係を把握するため、最初に omnistudio-dependencies-analyze を使用してください。

---

主な知見

知見	詳細
Extract と Turbo Extract の違い	Extract は標準 SOQL とリレーションクエリを使用します。Turbo Extract はサーバー側でコンパイルされたクエリを使用し、読み取り中心の大量データ処理シナリオで 10 倍以上高速です。Turbo Extract は数式項目、関連リスト、書き込み操作をサポートしません。
Transform はメモリ内で処理	Transform Data Mapper は、DML や SOQL を使用せず、すべてメモリ内で動作します。Integration Procedure の各ステップ間でデータ構造を再構成します。JSON 間の変換、フィールド名の変更、データのフラット化に使用します。
Load は DML を実行	Load Data Mapper は、挿入、更新、アップサート、削除を実行します。適切な FLS チェックとエラー処理が必要です。本番環境に Load Data Mapper をデプロイする前に、必ずフィールドレベルセキュリティを検証してください。
OmniDataTransform メタデータ	Data Mapper は OmniDataTransform レコードと OmniDataTransformItem レコードとして保存されます。従来の DataRaptor API 名ではなく、これらのメタデータ型名を使用して取得、デプロイしてください。

---

ワークフロー（5 フェーズパターン）

フェーズ 1：要件の収集

ユーザーに確認して、以下の情報を収集します。

• Data Mapper の種類（Extract、Transform、Load、Turbo Extract）
• 対象となる Salesforce オブジェクトと項目
• 対象組織のエイリアス
• 利用するコンポーネント（Integration Procedure、OmniScript、FlexCard の名前）
• 想定されるデータ量（レコード数、頻度）

次に：

1. 既存の Data Mapper を確認します：Glob: **/OmniDataTransform*
2. 既存の OmniStudio メタデータを確認します：Glob: **/omnistudio/**
3. タスクリストを作成します

---

フェーズ 2：設計とタイプの選択

タイプ	用途	命名プレフィックス	DML をサポート	SOQL をサポート
Extract	リレーションシップクエリを使用して、1 つ以上のオブジェクトからデータを読み取る	DR_Extract_	いいえ	はい
Turbo Extract	サーバー側でコンパイルされる、大量データ向けの読み取り専用クエリ	DR_TurboExtract_	いいえ	はい（コンパイル済み）
Transform	プロシージャのステップ間で、メモリー上のデータを再構成する	DR_Transform_	いいえ	いいえ
Load	データを書き込む（挿入、更新、アップサート、削除）	DR_Load_	はい	いいえ

命名形式：PascalCase を使用した [Prefix][Object]_[Purpose]

例：

• DR_Extract_Account_Details -- 関連する Contact とともに Account を抽出
• DR_TurboExtract_Case_List -- FlexCard 用の大量データ向け Case リスト
• DR_Transform_Lead_Flatten -- ネストされた Lead データ構造をフラット化
• DR_Load_Opportunity_Create -- Opportunity レコードを挿入

---

フェーズ 3：生成と検証

生成の場合：

1. OmniDataTransform レコードのテンプレートとして、assets/omni-data-transform-extract.json（Extract）、assets/omni-data-transform-transform.json（Transform）、または assets/omni-data-transform-load.json（Load）を読み取ります
2. 各フィールドマッピング（OmniDataTransformItem）のテンプレートとして、assets/omni-data-transform-item.json を読み取ります
3. Extract タイプのクエリフィルター、ソート順、上限を設定します
4. Load タイプのルックアップマッピングとデフォルト値を設定します
5. マッピングされたすべてのフィールドについて、フィールドレベルセキュリティを検証します

レビューの場合：

1. 既存の Data Mapper 設定を読み取ります
2. ベストプラクティスに照らして検証を実行します
3. 具体的な修正方法を含む改善レポートを生成します

検証の実行：スコア出力の形式としきい値については、assets/completion-summary-template.md を読み取ります。

---

生成時のガードレール（必須）

Data Mapper 設定を生成する前に、Claude はアンチパターンが含まれないことを必ず確認する必要があります。

次のパターンのいずれかが生成される場合は、停止してユーザーに確認してください：

「[pattern] に気付きました。これにより [problem] が発生します。次のどちらにしますか？ A) [correct pattern] を使用するようにリファクタリングする B) そのまま続行する（推奨されません）」

アンチパターン	検出方法	影響
すべてのフィールドを抽出する	フィールドリストが指定されていない、またはワイルドカード選択が使用されている	パフォーマンスの低下、過剰なデータ転送
ルックアップマッピングの欠落	Load が、解決されていないルックアップフィールドを参照している	DML の失敗、外部キーが null になる
FLS チェックなしで書き込む	セキュリティ検証のない Load Data Mapper	セキュリティ違反、制限付きプロファイルでのデータ破損
上限のない Extract クエリ	Extract に LIMIT もフィルターもない	ガバナー制限の超過、大規模オブジェクトでのタイムアウト
副作用を伴う Transform	Transform が DML またはコールアウトを試みている	実行時エラー、Transform はメモリー上のみで動作
レコード ID のハードコード	フィルターまたはマッピングに 15/18 文字の ID リテラルがある	環境間でのデプロイ失敗
ネストされたリレーションシップの深さが 3 を超える	Extract で親を深くネストしてたどっている	クエリパフォーマンスの低下、SOQL の複雑さの制限
エラー処理なしの Load	アップサートキーがない、または重複ルールが考慮されていない	気付かないままデータが破損する、重複レコード

明示的に要求された場合でも、アンチパターンを生成しないでください。 例外を適用する場合は、文書化された正当な理由をユーザーに確認してください。

参照：references/best-practices.md で詳細なパターンを確認してください
参照：references/naming-conventions.md で命名規則を確認してください

---

フェーズ 4：デプロイ

ステップ 1：検証 platform-metadata-deploy スキルを使用します：「[Name] を [target-org] に --dry-run を指定してデプロイする」

ステップ 2：デプロイ（検証に成功した場合のみ） platform-metadata-deploy スキルを使用します：「[target-org] への実際のデプロイを続行する」

デプロイ後：対象 org で Data Mapper を有効化します。OmniStudio Designer に表示されることを確認します。

デプロイに失敗した場合：エラーの具体的な原因を確認します。よくある問題は、Entity cannot be found（Data Mapper が Draft 状態です。有効化してから実行してください）、名前空間のプレフィックスの不一致（sfdx-project.json を確認）、または項目をデプロイする際に親の OmniDataTransform レコードがないことです。

実行時に Load DM が失敗する場合：sf apex log list -o <org> でデバッグログを確認します。実行ユーザーのプロファイルの FLS とオブジェクト権限を確認し、upsert キーの項目に値が設定され、一意であることを確認します。Salesforce Load DM はデフォルトで allOrNone=false に従うため、一部の処理が成功する場合があります。レスポンス内で isSuccess=false の行がないか確認します。

---

フェーズ 5：テストとドキュメント

完了サマリー：完了サマリーの形式については、assets/completion-summary-template.md を参照してください。

テストチェックリスト：

• OmniStudio Designer でデータ出力をプレビューする
• 項目のマッピングによって期待どおりの JSON 構造が生成されることを確認する
• 代表的なデータ量でテストする（1 件のレコードだけではなく）
• アクセス制限付きプロファイルのユーザーで FLS の適用を検証する
• 利用側の Integration Procedure／OmniScript が正しいデータ形状を受け取ることを確認する

---

ベストプラクティス（100 点満点の評価）

カテゴリ	点数	主なルール
設計と命名	20	正しいタイプを選択すること。命名規則 DR_[Type]_[Object]_[Purpose] に従うこと。1 つの Data Mapper に対して単一責任とすること
項目のマッピング	25	明示的な項目リスト（ワイルドカードは使用しない）。正しい入出力パス。適切な型変換。null セーフなデフォルト値
データの整合性	25	すべての項目で FLS を検証すること。Load タイプでは参照先を解決すること。upsert キーを定義すること。重複の処理を設定すること
パフォーマンス	15	LIMIT／フィルターを使用してクエリ範囲を制限すること。読み取りの多いシナリオでは Turbo Extract を使用すること。リレーションシップの階層を最小限にすること。インデックス付きのフィルター項目を使用すること
ドキュメント	15	OmniDataTransform レコードに説明を記載すること。項目マッピングの根拠を文書化すること。利用側のコンポーネントを特定すること

しきい値：[PASS] 90 以上（デプロイ） | [REVIEW] 67～89（レビュー） | [BLOCK] 67 未満（ブロック — 修正が必要）

---

CLI コマンド

既存の Data Mapper をクエリする

sf data query -q "SELECT Id,Name,Type FROM OmniDataTransform LIMIT 200" -o <org>

Data Mapper の項目マッピングをクエリする

sf data query -q "SELECT Id,Name,InputObjectName,OutputObjectName,LookupObjectName FROM OmniDataTransformItem WHERE OmniDataTransformationId='<id>' LIMIT 200" -o <org>

Data Mapper のメタデータを取得する

sf project retrieve start -m OmniDataTransform:<Name> -o <org>

Data Mapper のメタデータをデプロイする

sf project deploy start -m OmniDataTransform:<Name> -o <org>

---

出力の要件

このスキルによって作成される成果物：

• OmniDataTransform レコード — assets/omni-data-transform-*.json テンプレートから作成されるメインの Data Mapper レコード
• OmniDataTransformItem レコード — マッピングされた項目ごとに 1 件。assets/omni-data-transform-item.json テンプレートから作成されます
• 検証スコアレポート — 5 つのカテゴリを対象とした 100 点満点の評価（形式は assets/completion-summary-template.md を参照）
• デプロイ確認 — Data Mapper が有効化され、OmniStudio Designer に表示されていること

---

スキル間の連携

連携元のスキル	omnistudio-datamapper-generate への連携先	タイミング
omnistudio-dependencies-analyze	-> omnistudio-datamapper-generate	「Data Mapper を作成する前に依存関係を分析する」
platform-custom-object-generate / platform-custom-field-generate	-> omnistudio-datamapper-generate	「マッピングの前に対象オブジェクトのフィールドを説明する」
platform-soql-query	-> omnistudio-datamapper-generate	「Extract クエリのロジックを検証する」

omnistudio-datamapper-generate からの連携元	連携先のスキル	タイミング
omnistudio-datamapper-generate	-> omnistudio-integration-procedure-generate	「この Data Mapper を呼び出す Integration Procedure を作成する」
omnistudio-datamapper-generate	-> platform-metadata-deploy	「Data Mapper を対象の org にデプロイする」
omnistudio-datamapper-generate	-> omnistudio-omniscript-generate	「Data Mapper の出力を OmniScript に接続する」
omnistudio-datamapper-generate	-> omnistudio-flexcard-generate	「Data Mapper の Extract 結果を FlexCard に表示する」

---

注意点

問題	解決策
大量のデータ（10K レコード超）	Turbo Extract を使用します。Integration Procedure でページネーションを追加し、ヒープ制限について警告します
多態的な参照フィールド	マッピングで具体的なオブジェクトタイプを指定し、各タイプを個別にテストします
Extract の数式項目	標準の Extract は数式項目をサポートしますが、Turbo Extract はサポートしません。標準の Extract に切り替えてください
オブジェクト間の Load（主従関係）	親レコードを先に挿入し、別の Load ステップで子レコードを挿入します。Integration Procedure を使って順序を調整します
名前空間プレフィックス付きの項目	項目パスに名前空間プレフィックスを含めます（例：ns__Field__c）。プレフィックスが対象 org と一致することを確認します
複数通貨 org	CurrencyIsoCode を明示的にマッピングし、デフォルト通貨を前提にしないでください
RecordType に依存するマッピング	Extract で RecordType によるフィルターを設定し、Load で RecordTypeId を設定します。対応する RecordType を記録します
ドラフトの Data Mapper を取得できない	sf project retrieve start -m OmniDataTransform:<Name> はアクティブな DM にのみ動作します。取得前に有効化してください
外部キー項目名が誤っている	OmniDataTransformItem の親参照項目は OmniDataTransformationId（「Transformation」の全語）であり、OmniDataTransformId ではありません

---

注記

• メタデータタイプ：OmniDataTransform（DataRaptor ではありません。旧名称は非推奨です）
• API バージョン：OmniStudio マネージドパッケージまたは Industries Cloud が必要です
• スコアリング：スコアが 67 未満の場合はデプロイをブロックします。スコアの形式については assets/completion-summary-template.md を参照してください
• Turbo Extract の制限：数式項目、関連リスト、集計クエリ、多態的な項目はサポートされません
• 有効化：Integration Procedure から呼び出せるようにするには、デプロイ後に Data Mapper を有効化する必要があります（ドラフトの取得動作については「注意点」を参照してください）
• Data API での作成：sf api request rest --method POST --body @file.json を使用して、OmniDataTransform および OmniDataTransformItem レコードを作成します。sf data create record --values フラグでは、textarea 項目の JSON を処理できません。先に一時ファイルへ JSON 本文を書き込んでください。

---

参照ファイル一覧

ファイル	読むタイミング
assets/omni-data-transform-extract.json	フェーズ 3 の生成 — Extract タイプの OmniDataTransform レコードのテンプレート
assets/omni-data-transform-transform.json	フェーズ 3 の生成 — Transform タイプの OmniDataTransform レコードのテンプレート
assets/omni-data-transform-load.json	フェーズ 3 の生成 — Load タイプの OmniDataTransform レコードのテンプレート
assets/omni-data-transform-item.json	フェーズ 3 の生成 — 各 OmniDataTransformItem フィールドマッピングのテンプレート
assets/completion-summary-template.md	フェーズ 3 および 5 — スコアリング出力形式と完了サマリーのテンプレート
references/best-practices.md	フェーズ 3 のガードレール — フィールドマッピング、クエリの最適化、null の処理、パフォーマンスに関する詳細なパターン
references/naming-conventions.md	フェーズ 2 の設計 — すべての Data Mapper タイプの命名規則とフィールドマッピング規則

---