sf-agent-framework/sf-core/utils/field-usage-analyzer.md

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

# Field Usage Analyzer Utility - Agent Instructions

## Purpose

This utility provides instructions for AI agents to generate comprehensive field
usage analysis solutions for Salesforce organizations, helping identify unused
fields, optimize page layouts, and improve data quality.

## Agent Instructions

### When to Generate Field Usage Analysis

Generate field usage analysis components when:

- Organizations need to optimize data models
- Page layouts require optimization
- Field cleanup is needed
- License optimization requires field analysis
- Data migration needs field mapping
- Performance optimization is required
- Compliance audits need field documentation

### Core Components to Generate

#### 1. Field Usage Scanner

Generate an Apex class that:

- Scans all objects for field metadata
- Counts populated vs empty fields
- Tracks field modification dates
- Identifies unused fields
- Analyzes field dependencies
- Calculates field importance scores

Key scanning capabilities:

- Null value detection
- Default value analysis
- Last modified tracking
- Reference counting
- Formula field usage
- Workflow/trigger dependencies

#### 2. Usage Pattern Analyzer

Create analysis components that:

- Track field access patterns
- Monitor field update frequency
- Identify seasonal usage
- Detect redundant fields
- Analyze field relationships
- Generate usage heat maps

#### 3. Optimization Engine

Implement optimization features:

- Recommend fields for removal
- Suggest field consolidation
- Identify archival candidates
- Propose page layout changes
- Calculate storage impact
- Generate cleanup scripts

### Configuration Requirements

#### Custom Objects

Create these objects:

```yaml
Field_Analysis__c:
  - Object_Name__c (Text)
  - Field_Name__c (Text)
  - Field_Type__c (Text)
  - Analysis_Date__c (DateTime)
  - Total_Records__c (Number)
  - Populated_Records__c (Number)
  - Population_Percent__c (Percent)
  - Last_Modified_Date__c (DateTime)
  - Usage_Score__c (Number)
  - Recommendation__c (Picklist)

Field_Dependency__c:
  - Field_Analysis__c (Master-Detail)
  - Dependency_Type__c (Picklist)
  - Dependent_Component__c (Text)
  - Component_Type__c (Picklist)
  - Is_Critical__c (Checkbox)
  - Description__c (Text Area)

Usage_Pattern__c:
  - Field_Analysis__c (Lookup)
  - Period__c (Text)
  - Access_Count__c (Number)
  - Update_Count__c (Number)
  - Unique_Users__c (Number)
  - Peak_Usage_Time__c (Text)
```

#### Analysis Configuration

```yaml
Field_Analysis_Config__mdt:
  - Object_Name__c (Text)
  - Include_In_Analysis__c (Checkbox)
  - Minimum_Population_Threshold__c (Number)
  - Archive_Threshold_Days__c (Number)
  - Critical_Fields__c (Long Text Area)
  - Excluded_Fields__c (Long Text Area)
```

### Analysis Algorithms to Implement

#### Population Analysis

```
For each field:
1. Count total records in object
2. Count records where field is not null
3. Calculate: (populated / total) × 100
4. Classify population level:
   - High: > 80%
   - Medium: 30-80%
   - Low: 5-30%
   - Minimal: < 5%
```

#### Usage Score Calculation

```
Usage Score = (Population % × 0.3) +
              (Access Frequency × 0.2) +
              (Update Frequency × 0.2) +
              (Dependency Count × 0.2) +
              (Business Criticality × 0.1)
```

#### Optimization Recommendations

```
If population < 5% AND no dependencies:
  → Recommend removal
If similar fields exist with overlap > 70%:
  → Recommend consolidation
If not modified in > 365 days:
  → Recommend archival
If used only in specific record types:
  → Recommend conditional visibility
```

### Implementation Patterns

#### Batch Analysis Pattern

1. Implement Database.Batchable
2. Process objects in chunks
3. Aggregate field statistics
4. Store analysis results
5. Generate recommendations
6. Create summary reports

#### Real-time Monitoring Pattern

1. Track field access events
2. Update usage counters
3. Detect access patterns
4. Alert on anomalies
5. Update dashboards
6. Trigger notifications

#### Dependency Mapping Pattern

1. Scan validation rules
2. Check workflow rules
3. Analyze process builder
4. Review flows
5. Check apex references
6. Map relationships

### Field Categories to Analyze

#### System Fields

- Created/Modified dates
- Owner fields
- Record type
- System timestamps
- Audit fields

#### Custom Fields

- Business data fields
- Integration fields
- Formula fields
- Lookup relationships
- Picklist fields

#### Special Fields

- Encrypted fields
- External ID fields
- Unique fields
- Required fields
- Rich text fields

### Dashboard Components to Generate

#### Field Usage Overview

Display:

- Total fields by object
- Population percentages
- Usage heat map
- Trend analysis
- Top unused fields
- Storage impact

#### Optimization Dashboard

Show:

- Removal candidates
- Consolidation opportunities
- Archive recommendations
- Page layout suggestions
- Projected savings
- Implementation priority

#### Compliance Dashboard

Include:

- Required field compliance
- Data quality scores
- Field documentation status
- Audit trail coverage
- Security compliance

### Integration Requirements

#### Metadata API Integration

- Field describe calls
- Dependency queries
- Layout analysis
- Permission checks
- Profile field access

#### Analytics Integration

- Einstein Analytics datasets
- Usage pattern visualization
- Predictive analytics
- Trend forecasting
- Anomaly detection

#### Change Management Integration

- Field retirement workflows
- Impact analysis
- Stakeholder notifications
- Migration planning
- Rollback procedures

### Best Practices to Implement

1. **Analysis Scheduling**
   - Run during off-peak hours
   - Batch large objects
   - Cache results
   - Incremental updates
   - Monitor performance

2. **Accuracy Assurance**
   - Validate findings
   - Cross-reference dependencies
   - Sample verification
   - User confirmation
   - Test recommendations

3. **Change Management**
   - Document all changes
   - Communicate impacts
   - Phase implementations
   - Monitor post-change
   - Maintain rollback plans

4. **Data Governance**
   - Enforce standards
   - Regular reviews
   - Documentation updates
   - Training programs
   - Compliance monitoring

### Advanced Features to Consider

1. **Machine Learning Integration**
   - Usage prediction
   - Anomaly detection
   - Pattern recognition
   - Auto-categorization
   - Smart recommendations

2. **Automated Cleanup**
   - Safe field removal
   - Data archival
   - Layout updates
   - Permission adjustments
   - Validation rule updates

3. **Impact Simulation**
   - What-if analysis
   - Change preview
   - Risk assessment
   - Cost-benefit analysis
   - Timeline estimation

### Error Handling Instructions

Handle these scenarios:

1. Large data volumes
2. Complex dependencies
3. Permission restrictions
4. API limits
5. Timeout issues

Recovery strategies:

- Checkpoint progress
- Retry failed objects
- Partial analysis
- Manual overrides
- Error reporting

### Testing Requirements

Generate test classes for:

1. Field analysis accuracy
2. Dependency detection
3. Recommendation logic
4. Batch processing
5. Integration points

### Reporting Capabilities

Generate reports for:

- Executive summary
- Technical field analysis
- Optimization roadmap
- Compliance status
- ROI projections
- Implementation guide

### Success Metrics

Track and measure:

- Fields analyzed
- Unused fields identified
- Storage recovered
- Performance improvement
- Compliance scores
- User satisfaction