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 を使用または供給する関連 OmniStudio コンポーネント (Integration Procedure、OmniScript、FlexCard) を特定
4. 検証とスコアリング: 5 つのカテゴリに対して Data Mapper 設定をスコアリング (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 vs Turbo Extract	Extract は関係クエリを使用する標準 SOQL を使用します。Turbo Extract はサーバーサイドコンパイルされたクエリを使用し、読み取り集約、高容量シナリオに対応 (10 倍以上高速)。Turbo Extract は数式フィールド、関連リスト、書き込み操作をサポートしません。
Transform はメモリ内	Transform Data Mapper はメモリ内で完全に動作し、DML または SOQL をサポートしません。Integration Procedure のステップ間でデータ構造を再構成するために使用します。JSON-JSON 変換、フィールド名変更、データフラット化に使用します。
Load = DML	Load Data Mapper は insert、update、upsert、または delete 操作を実行します。適切な FLS チェックとエラーハンドリングが必要です。本番環境に Load Data Mapper をデプロイする前に必ずフィールドレベルセキュリティを検証してください。
OmniDataTransform メタデータ	Data Mapper は OmniDataTransform および OmniDataTransformItem レコードとして保存されます。レガシー DataRaptor API 名ではなく、これらのメタデータ型名を使用して取得とデプロイを行います。

---

ワークフロー (5 段階パターン)

フェーズ 1: 要件収集

ユーザーに以下を確認してください:

• Data Mapper タイプ (Extract、Transform、Load、Turbo Extract)
• ターゲット Salesforce オブジェクトおよびフィールド
• ターゲット org エイリアス
• 使用するコンポーネント (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	データの書き込み (insert、update、upsert、delete)	DR_Load_	はい	いいえ

命名形式: [Prefix][Object]_[Purpose] (PascalCase を使用)

例:

• 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 レコードを定義 (Name、Type、Active ステータス)
2. OmniDataTransformItem レコードを定義 (フィールドマッピング、入力/出力パス)
3. Extract タイプのクエリフィルター、ソート順、制限を設定
4. Load タイプの参照マッピングとデフォルト値を設定
5. マップされたすべてのフィールドのフィールドレベルセキュリティを検証

レビューの場合:

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

検証を実行:

スコア: XX/100 評価
|- 設計と命名: XX/20
|- フィールドマッピング: XX/25
|- データ整合性: XX/25
|- パフォーマンス: XX/15
|- ドキュメント: XX/15

---

生成ガードレール (必須)

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

以下のパターンのいずれかが生成される場合、停止してユーザーに質問してください:

「[パターン] に気づきました。これにより [問題] が発生します。以下のどちらを選択しますか: A) [正しいパターン] を使用するようにリファクタリング 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 スキルを使用: 「Deploy OmniDataTransform [Name] to [target-org] with --dry-run」

ステップ 2: デプロイ (検証が成功した場合のみ) sf-deploy スキルを使用: 「Proceed with actual deployment to [target-org]」

デプロイ後: ターゲット org で Data Mapper をアクティブ化します。OmniStudio Designer に表示されることを確認します。

---

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

完了サマリー:

Data Mapper 完了: [Name]
  タイプ: [Extract|Transform|Load|Turbo Extract]
  ターゲットオブジェクト: [Object1, Object2]
  フィールド数: [N 個のマップ済みフィールド]
  検証: PASSED (スコア: XX/100)

次のステップ: Integration Procedure でテスト、データ出力を検証、パフォーマンスを監視

テストチェックリスト:

• OmniStudio Designer でデータ出力をプレビュー
• フィールドマッピングが期待される JSON 構造を生成することを確認
• 代表的なデータ容量でテスト (1 レコードだけではなく)
• 制限付きプロファイルユーザーで FLS 強制を検証
• 使用する Integration Procedure/OmniScript が正しいデータ形状を受け取ることを確認

---

ベストプラクティス (100 点スコアリング)

カテゴリ	ポイント	主要ルール
設計と命名	20	正しいタイプ選択、命名は DR_[Type]_[Object]_[Purpose] 規約に従う、Data Mapper あたり単一責務
フィールドマッピング	25	明示的なフィールドリスト (ワイルドカードなし)、正しい入力/出力パス、適切な型変換、null-safe デフォルト値
データ整合性	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 をターゲット org にデプロイ」
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 (マスター詳細)	親レコードを最初に insert、その後、子レコードを別の Load ステップで insert、Integration Procedure でシーケンスをオーケストレーション
名前空間プリフィックス付きフィールド	フィールドパスに名前空間プリフィックスを含める (例: ns__Field__c)、プリフィックスがターゲット org と一致することを確認
マルチ通貨 org	CurrencyIsoCode を明示的にマップ、デフォルト通貨の仮定に依存しない
RecordType 依存マッピング	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 の制限: 数式フィールドなし、関連リストなし、集計クエリなし、ポリモーフィックフィールドなし
• アクティブ化: Data Mapper をデプロイ後、Integration Procedure から呼び出し可能にするためにアクティブ化する必要があります
• ドラフト DM を取得できない: sf project retrieve start -m OmniDataTransform:<Name> はアクティブな Data Mapper でのみ機能します。ドラフト DM は「Entity cannot be found」を返します。
• Data API 経由での作成: sf api request rest --method POST --body @file.json を使用して OmniDataTransform および OmniDataTransformItem レコードを作成します。sf data create record --values フラグは textarea フィールドの JSON を処理できません。最初に JSON 本体を一時ファイルに書き込みます。
• 外部キーフィールド名: OmniDataTransformItem の親参照は OmniDataTransformationId (完全な単語「Transformation」) で、OmniDataTransformId ではありません。

---

ライセンス

MIT ライセンス。 著作権 (c) 2026 David Ryan (weytani)