@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/building-omnistudio-datamapper/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: building-omnistudio-datamapper
+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 building-omnistudio-integration-procedure), authoring OmniScripts (use building-omnistudio-omniscript), or analyzing cross-component dependencies (use analyzing-omnistudio-dependencies)."
+license: MIT
+metadata:
+  version: "1.0"
+---
+
+# building-omnistudio-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.
+
+---
+
+## 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 deploying-metadata skill
+- **Out of scope**: Building Integration Procedures (use `building-omnistudio-integration-procedure`), authoring OmniScripts (use `building-omnistudio-omniscript`), designing FlexCards (use `building-omnistudio-flexcard`), analyzing cross-component dependencies (use `analyzing-omnistudio-dependencies`)
+
+---
+
+## 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
+
+**analyzing-omnistudio-dependencies -> building-omnistudio-datamapper -> building-omnistudio-integration-procedure -> building-omnistudio-omniscript -> building-omnistudio-flexcard** (you are here: building-omnistudio-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 analyzing-omnistudio-dependencies 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 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)"
+
+| Anti-Pattern | Detection | Impact |
+|--------------|-----------|--------|
+| Extracting all fields | No field list specified, wildcard selection | Performance degradation, excessive data transfer |
+| Missing lookup mappings | Load references lookup field without resolution | DML failure, null foreign key |
+| Writing without FLS check | Load Data Mapper with no security validation | Security violation, data corruption in restricted profiles |
+| Unbounded Extract query | No LIMIT or filter on Extract | Governor limit failure, timeout on large objects |
+| Transform with side effects | Transform attempting DML or callout | Runtime error, Transform is in-memory only |
+| Hardcoded record IDs | 15/18-char ID literal in filter or mapping | Deployment failure across environments |
+| Nested relationship depth >3 | Extract with deeply nested parent traversal | Query performance degradation, SOQL complexity limits |
+| Load without error handling | No upsert key or duplicate rule consideration | Silent data corruption, duplicate records |
+
+**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 **deploying-metadata** skill: "Deploy OmniDataTransform [Name] to [target-org] with --dry-run"
+
+**Step 2: Deploy** (only if validation succeeds)
+Use the **deploying-metadata** 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)
+
+| Category | Points | Key Rules |
+|----------|--------|-----------|
+| **Design & Naming** | 20 | Correct type selection; naming follows `DR_[Type]_[Object]_[Purpose]` convention; single responsibility per Data Mapper |
+| **Field Mapping** | 25 | Explicit field list (no wildcards); correct input/output paths; proper type conversions; null-safe default values |
+| **Data Integrity** | 25 | FLS validation on all fields; lookup resolution for Load types; upsert keys defined; duplicate handling configured |
+| **Performance** | 15 | Bounded queries with LIMIT/filters; Turbo Extract for read-heavy scenarios; minimal relationship depth; indexed filter fields |
+| **Documentation** | 15 | Description on OmniDataTransform record; field mapping rationale documented; consuming components identified |
+
+**Thresholds**: ✅ 90+ (Deploy) | ⚠️ 67-89 (Review) | ❌ <67 (Block - fix required)
+
+---
+
+## CLI Commands
+
+### Query Existing Data Mappers
+
+```bash
+sf data query -q "SELECT Id,Name,Type FROM OmniDataTransform LIMIT 200" -o <org>
+```
+
+### Query Data Mapper Field Mappings
+
+```bash
+sf data query -q "SELECT Id,Name,InputObjectName,OutputObjectName,LookupObjectName FROM OmniDataTransformItem WHERE OmniDataTransformationId='<id>' LIMIT 200" -o <org>
+```
+
+### Retrieve Data Mapper Metadata
+
+```bash
+sf project retrieve start -m OmniDataTransform:<Name> -o <org>
+```
+
+### Deploy Data Mapper Metadata
+
+```bash
+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
+
+| From Skill | To building-omnistudio-datamapper | When |
+|------------|------------------|------|
+| analyzing-omnistudio-dependencies | -> building-omnistudio-datamapper | "Analyze dependencies before creating Data Mapper" |
+| generating-custom-object / generating-custom-field | -> building-omnistudio-datamapper | "Describe target object fields before mapping" |
+| querying-soql | -> building-omnistudio-datamapper | "Validate Extract query logic" |
+
+| From building-omnistudio-datamapper | To Skill | When |
+|--------------------|----------|------|
+| building-omnistudio-datamapper | -> building-omnistudio-integration-procedure | "Create Integration Procedure that calls this Data Mapper" |
+| building-omnistudio-datamapper | -> deploying-metadata | "Deploy Data Mapper to target org" |
+| building-omnistudio-datamapper | -> building-omnistudio-omniscript | "Wire Data Mapper output into OmniScript" |
+| building-omnistudio-datamapper | -> building-omnistudio-flexcard | "Display Data Mapper Extract results in FlexCard" |
+
+---
+
+## Gotchas
+
+| Issue | Resolution |
+|-------|-----------|
+| Large data volume (>10K records) | Use Turbo Extract; add pagination via Integration Procedure; warn about heap limits |
+| Polymorphic lookup fields | Specify the concrete object type in the mapping; test each type separately |
+| Formula fields in Extract | Standard Extract supports formula fields; Turbo Extract does not — fall back to standard Extract |
+| Cross-object Load (master-detail) | Insert parent records first, then child records in a separate Load step; use Integration Procedure to orchestrate sequence |
+| Namespace-prefixed fields | Include namespace prefix in field paths (e.g., `ns__Field__c`); verify prefix matches target org |
+| Multi-currency orgs | Map CurrencyIsoCode explicitly; do not rely on default currency assumption |
+| RecordType-dependent mappings | Filter by RecordType in Extract; set RecordTypeId in Load; document which RecordTypes are supported |
+| Draft Data Mapper not retrievable | `sf project retrieve start -m OmniDataTransform:<Name>` only works for active DMs; activate before retrieving |
+| Foreign key field name wrong | The parent lookup on `OmniDataTransformItem` is `OmniDataTransformationId` (full word "Transformation"), not `OmniDataTransformId` |
+
+---
+
+## 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
+
+| File | When to Read |
+|------|-------------|
+| `assets/omni-data-transform-extract.json` | Phase 3 Generation — template for Extract type OmniDataTransform records |
+| `assets/omni-data-transform-transform.json` | Phase 3 Generation — template for Transform type OmniDataTransform records |
+| `assets/omni-data-transform-load.json` | Phase 3 Generation — template for Load type OmniDataTransform records |
+| `assets/omni-data-transform-item.json` | Phase 3 Generation — template for each OmniDataTransformItem field mapping |
+| `assets/completion-summary-template.md` | Phase 3 & 5 — scoring output format and completion summary template |
+| `references/best-practices.md` | Phase 3 Guardrails — detailed patterns for field mapping, query optimization, null handling, and performance |
+| `references/naming-conventions.md` | Phase 2 Design — full naming rules for all Data Mapper types and field mapping conventions |
+
+---

package/skills/building-omnistudio-datamapper/assets/completion-summary-template.md

@@ -0,0 +1,28 @@
+# Data Mapper Completion Templates
+
+Use these templates in Phase 3 (scoring output) and Phase 5 (completion summary).
+
+## Scoring Output (Phase 3)
+
+```
+Score: XX/100 Rating
+|- Design & Naming: XX/20
+|- Field Mapping: XX/25
+|- Data Integrity: XX/25
+|- Performance: XX/15
+|- Documentation: XX/15
+```
+
+**Thresholds**: ✅ 90+ (Deploy) | ⚠️ 67-89 (Review) | ❌ <67 (Block — fix required)
+
+## Completion Summary (Phase 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
+```

package/skills/building-omnistudio-datamapper/assets/omni-data-transform-extract.json

@@ -0,0 +1,6 @@
+{
+  "Name": "DR_Extract_{{Object}}_{{Purpose}}",
+  "Type": "Extract",
+  "IsActive__c": false,
+  "Description": "Extract {{Object}} records for {{Purpose}}"
+}

package/skills/building-omnistudio-datamapper/assets/omni-data-transform-item.json

@@ -0,0 +1,12 @@
+{
+  "OmniDataTransformationId": "{{ParentTransformId}}",
+  "Name": "{{FieldName}}",
+  "InputObjectName": "{{SalesforceObjectApiName}}",
+  "InputFieldName": "{{SalesforceFieldApiName}}",
+  "OutputObjectName": "{{OutputNodeName}}",
+  "OutputFieldName": "{{OutputFieldName}}",
+  "OmniDataTransformItemOrder": 1,
+  "FilterDataType": "String",
+  "FilterOperator": "",
+  "FilterValue": ""
+}

package/skills/building-omnistudio-datamapper/assets/omni-data-transform-load.json

@@ -0,0 +1,6 @@
+{
+  "Name": "DR_Load_{{Object}}_{{Purpose}}",
+  "Type": "Load",
+  "IsActive__c": false,
+  "Description": "Load {{Object}} records for {{Purpose}}"
+}

package/skills/building-omnistudio-datamapper/assets/omni-data-transform-transform.json

@@ -0,0 +1,6 @@
+{
+  "Name": "DR_Transform_{{Object}}_{{Purpose}}",
+  "Type": "Transform",
+  "IsActive__c": false,
+  "Description": "Transform {{Object}} data structure for {{Purpose}}"
+}

package/skills/building-omnistudio-datamapper/references/best-practices.md

@@ -0,0 +1,277 @@
+<!-- Parent: building-omnistudio-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:
+
+| Source Type | Target Type | Notes |
+|-------------|-------------|-------|
+| String | Date | Requires ISO 8601 format (YYYY-MM-DD) |
+| String | Number | Ensure source contains numeric values only |
+| Boolean | String | Maps to "true"/"false" string literals |
+| DateTime | Date | Truncates time component |
+| Picklist | String | Maps selected value as string |
+
+### 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:
+
+| Field Type | Recommended Default | Rationale |
+|------------|-------------------|-----------|
+| String | `""` (empty string) | Prevents null reference in concatenation |
+| Number | `0` | Prevents null arithmetic errors |
+| Boolean | `false` | Prevents null conditional evaluation |
+| Date | (no default) | Leave null; do not fabricate dates |
+| Lookup | (no default) | Leave null; handle in consuming component |
+
+### 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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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
+
+| Record Count | Recommended Approach |
+|--------------|---------------------|
+| 1-200 | Standard Extract, single call |
+| 200-2000 | Turbo Extract, single call |
+| 2000-10000 | Turbo Extract with pagination via Integration Procedure |
+| 10000+ | Batch processing: scheduled Integration Procedure with chunked Turbo Extract calls |
+
+### 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:
+
+```bash
+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.