Sf Industry Commoncore Datamapper

sf-industry-commoncore-datamapper: 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.

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

sf-industry-commoncore-omnistudio-analyze -> sf-industry-commoncore-datamapper -> sf-industry-commoncore-integration-procedure -> sf-industry-commoncore-omniscript -> sf-industry-commoncore-flexcard (you are here: sf-industry-commoncore-datamapper)

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 sf-industry-commoncore-omnistudio-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:

• 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. Define the OmniDataTransform record (Name, Type, Active status) 2. Define OmniDataTransformItem records (field mappings, input/output paths) 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:

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

---

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 for detailed patterns See: references/naming-conventions.md for naming rules

---

Phase 4: Deployment

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

Step 2: Deploy (only if validation succeeds) Use the sf-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.

---

Phase 5: Testing & Documentation

Completion Summary:

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

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: ✅ 90+ (Deploy) | ⚠️ 67-89 (Review) | ❌ <67 (Block - fix required)

---

CLI Commands

Query Existing Data Mappers

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

Query Data Mapper Field Mappings

sf data query -q "SELECT Id,Name,InputObjectName,OutputObjectName,LookupObjectName FROM OmniDataTransformItem WHERE OmniDataTransformationId='<id>'" -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>

---

Cross-Skill Integration

---

Edge Cases

---

Notes

• Metadata Type: OmniDataTransform (not DataRaptor -- legacy name deprecated)
• API Version: Requires OmniStudio managed package or Industries Cloud
• Scoring: Block deployment if score < 67
• Dependencies (optional): sf-deploy, sf-metadata, sf-industry-commoncore-omnistudio-analyze, sf-industry-commoncore-integration-procedure
• 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
• Draft DMs can't be retrieved: sf project retrieve start -m OmniDataTransform:<Name> only works for active Data Mappers. Draft DMs return "Entity cannot be found".
• 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.
• Foreign key field name: The parent lookup on OmniDataTransformItem is OmniDataTransformationId (full word "Transformation"), not OmniDataTransformId.

---

License

MIT License. Copyright (c) 2026 David Ryan (weytani)

Credits & Acknowledgments

This skill was built upon the collective knowledge of the Salesforce OmniStudio community. We gratefully acknowledge the following projects, teams, and resources whose work informed the patterns and best practices in this skill.

---

Tools & Projects

sf-explorer/omnistudio-mcp-server

[github.com/sf-explorer/omnistudio-mcp-server](https://github.com/sf-explorer/omnistudio-mcp-server)

Key contributions:

• Dependency analysis patterns for OmniStudio components
• Cross-component relationship mapping (Data Mapper <-> Integration Procedure <-> OmniScript)
• Metadata querying patterns for OmniDataTransform records

@salesforce/omnistudio-mcp

Official Salesforce OmniStudio MCP Server

Key contributions:

• Canonical OmniStudio metadata type definitions
• Standard field mapping patterns and type structures
• OmniDataTransform and OmniDataTransformItem schema reference

---

Salesforce Engineering

Salesforce Industries Engineering

Key contributions:

• OmniStudio platform architecture and Data Mapper runtime
• OmniDataTransform metadata API and deployment model
• Turbo Extract server-side compilation engine
• DataRaptor to Data Mapper migration path and naming continuity

---

Educational Resources

OmniStudio Trailhead Modules

[trailhead.salesforce.com](https://trailhead.salesforce.com)

Key contributions:

• DataRaptor fundamentals and hands-on exercises
• Extract, Transform, and Load workflow patterns
• Integration Procedure and Data Mapper interaction models
• OmniStudio Developer certification preparation material

Relevant trails and modules:

• Build OmniStudio DataRaptors
• OmniStudio Integration Procedures
• OmniStudio Developer Certification Prep

---

Official Salesforce Resources

• OmniStudio Developer Guide: https://developer.salesforce.com/docs/atlas.en-us.omnistudio.meta/omnistudio/
• OmniStudio Trailhead: https://trailhead.salesforce.com/en/content/learn/trails/build-omnistudio-components
• Salesforce Industries Documentation: https://help.salesforce.com/s/articleView?id=sf.os_dataraptors.htm

---

Community Resources

Salesforce Stack Exchange

[salesforce.stackexchange.com](https://salesforce.stackexchange.com/)

• DataRaptor/Data Mapper Q&A and troubleshooting
• Performance optimization discussions
• Field mapping pattern solutions

Salesforce Ben

[salesforceben.com](https://www.salesforceben.com/)

• OmniStudio overview articles
• DataRaptor best practice guides
• Industries Cloud adoption guidance

---

Contributor

David Ryan (weytani)

Primary Contributor — GitHub

This sf-industry-commoncore-datamapper skill was contributed by David Ryan (weytani) as part of the Jaganpro/sf-skills skill library.

---

Special Thanks

To the Salesforce Industries and OmniStudio community -- consultants, developers, architects, and ISV partners -- for sharing practical knowledge about Data Mapper patterns, performance tuning, and production deployment strategies.

---

If we've missed anyone whose work influenced this skill, please let us know so we can add proper attribution.

<!-- Parent: sf-industry-commoncore-datamapper/SKILL.md -->

Data Mapper Best Practices

When to Use Each Type

Extract

Use Extract when:

• Reading data from one or more related Salesforce objects
• You need relationship queries (parent-to-child or child-to-parent)
• Formula fields are required in the output
• Data volume is moderate (under 10K records per execution)
• You need aggregate functions or complex filter logic

Do NOT use Extract when:

• Read volume exceeds 10K records consistently -- use Turbo Extract
• No SOQL is needed (data reshaping only) -- use Transform
• You are writing data -- use Load

Turbo Extract

Use Turbo Extract when:

• Read-heavy scenarios with high volume (10K+ records)
• Query is straightforward with indexed filter fields
• Formula fields are not required
• No related list (child-to-parent) queries are needed
• Performance is the primary concern (10x+ faster than standard Extract)

Do NOT use Turbo Extract when:

• Formula fields are needed in output
• Related list queries are required
• Aggregate queries (COUNT, SUM) are needed
• Polymorphic lookup fields are involved

Transform

Use Transform when:

• Reshaping JSON structures between Integration Procedure steps
• Renaming fields from one schema to another
• Flattening nested data structures
• Filtering or merging in-memory datasets
• No database interaction is needed

Do NOT use Transform when:

• Reading from or writing to Salesforce objects -- use Extract or Load
• Data needs to be persisted -- use Load

Load

Use Load when:

• Inserting, updating, upserting, or deleting Salesforce records
• Writing data collected from OmniScript input or external sources
• Synchronizing data from Integration Procedure callout responses

Do NOT use Load when:

• Reading data -- use Extract or Turbo Extract
• Reshaping data without persistence -- use Transform

---

Field Mapping Patterns

Explicit Field Selection

Always specify fields explicitly. Never rely on wildcard or "all fields" selection.

Good:  Account.Name, Account.Industry, Account.BillingCity
Bad:   Account.* (extracts all fields, wastes bandwidth and heap)

Input/Output Path Structure

Data Mapper fields use dot-notation paths for input and output:

Input Path:   AccountData.Name
Output Path:  Account.Name

For nested structures:

Input Path:   Response.data.accounts[0].name
Output Path:  AccountList.Name

Type Conversion Handling

Map fields with compatible types. Common conversions:

Lookup Resolution for Load

When loading records with lookup relationships:

1. Define a lookup mapping that resolves the external key to a Salesforce ID 2. Specify the lookup object and match field (e.g., Account.Name to resolve AccountId) 3. Handle cases where the lookup returns no match (set default or fail gracefully)

Field:         AccountId
Lookup Object: Account
Match Field:   Name
Input Path:    InputData.AccountName

---

Query Sequence Optimization

Filter Field Indexing

For Extract and Turbo Extract, filter on indexed fields whenever possible:

• Id (always indexed)
• Name (indexed on standard objects)
• CreatedDate (indexed)
• SystemModstamp (indexed)
• Custom fields marked as External ID or Unique
• Custom Index fields (request from admin if needed)

Filter Order

Place the most selective filter first to reduce the result set early:

Good:  WHERE Id = :recordId AND Status = 'Active'
Bad:   WHERE Status = 'Active' AND Id = :recordId

Relationship Query Depth

Limit relationship traversal to 2 levels for performance:

Good:  Account.Owner.Name (1 level)
Bad:   Account.Parent.Parent.Parent.Owner.Name (3+ levels)

Limit and Offset

Always set a LIMIT on Extract queries unless the consuming component guarantees a bounded input:

LIMIT 200    -- Standard batch size
LIMIT 2000   -- Maximum for most UI scenarios
LIMIT 10000  -- Absolute maximum, use only with pagination

---

Null Handling and Type Conversion

Default Values

Set default values for fields that may be null to prevent downstream errors:

Null-Safe Mapping

When mapping fields that may be null:

1. Set isNullable: true on the OmniDataTransformItem 2. Configure a default value where business logic requires one 3. Document which fields are expected to be null in certain scenarios 4. Test with records that have null values in mapped fields

---

Relationship Queries

Parent-to-Child (Subquery)

Extract supports parent-to-child relationship queries:

Object: Account
Fields: Name, Industry
Child Relationship: Contacts (Contact)
Child Fields: FirstName, LastName, Email

Output structure:

{
  "Name": "Acme Corp",
  "Industry": "Technology",
  "Contacts": [
    { "FirstName": "Jane", "LastName": "Doe", "Email": "jane@acme.com" }
  ]
}

Child-to-Parent (Lookup Traversal)

Extract supports child-to-parent traversal via dot notation:

Object: Contact
Fields: FirstName, LastName, Account.Name, Account.Industry

Output structure:

{
  "FirstName": "Jane",
  "LastName": "Doe",
  "AccountName": "Acme Corp",
  "AccountIndustry": "Technology"
}

Turbo Extract Limitations

Turbo Extract does NOT support:

• Child-to-parent relationship queries (subqueries)
• Formula fields
• Aggregate functions
• Polymorphic lookups (e.g., WhoId on Task)

---

Performance with Large Data Volumes

Batch Size Recommendations

Heap Size Management

Each Data Mapper execution contributes to the Apex heap limit (6 MB synchronous, 12 MB async):

• Map only the fields you need (reduces JSON payload size)
• Use Turbo Extract for large result sets (server-side processing reduces heap usage)
• Paginate results when total data exceeds 2 MB

Caching Strategy

For data that changes infrequently:

• Enable Platform Cache in the consuming Integration Procedure
• Set appropriate TTL (Time To Live) based on data change frequency
• Cache at the org partition level for shared reference data
• Cache at the session partition level for user-specific data

Monitoring

Track Data Mapper performance using:

sf data query -q "SELECT Id,Name,Type,LastModifiedDate FROM OmniDataTransform WHERE IsActive=true ORDER BY LastModifiedDate DESC" -o <org>

Review execution logs in OmniStudio Designer > Data Mapper > Preview to identify slow queries and excessive field counts.

<!-- Parent: sf-industry-commoncore-datamapper/SKILL.md -->

Data Mapper Naming Conventions

Type Prefixes

Every Data Mapper name starts with a type prefix that identifies its function at a glance.

The DR_ prefix stands for DataRaptor, the original product name. It remains the standard prefix for backward compatibility and team familiarity.

---

Object Naming

Format

DR_[Type]_[PrimaryObject]_[Purpose]

• Type: Extract, TurboExtract, Transform, Load
• PrimaryObject: The main Salesforce object (PascalCase, no underscores for standard objects)
• Purpose: A short, descriptive action or qualifier (PascalCase)

Standard Object Examples

Custom Object Examples

For custom objects, include the namespace prefix if applicable but drop the __c suffix from the name:

Multi-Object Data Mappers

When a Data Mapper spans multiple objects, name it after the primary (root) object:

DR_Extract_Account_WithContactsAndOpps
DR_Extract_Order_WithLineItems

If the Data Mapper truly serves a cross-cutting concern, use a domain name instead:

DR_Extract_CustomerProfile_Full
DR_Transform_ClaimSubmission_Normalize

---

Field Mapping Naming Patterns

Output Field Names

Output field names in the Data Mapper JSON response should follow these conventions:

Input Path Conventions

Input paths reference the source data structure. Use consistent dot notation:

AccountData.Name          -- Simple field
AccountData.Owner.Name    -- Relationship traversal
AccountData.Contacts[0]   -- Collection index
RequestBody.payload.id    -- Nested JSON path

Output Path Conventions

Output paths define the JSON structure returned by the Data Mapper:

AccountInfo.Name           -- Nested output
AccountInfo.OwnerName      -- Flattened relationship
AccountInfo.Contacts       -- Collection output
Result.status              -- Top-level result wrapper

---

Naming Anti-Patterns

---

Version and Environment Conventions

Data Mapper names should be environment-agnostic. Do not include environment identifiers in the name:

Bad:   DR_Extract_Account_Details_DEV
Bad:   DR_Extract_Account_Details_v2
Good:  DR_Extract_Account_Details

Use OmniStudio versioning (built into the platform) to manage iterations. The Data Mapper name stays constant across environments and versions.

---

Character Limits and Restrictions

• Maximum name length: 80 characters
• Allowed characters: letters, numbers, underscores
• Must start with DR_
• No spaces, hyphens, or special characters
• PascalCase after each underscore delimiter