sf-agent-framework/sf-core/utils/report-generator.md

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

# Report Generator Utility - Agent Instructions

## Purpose

This utility provides instructions for AI agents to generate comprehensive
reporting solutions for Salesforce implementations, enabling data visualization,
analytics, and automated report generation across various business domains.

## Agent Instructions

### When to Generate Reports

Generate reporting components when:

- Business metrics need visualization
- Executive dashboards are required
- Operational reports need automation
- Compliance reporting is mandatory
- Performance metrics need tracking
- Data analysis requires documentation
- Stakeholder updates are needed

### Core Components to Generate

#### 1. Report Builder Framework

Generate components that:

- Create dynamic reports
- Build reusable templates
- Generate multiple formats (PDF, Excel, CSV)
- Schedule automated delivery
- Implement data aggregation
- Support drill-down capabilities

Key report types:

- Executive summaries
- Operational dashboards
- Compliance reports
- Performance analytics
- Trend analysis
- Exception reports

#### 2. Data Aggregation Engine

Create aggregation logic for:

- Multi-object queries
- Cross-org reporting
- Time-based rollups
- Complex calculations
- Data transformations
- Statistical analysis

#### 3. Visualization Components

Implement visualizations using:

- Lightning Web Components
- Chart.js integration
- D3.js for complex visuals
- Tableau CRM embedding
- Custom SVG graphics
- Interactive dashboards

### Configuration Requirements

#### Custom Objects

```yaml
Report_Template__c:
  - Name (Text)
  - Report_Type__c (Picklist)
  - Query_Definition__c (Long Text Area)
  - Schedule__c (Text)
  - Format__c (Multi-Select Picklist)
  - Recipients__c (Text Area)
  - Active__c (Checkbox)

Report_Execution__c:
  - Report_Template__c (Master-Detail)
  - Execution_Time__c (DateTime)
  - Status__c (Picklist)
  - File_URL__c (URL)
  - Error_Message__c (Text Area)
  - Row_Count__c (Number)
  - Duration_ms__c (Number)

Report_Metric__c:
  - Name (Text)
  - Object_API_Name__c (Text)
  - Field_API_Name__c (Text)
  - Aggregation_Type__c (Picklist)
  - Filter_Criteria__c (Text Area)
  - Group_By__c (Text)
```

### Report Types to Implement

#### Sales Reports

```
- Pipeline Analysis
- Forecast vs Actual
- Win/Loss Analysis
- Territory Performance
- Product Performance
- Commission Calculations
```

#### Service Reports

```
- Case Volume Trends
- SLA Compliance
- Agent Performance
- Customer Satisfaction
- First Call Resolution
- Escalation Analysis
```

#### Marketing Reports

```
- Campaign ROI
- Lead Conversion
- Channel Performance
- Content Engagement
- Event Analytics
- Attribution Analysis
```

#### Financial Reports

```
- Revenue Recognition
- Billing Summary
- Collections Status
- Budget vs Actual
- Profitability Analysis
- Cash Flow Projections
```

### Implementation Patterns

#### Dynamic Report Generation Pattern

1. Parse report definition
2. Build dynamic queries
3. Apply filters and parameters
4. Execute data retrieval
5. Transform and aggregate
6. Generate output format

#### Scheduled Report Pattern

1. Define report schedule
2. Queue batch jobs
3. Execute at scheduled time
4. Generate report
5. Distribute to recipients
6. Archive results

#### Real-time Dashboard Pattern

1. Subscribe to data changes
2. Update calculations
3. Refresh visualizations
4. Maintain performance
5. Handle concurrency
6. Optimize queries

### Report Building Instructions

#### Query Construction

```
SELECT fields
FROM objects
WHERE conditions
GROUP BY dimensions
HAVING aggregations
ORDER BY metrics
LIMIT rows
```

#### Aggregation Functions

- SUM() for totals
- AVG() for averages
- COUNT() for quantities
- MIN()/MAX() for ranges
- Custom rollup summaries
- Statistical calculations

#### Performance Optimization

- Use indexed fields
- Limit data scope
- Implement caching
- Batch processing
- Asynchronous generation
- Progressive loading

### Dashboard Components to Generate

#### Executive Dashboard

Display:

- KPI scorecards
- Trend charts
- Comparison metrics
- Goal tracking
- Exception alerts
- Drill-down navigation

#### Operational Dashboard

Show:

- Real-time metrics
- Process status
- Queue monitoring
- Resource utilization
- Activity tracking
- Performance indicators

#### Analytics Dashboard

Include:

- Historical trends
- Predictive analytics
- Correlation analysis
- Segmentation
- Forecasting
- What-if scenarios

### Export Format Handlers

#### PDF Generation

- Use Visualforce rendering
- Implement page layouts
- Add headers/footers
- Include charts/graphs
- Format tables
- Apply branding

#### Excel Export

- Multiple worksheets
- Formatted cells
- Pivot table data
- Charts and graphs
- Conditional formatting
- Data validation

#### CSV Export

- Standard delimiters
- Header rows
- Encoding options
- Large data handling
- Compression support
- Streaming capability

### Best Practices to Implement

1. **Data Accuracy**
   - Validate sources
   - Handle nulls
   - Check calculations
   - Verify aggregations
   - Test edge cases

2. **Performance**
   - Optimize queries
   - Use selective filters
   - Implement pagination
   - Cache results
   - Batch processing

3. **User Experience**
   - Clear visualizations
   - Intuitive navigation
   - Responsive design
   - Export options
   - Print formatting

4. **Governance**
   - Data security
   - Row-level access
   - Field permissions
   - Audit trails
   - Version control

### Advanced Features to Consider

1. **AI-Enhanced Reporting**
   - Natural language queries
   - Anomaly detection
   - Trend prediction
   - Smart insights
   - Auto-generated narratives

2. **Interactive Features**
   - Drill-through navigation
   - Dynamic filtering
   - Parameter selection
   - Report customization
   - Collaborative annotations

3. **Integration Capabilities**
   - External data sources
   - API endpoints
   - Webhook notifications
   - Email delivery
   - Slack/Teams integration

### Error Handling Instructions

Handle these scenarios:

1. Query timeouts
2. Governor limits
3. Missing data
4. Permission errors
5. Export failures

Recovery strategies:

- Implement retries
- Chunk large datasets
- Graceful degradation
- Error notifications
- Fallback options

### Testing Requirements

Generate test classes for:

1. Report generation logic
2. Data aggregation
3. Export functionality
4. Scheduling system
5. Permission checks

### Success Metrics

Track and measure:

- Report accuracy
- Generation time
- User adoption
- Export success rate
- System performance
- Business value delivered