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

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

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

Examples:

• DRExtractAccount_Details -- Extract Account with related Contacts
• DRTurboExtractCase_List -- High-volume Case list for FlexCard
• DRTransformLead_Flatten -- Flatten nested Lead data structure
• DRLoadOpportunity_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 filters, sort order, and limits for Extract types
4. Set up lookup mappings and default values for Load types
5. Validate field-level security for all mapped fields

For Review:

1. Read existing Data Mapper configuration
2. Run validation against best practices
3. Generate improvement report with specific fixes

Run Validation: Read assets/completion-summary-template.md for the scoring output format and thresholds.

Generation Guardrails (MANDATORY)

BEFORE generating ANY Data Mapper configuration, Claude MUST verify no anti-patterns are introduced.

If ANY of these patterns would be generated, STOP and ask the user:

"I noticed [pattern]. This will cause [problem]. Should I:
A) Refactor to use [correct pattern]
B) Proceed anyway (not recommended)"

DO NOT generate anti-patterns even if explicitly requested. Ask user to confirm the exception with documented justification.

See: [references/best-practices.md](references/best-practices.md) for detailed patterns See: [references/naming-conventions.md](references/naming-conventions.md) for naming rules

Phase 4: Deployment

Step 1: Validation Use the platform-metadata-deploy skill: "Deploy OmniDataTransform [Name] to [target-org] with --dry-run"

Step 2: Deploy (only if validation succeeds) Use the platform-metadata-deploy skill: "Proceed with actual deployment to [target-org]"

Post-Deploy: Activate the Data Mapper in the target org. Verify it appears in OmniStudio Designer.

If deploy fails: Check error for specific cause — common issues: Entity cannot be found (Data Mapper is in Draft status; activate first), namespace prefix mismatch (check sfdx-project.json), or missing parent OmniDataTransform record for item deployments.

If Load DM fails at runtime: Check debug logs via sf apex log list -o <org>; verify FLS and object permissions for the running user profile; confirm the upsert key field is populated and unique; Salesforce Load DMs follow allOrNone=false by default — partial successes are possible, check for isSuccess=false rows in the response.

Phase 5: Testing & Documentation

Completion Summary: Read assets/completion-summary-template.md for the completion summary format.

Testing Checklist:

• Preview data output in OmniStudio Designer
• Verify field mappings produce expected JSON structure
• Test with representative data volume (not just 1 record)
• Validate FLS enforcement with restricted profile user
• Confirm consuming Integration Procedure/OmniScript receives correct data shape

Best Practices (100-Point Scoring)

Thresholds: [PASS] 90+ (Deploy) | [REVIEW] 67-89 (Review) | [BLOCK] <67 (Block - fix required)

CLI Commands

Query Existing Data Mappers

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

Query Data Mapper Field Mappings

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

Retrieve Data Mapper Metadata

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

Deploy Data Mapper Metadata

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

Output Expectations

Deliverables produced by this skill:

• OmniDataTransform record — main Data Mapper record built from assets/omni-data-transform-*.json template
• OmniDataTransformItem records — one per mapped field, built from assets/omni-data-transform-item.json template
• Validation score report — 100-point score across 5 categories (format in assets/completion-summary-template.md)
• Deployment confirmation — Data Mapper activated and visible in OmniStudio Designer

Cross-Skill Integration

Gotchas

Notes

• Metadata Type: OmniDataTransform (not DataRaptor — legacy name deprecated)
• API Version: Requires OmniStudio managed package or Industries Cloud
• Scoring: Block deployment if score < 67; read assets/completion-summary-template.md for score format
• Turbo Extract Limitations: No formula fields, no related lists, no aggregate queries, no polymorphic fields
• Activation: Data Mappers must be activated after deployment to be callable from Integration Procedures (see Gotchas for draft retrieval behavior)
• Creating via Data API: Use sf api request rest --method POST --body @file.json to create OmniDataTransform and OmniDataTransformItem records. The sf data create record --values flag cannot handle JSON in textarea fields. Write the JSON body to a temp file first.

Reference File Index