/omnistudio-datamapper-generate

name: omnistudio-datamapper-generate
description: "OmniStudio Data Mapper (formerly DataRaptor) creation and validation with 100-point scoring. Use when building Extract, Transform, Load, or Turbo Extract Data Mappers, mapping Salesforce object fields, or reviewing existing Data Mapper configurations. TRIGGER when: user creates Data Mappers, configures field mappings, works with OmniDataTransform metadata, or asks about DataRaptor/Data Mapper patterns. DO NOT TRIGGER when: building Integration Procedures (use omnistudio-integration-procedure-generate), authoring OmniScripts (use omnistudio-omniscript-generate), or analyzing cross-component dependencies (use omnistudio-dependencies-analyze)."
metadata:
  cliTools:
    - tool: ["sf"]
      semver: ">=2.0.0"
  relatedSkills:
    - "omnistudio-dependencies-analyze"
    - "omnistudio-flexcard-generate"
    - "omnistudio-integration-procedure-generate"
    - "omnistudio-omniscript-generate"
    - "platform-custom-field-generate"
    - "platform-custom-object-generate"
    - "platform-metadata-deploy"
    - "platform-soql-query"
  version: "1.0"
  domains: ["OmniStudio"]
  minApiVersion: "60.0"

omnistudio-datamapper-generate: OmniStudio Data Mapper Creation and Validation

Expert OmniStudio Data Mapper developer specializing in Extract, Transform, Load, and Turbo Extract configurations. Generate production-ready, performant, and maintainable Data Mapper definitions with proper field mappings, query optimization, and data integrity safeguards.

---

Scope

• **In scope**: Creating and validating OmniStudio Data Mapper configurations (Extract, Transform, Load, Turbo Extract); field mapping design; query optimization; FLS (Field-Level Security) validation; deployment via platform-metadata-deploy skill
• **Out of scope**: Building Integration Procedures (use `omnistudio-integration-procedure-generate`), authoring OmniScripts (use `omnistudio-omniscript-generate`), designing FlexCards (use `omnistudio-flexcard-generate`), analyzing cross-component dependencies (use `omnistudio-dependencies-analyze`)

---

Core Responsibilities

1. **Generation**: Create Data Mapper configurations (Extract, Transform, Load, Turbo Extract) from requirements 2. **Field Mapping**: Design object-to-output field mappings with proper type handling, lookup resolution, and null safety 3. **Dependency Tracking**: Identify related OmniStudio components (Integration Procedures, OmniScripts, FlexCards) that consume or feed Data Mappers 4. **Validation & Scoring**: Score Data Mapper configurations against 5 categories (0-100 points)

---

CRITICAL: Orchestration Order

**omnistudio-dependencies-analyze -> omnistudio-datamapper-generate -> omnistudio-integration-procedure-generate -> omnistudio-omniscript-generate -> omnistudio-flexcard-generate** (you are here: omnistudio-datamapper-generate)

Data Mappers are the data access layer of the OmniStudio stack. They must be created and deployed before Integration Procedures or OmniScripts that reference them. Use omnistudio-dependencies-analyze FIRST to understand existing component dependencies.

---

Key Insights

| Insight | Details | |---------|---------| | **Extract vs Turbo Extract** | Extract uses standard SOQL with relationship queries. Turbo Extract uses server-side compiled queries for read-heavy, high-volume scenarios (10x+ faster). Turbo Extract does not support formula fields, related lists, or write operations. | | **Transform is in-memory** | Transform Data Mappers operate entirely in memory with no DML or SOQL. They reshape data structures between steps in an Integration Procedure. Use for JSON-to-JSON transformations, field renaming, and data flattening. | | **Load = DML** | Load Data Mappers perform insert, update, upsert, or delete operations. They require proper FLS checks and error handling. Always validate field-level security before deploying Load Data Mappers to production. | | **OmniDataTransform metadata** | Data Mappers are stored as OmniDataTransform and OmniDataTransformItem records. Retrieve and deploy using these metadata type names, not the legacy DataRaptor API names. |

---

Workflow (5-Phase Pattern)

Phase 1: Requirements Gathering

**Ask the user** to gather:

• Data Mapper type (Extract, Transform, Load, Turbo Extract)
• Target Salesforce object(s) and fields
• Target org alias
• Consuming component (Integration Procedure, OmniScript, or FlexCard name)
• Data volume expectations (record counts, frequency)

**Then**: 1. Check existing Data Mappers: `Glob: **/OmniDataTransform*` 2. Check existing OmniStudio metadata: `Glob: **/omnistudio/**` 3. Create a task list

---

Phase 2: Design & Type Selection

| Type | Use Case | Naming Prefix | Supports DML | Supports SOQL | |------|----------|---------------|--------------|---------------| | **Extract** | Read data from one or more objects with relationship queries | `DR_Extract_` | No | Yes | | **Turbo Extract** | High-volume read-only queries, server-side compiled | `DR_TurboExtract_` | No | Yes (compiled) | | **Transform** | In-memory data reshaping between procedure steps | `DR_Transform_` | No | No | | **Load** | Write data (insert, update, upsert, delete) | `DR_Load_` | Yes | No |

**Naming Format**: `[Prefix][Object]_[Purpose]` using PascalCase

**Examples**:

• `DR_Extract_Account_Details` -- Extract Account with related Contacts
• `DR_TurboExtract_Case_List` -- High-volume Case list for FlexCard
• `DR_Transform_Lead_Flatten` -- Flatten nested Lead data structure
• `DR_Load_Opportunity_Create` -- Insert Opportunity records

---

Phase 3: Generation & Validation

**For Generation**: 1. Read `assets/omni-data-transform-extract.json` (Extract), `assets/omni-data-transform-transform.json` (Transform), or `assets/omni-data-transform-load.json` (Load) for the OmniDataTransform record template 2. Read `assets/omni-data-transform-item.json` for each field mapping (OmniDataTransformItem) template 3. Configure query filte