building-omnistudio-datamapper

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

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

---

対象範囲

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

---

主な責務

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 点）

---

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

analyzing-omnistudio-dependencies -> building-omnistudio-datamapper -> building-omnistudio-integration-procedure -> building-omnistudio-omniscript -> building-omnistudio-flexcard（現在の対象：building-omnistudio-datamapper）

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

---

主なポイント

ポイント	詳細
Extract と Turbo Extract の違い	Extract は標準的な SOQL とリレーションクエリを使用します。Turbo Extract はサーバー側でコンパイルされたクエリを使用し、読み取りが中心の大量データ処理に適しています（10 倍以上高速）。Turbo Extract は数式項目、関連リスト、書き込み操作をサポートしていません。
Transform はインメモリで処理	Transform Data Mapper は、DML や SOQL を使用せず、すべてインメモリで処理します。Integration Procedure のステップ間でデータ構造を組み替えます。JSON から 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：検証 deploying-metadata スキルを使用します：「OmniDataTransform [Name] を [target-org] に --dry-run でデプロイする」

ステップ 2：デプロイ（検証が成功した場合のみ） deploying-metadata スキルを使用します：「[target-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 とオブジェクト権限を確認します。アップサートキーの項目に値が設定され、一意であることを確認します。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] に従う。Data Mapper 1 つにつき単一責任とする
項目マッピング	25	項目リストを明示する（ワイルドカードは使用しない）。入力／出力パスを正しく設定する。適切な型変換を行う。null 安全なデフォルト値を設定する
データ整合性	25	すべての項目で FLS を検証する。Load タイプではルックアップを解決する。アップサートキーを定義する。重複処理を設定する
パフォーマンス	15	LIMIT／フィルターを使ってクエリの範囲を制限する。読み取りが多いシナリオでは Turbo Extract を使用する。リレーションの階層を最小限にする。インデックス付きのフィルター項目を使用する
ドキュメント	15	OmniDataTransform レコードに説明を記載する。項目マッピングの根拠を文書化する。呼び出し元のコンポーネントを特定する

しきい値：✅ 90 点以上（デプロイ） | ⚠️ 67～89 点（レビュー） | ❌ 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 に表示されていること

---

スキル間の連携

スキル元	building-omnistudio-datamapper への連携	タイミング
analyzing-omnistudio-dependencies	-> building-omnistudio-datamapper	「Data Mapper を作成する前に依存関係を分析する」
generating-custom-object / generating-custom-field	-> building-omnistudio-datamapper	「マッピングする前に対象オブジェクトの項目を説明する」
querying-soql	-> building-omnistudio-datamapper	「Extract クエリのロジックを検証する」

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

---

注意事項

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

---

メモ

• メタデータ型：OmniDataTransform（DataRaptor ではありません。旧称は非推奨です）
• API バージョン：OmniStudio マネージドパッケージまたは Industries Cloud が必要です
• スコアリング：スコアが 67 未満の場合はデプロイをブロックします。スコアの形式については assets/completion-summary-template.md を参照してください
• Turbo Extract の制限：数式項目、関連リスト、集計クエリ、ポリモーフィック項目はサポートされません
• 有効化：Data Mapper はデプロイ後に有効化しないと Integration Procedure から呼び出せません（ドラフトの取得動作については「注意事項」を参照してください）
• 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 タイプの命名規則とフィールドマッピング規則

---