sf-agent-framework/sf-core/utils/mapping-validator.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# Mapping Validator Utility - Agent Instructions

## Purpose

This utility provides instructions for AI agents to generate comprehensive data
mapping validation solutions for Salesforce integrations, migrations, and
transformations.

## Agent Instructions

### When to Generate Mapping Validation

Generate mapping validation components when:

- Data migrations need field mapping verification
- Integration mappings require validation
- ETL processes need quality checks
- Data transformations need accuracy validation
- Field mappings need consistency checks
- Cross-system mappings need verification
- Compliance requires mapping documentation

### Core Components to Generate

#### 1. Mapping Validation Engine

Generate validation components that:

- Validate source-to-target field mappings
- Check data type compatibility
- Verify transformation rules
- Validate required field mappings
- Detect mapping conflicts
- Ensure referential integrity

Key validation checks:

- Data type matching
- Field length compatibility
- Picklist value mapping
- Formula field validation
- Relationship mapping
- Default value handling

#### 2. Mapping Rule Processor

Create processors that:

- Apply transformation rules
- Execute data conversions
- Handle complex mappings
- Process conditional logic
- Manage exceptions
- Generate mapping reports

#### 3. Validation Report Generator

Implement reporting for:

- Mapping completeness
- Validation errors
- Warning conditions
- Success metrics
- Recommendations
- Compliance status

### Configuration Requirements

#### Custom Objects

```yaml
Mapping_Definition__c:
  - Name (Text)
  - Source_Object__c (Text)
  - Target_Object__c (Text)
  - Mapping_Type__c (Picklist)
  - Status__c (Picklist)
  - Validation_Status__c (Picklist)
  - Last_Validated__c (DateTime)

Field_Mapping__c:
  - Mapping_Definition__c (Master-Detail)
  - Source_Field__c (Text)
  - Target_Field__c (Text)
  - Transformation_Rule__c (Text Area)
  - Is_Required__c (Checkbox)
  - Validation_Status__c (Picklist)
  - Error_Message__c (Text Area)

Validation_Result__c:
  - Mapping_Definition__c (Lookup)
  - Validation_Date__c (DateTime)
  - Total_Mappings__c (Number)
  - Valid_Mappings__c (Number)
  - Invalid_Mappings__c (Number)
  - Warning_Count__c (Number)
  - Error_Details__c (Long Text Area)
```

### Validation Rules to Implement

#### Data Type Validation

```
1. Check source field type
2. Check target field type
3. Verify type compatibility
4. Apply conversion rules
5. Flag incompatible types
6. Suggest solutions
```

#### Field Length Validation

```
1. Get source field max length
2. Get target field max length
3. Compare lengths
4. If source > target:
   - Flag as warning/error
   - Suggest truncation rules
```

#### Picklist Mapping Validation

```
1. Extract source picklist values
2. Extract target picklist values
3. Check value mappings
4. Identify unmapped values
5. Validate default mappings
6. Generate mapping matrix
```

### Implementation Patterns

#### Pre-Migration Validation

1. Load mapping definitions
2. Validate all mappings
3. Generate validation report
4. Fix identified issues
5. Re-validate
6. Approve for migration

#### Real-time Validation

1. Validate on mapping creation
2. Check on rule changes
3. Monitor mapping usage
4. Alert on failures
5. Update dashboards

#### Post-Migration Validation

1. Compare source records
2. Verify target records
3. Validate transformations
4. Check data integrity
5. Generate audit report

### Mapping Types to Support

#### Simple Field Mapping

- Direct field-to-field
- Same data type
- No transformation
- One-to-one mapping

#### Transformation Mapping

- Data type conversion
- Format changes
- Value translations
- Formula applications

#### Complex Mapping

- Multiple source fields
- Conditional logic
- Lookup translations
- Aggregations
- Cross-object references

### Validation Categories

#### Structural Validation

- Object existence
- Field existence
- Field accessibility
- API names
- Namespace handling

#### Data Validation

- Type compatibility
- Value ranges
- Format compliance
- Required fields
- Unique constraints

#### Business Rule Validation

- Transformation logic
- Conditional rules
- Default values
- Calculation accuracy
- Reference integrity

### Dashboard Components to Generate

#### Mapping Overview Dashboard

Display:

- Total mappings by object
- Validation status summary
- Error distribution
- Completeness metrics
- Trend analysis
- Critical issues

#### Validation Details Dashboard

Show:

- Field-level validation results
- Error categories
- Warning details
- Transformation accuracy
- Performance metrics
- Resolution tracking

### Integration Requirements

#### Metadata API Integration

- Schema retrieval
- Field describe
- Picklist values
- Relationship mapping
- Permission checks

#### Data Loader Integration

- Mapping file import
- Validation execution
- Error reporting
- Batch processing
- Result export

#### Change Set Integration

- Mapping deployment
- Version control
- Environment sync
- Rollback support
- Audit trails

### Best Practices to Implement

1. **Validation Completeness**
   - Check all mappings
   - Validate edge cases
   - Test transformations
   - Verify defaults
   - Document exceptions

2. **Performance Optimization**
   - Batch validations
   - Cache metadata
   - Async processing
   - Efficient queries
   - Resource management

3. **Error Handling**
   - Clear error messages
   - Actionable feedback
   - Recovery suggestions
   - Logging details
   - User notifications

4. **Documentation**
   - Mapping specifications
   - Validation rules
   - Transformation logic
   - Exception handling
   - Audit trails

### Advanced Features to Consider

1. **AI-Powered Mapping**
   - Auto-suggest mappings
   - Pattern recognition
   - Historical learning
   - Anomaly detection
   - Smart validation

2. **Impact Analysis**
   - Downstream effects
   - Dependency mapping
   - Risk assessment
   - Change simulation
   - Rollback planning

3. **Continuous Validation**
   - Real-time monitoring
   - Automated testing
   - Performance tracking
   - Quality metrics
   - Trend analysis

### Error Handling Instructions

Handle these scenarios:

1. Missing source/target fields
2. Type incompatibilities
3. Transformation failures
4. Performance issues
5. Permission errors

Recovery strategies:

- Detailed error logging
- Mapping suggestions
- Alternative approaches
- Manual overrides
- Rollback procedures

### Testing Requirements

Generate test classes for:

1. Validation accuracy
2. Transformation logic
3. Error detection
4. Performance limits
5. Integration points

### Success Metrics

Track and measure:

- Validation accuracy rate
- Mapping completeness
- Error reduction
- Processing speed
- User satisfaction
- Migration success rate