sf-industry-commoncore-datamapper

sf-industry-commoncore-datamapper：OmniStudio Data Mapper の作成と検証

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

主な責任

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

---

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

sf-industry-commoncore-omnistudio-analyze -> sf-industry-commoncore-datamapper -> sf-industry-commoncore-integration-procedure -> sf-industry-commoncore-omniscript -> sf-industry-commoncore-flexcard（現在の位置：sf-industry-commoncore-datamapper）

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

---

主な知見

知見	詳細
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 レコードを定義します（名前、タイプ、有効ステータス）
2. OmniDataTransformItem レコードを定義します（フィールドマッピング、入力／出力パス）
3. Extract タイプのクエリフィルター、ソート順、上限を設定します
4. Load タイプのルックアップマッピングとデフォルト値を設定します
5. マッピングしたすべてのフィールドについて、フィールドレベルセキュリティを検証します

レビューの場合：

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

検証の実行：

Score: XX/100 Rating
|- Design & Naming: XX/20
|- Field Mapping: XX/25
|- Data Integrity: XX/25
|- Performance: XX/15
|- Documentation: XX/15

---

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

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	upsert キーまたは重複ルールへの考慮がない	気付かないままデータが破損する、レコードが重複する

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

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

---

フェーズ 4：デプロイ

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

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

デプロイ後：ターゲット組織で Data Mapper を有効にします。OmniStudio Designer に表示されることを確認します。

---

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

完了サマリー：

Data Mapper Complete: [Name]
  Type: [Extract|Transform|Load|Turbo Extract]
  Target Object(s): [Object1, Object2]
  Field Count: [N mapped fields]
  Validation: PASSED (Score: XX/100)

Next Steps: Test in Integration Procedure, verify data output, monitor performance

テストチェックリスト：

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

---

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

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

しきい値：✅ 90 以上（デプロイ） | ⚠️ 67～89（レビュー） | ❌ 67 未満（ブロック — 修正が必要）

---

CLI コマンド

既存の Data Mapper をクエリする

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

Data Mapper のフィールドマッピングをクエリする

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

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

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

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

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

---

スキル間の連携

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

sf-industry-commoncore-datamapper から	スキルへの連携先	タイミング
sf-industry-commoncore-datamapper	-> sf-industry-commoncore-integration-procedure	「この Data Mapper を呼び出す Integration Procedure を作成する」
sf-industry-commoncore-datamapper	-> sf-deploy	「Data Mapper を対象組織にデプロイする」
sf-industry-commoncore-datamapper	-> sf-industry-commoncore-omniscript	「Data Mapper の出力を OmniScript に接続する」
sf-industry-commoncore-datamapper	-> sf-industry-commoncore-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 を文書化します

---

メモ

• メタデータ型：OmniDataTransform（DataRaptor ではありません。レガシー名は非推奨です）
• API バージョン：OmniStudio マネージドパッケージまたは Industries Cloud が必要です
• スコアリング：スコアが 67 未満の場合、デプロイをブロックします
• 依存関係（任意）：sf-deploy、sf-metadata、sf-industry-commoncore-omnistudio-analyze、sf-industry-commoncore-integration-procedure
• Turbo Extract の制限事項：数式項目、関連リスト、集計クエリ、ポリモーフィック項目には対応していません
• 有効化：Integration Procedure から呼び出せるようにするには、デプロイ後に Data Mapper を有効化する必要があります
• ドラフトの DM は取得できません：sf project retrieve start -m OmniDataTransform:<Name> が機能するのは、有効化済みの Data Mapper のみです。ドラフトの DM では「Entity cannot be found」が返されます。
• Data API による作成：OmniDataTransform および OmniDataTransformItem レコードを作成するには、sf api request rest --method POST --body @file.json を使用します。sf data create record --values フラグは、テキストエリア項目の JSON を処理できません。先に JSON 本文を一時ファイルに書き込んでください。
• 外部キー項目名：OmniDataTransformItem の親参照項目は OmniDataTransformId ではなく、OmniDataTransformationId（「Transformation」の全語）です。

---

ライセンス

MIT ライセンス。 Copyright (c) 2026 David Ryan (weytani)