sf-agent-framework/sf-core/tasks/flexcard-development.md

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

# FlexCard Development Task

## Task Overview

**Task**: Develop FlexCard component  
**Complexity**: Medium  
**Duration**: 4-8 hours  
**Output**: Functional FlexCard with documentation

## Prerequisites

- [ ] Design specifications available
- [ ] Data model understood
- [ ] OmniStudio access configured
- [ ] Test data prepared
- [ ] Acceptance criteria defined

## Development Process

### Phase 1: Setup (30 minutes)

#### Environment Preparation

1. **Access OmniStudio Designer**

   ```
   Setup → OmniStudio → FlexCards
   → New FlexCard
   ```

2. **Naming Convention**

   ```
   Pattern: FC_[Entity]_[Purpose]_[Version]
   Example: FC_Account_Summary_v1
   ```

3. **Initial Configuration**
   - Set Type and SubType
   - Configure title
   - Set theme/styling
   - Enable features needed

### Phase 2: Data Source Configuration (1 hour)

#### Option 1: SOQL Query

```sql
-- Example: Account summary query
SELECT Id, Name, Type, Industry, AnnualRevenue,
       BillingStreet, BillingCity, BillingState,
       (SELECT Id, Name, Email, Title
        FROM Contacts
        WHERE Primary__c = true
        LIMIT 5)
FROM Account
WHERE Id = '{recordId}'
```

#### Option 2: DataRaptor

```yaml
DataRaptor Configuration:
  Name: DR_AccountSummary_Extract
  Type: Extract
  Input:
    - accountId: { recordId }
  Output: Account data with related records
```

#### Option 3: Integration Procedure

```json
{
  "procedureName": "IP_GetAccountDetails",
  "input": {
    "accountId": "{recordId}",
    "includeHistory": true
  },
  "cacheable": true,
  "cacheTimeout": 300
}
```

### Phase 3: Card Layout Design (2 hours)

#### Header Section

```html
<!-- Card Header Template -->
<div class="slds-card__header">
  <h2 class="slds-text-heading_small">{Name}</h2>
  <div class="slds-text-body_regular">{Type} • {Industry}</div>
</div>
```

#### Body Section Structure

```yaml
Layout Options:
  1. Single Column:
    - Simple list of fields
    - Mobile optimized

  2. Two Column:
    - Field pairs
    - Balanced layout

  3. Grid Layout:
    - Multiple sections
    - Complex data display
```

#### Field Configuration

```json
{
  "fields": [
    {
      "name": "AnnualRevenue",
      "label": "Annual Revenue",
      "type": "currency",
      "format": "$#,###.00"
    },
    {
      "name": "LastActivityDate",
      "label": "Last Activity",
      "type": "date",
      "format": "relative"
    }
  ]
}
```

### Phase 4: States Implementation (1 hour)

#### State Configuration

```javascript
// State 1: Default State
{
  "name": "default",
  "isActive": true,
  "fields": ["all"],
  "actions": ["edit", "delete"]
}

// State 2: Compact State
{
  "name": "compact",
  "isActive": false,
  "fields": ["Name", "Type", "Industry"],
  "actions": ["expand"]
}

// State 3: Error State
{
  "name": "error",
  "isActive": false,
  "message": "Unable to load data",
  "actions": ["retry"]
}
```

#### Conditional Rendering

```javascript
// Show different content based on data
{
  "conditions": [
    {
      "field": "Type",
      "operator": "==",
      "value": "Enterprise",
      "showElement": "enterprise-section"
    }
  ]
}
```

### Phase 5: Actions & Events (1.5 hours)

#### Action Configuration

```json
{
  "actions": [
    {
      "name": "editRecord",
      "label": "Edit",
      "type": "Navigate",
      "target": "Record Page",
      "params": {
        "recordId": "{Id}",
        "mode": "edit"
      }
    },
    {
      "name": "launchFlow",
      "label": "Start Process",
      "type": "OmniScript",
      "target": "OS_ProcessAccount",
      "params": {
        "accountId": "{Id}"
      }
    }
  ]
}
```

#### Event Handling

```javascript
// Publish events
{
  "events": [
    {
      "name": "recordSelected",
      "channel": "FlexCard_Events",
      "data": {
        "recordId": "{Id}",
        "recordType": "Account"
      }
    }
  ]
}

// Subscribe to events
{
  "eventHandlers": [
    {
      "channel": "FlexCard_Events",
      "event": "refreshData",
      "action": "reload"
    }
  ]
}
```

### Phase 6: Styling & Responsiveness (1 hour)

#### Custom CSS

```css
/* FlexCard custom styles */
.fc-container {
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

.fc-header {
  background: linear-gradient(to right, #1589ee, #0070d2);
  color: white;
  padding: 1rem;
}

.fc-field-value {
  font-weight: 600;
  color: #032e61;
}

/* Responsive styles */
@media (max-width: 768px) {
  .fc-two-column {
    grid-template-columns: 1fr;
  }

  .fc-actions {
    flex-direction: column;
  }
}
```

#### Responsive Configuration

```json
{
  "responsive": {
    "breakpoints": {
      "mobile": {
        "maxWidth": 768,
        "columns": 1,
        "hideElements": ["secondary-info"]
      },
      "tablet": {
        "maxWidth": 1024,
        "columns": 2
      }
    }
  }
}
```

### Phase 7: Child Cards (Optional - 1 hour)

#### Child Card Implementation

```yaml
Parent Card Configuration:
  - Display mode: Embedded
  - Data passing: Automatic
  - Layout: Horizontal scroll

Child Card Setup:
  - Name: FC_Contact_Mini
  - Receives: Contact record
  - Display: Name, Title, Email
  - Actions: Email, Call
```

#### Data Relationship

```json
{
  "childCards": [
    {
      "name": "FC_RelatedContacts",
      "dataSource": "{Contacts}",
      "maxRecords": 5,
      "layout": "grid",
      "columns": 2
    }
  ]
}
```

### Phase 8: Testing (1.5 hours)

#### Functional Testing

```yaml
Test Scenarios:
  1. Data Loading:
    - Valid record ID
    - Invalid record ID
    - No access to record
    - Empty data fields

  2. User Interactions:
    - Click all actions
    - State transitions
    - Event firing
    - Error recovery

  3. Different Contexts:
    - Record page
    - Home page
    - Community
    - Mobile app
```

#### Performance Testing

```javascript
// Performance measurement
console.time('FlexCard Load');
// Card initialization
console.timeEnd('FlexCard Load');

// Check metrics
- Initial load: < 1 second
- Data fetch: < 500ms
- Render time: < 200ms
- Interaction response: < 100ms
```

#### Cross-Browser Testing

- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)
- Mobile browsers

## Best Practices Implementation

### 1. Performance Optimization

```javascript
// Efficient data fetching
{
  "dataSource": {
    "type": "SOQL",
    "query": "SELECT Id, Name, Type FROM Account WHERE Id = '{recordId}'",
    "fields": ["Id", "Name", "Type"], // Only required fields
    "cacheable": true,
    "cacheTimeout": 300
  }
}
```

### 2. Error Handling

```javascript
// Comprehensive error handling
{
  "errorHandling": {
    "dataFetchError": {
      "showMessage": true,
      "message": "Unable to load account data",
      "showRetry": true
    },
    "actionError": {
      "showToast": true,
      "logError": true
    }
  }
}
```

### 3. Accessibility

```html
<!-- Accessibility attributes -->
<div role="article" aria-label="Account Information" tabindex="0">
  <h2 id="account-name">{Name}</h2>
  <div aria-describedby="account-name">
    <!-- Content -->
  </div>
</div>
```

## Documentation Requirements

### Technical Documentation

```markdown
# FC_Account_Summary_v1

## Overview

Displays account summary information with related contacts.

## Data Source

- Type: DataRaptor
- Name: DR_AccountSummary_Extract
- Cache: 5 minutes

## States

1. Default - Full information display
2. Compact - Limited fields
3. Error - Error message with retry

## Actions

- Edit: Opens record in edit mode
- View Details: Navigates to full record page
- Create Case: Launches case creation OmniScript

## Events

- Publishes: recordSelected
- Subscribes: refreshData

## Performance

- Target load time: < 1 second
- Actual load time: 0.8 seconds
```

### User Documentation

- Screenshot of the card
- Field descriptions
- Action explanations
- Common use cases

## Deployment Checklist

### Pre-Deployment

- [ ] Code review completed
- [ ] Testing passed
- [ ] Documentation updated
- [ ] Performance validated
- [ ] Security reviewed

### Deployment Steps

1. Export FlexCard definition
2. Deploy to target org
3. Configure permissions
4. Activate FlexCard
5. Verify functionality

### Post-Deployment

- [ ] Smoke test in production
- [ ] Monitor performance
- [ ] Gather user feedback
- [ ] Document issues
- [ ] Plan improvements

## Common Issues & Solutions

### Issue 1: Data Not Loading

**Solution**: Check user permissions and field-level security

### Issue 2: Slow Performance

**Solution**: Enable caching and optimize queries

### Issue 3: Layout Issues

**Solution**: Review responsive settings and CSS

## Success Metrics

### Development Success

- Meets all requirements
- Passes all tests
- Performance targets met
- No critical bugs
- Documentation complete

### User Success

- Intuitive interface
- Fast loading
- Reliable data
- Useful actions
- Positive feedback