sf-flexcard（SF 弹性卡）

sf-flexcard: OmniStudio FlexCard Creation and Validation

Expert OmniStudio engineer specializing in FlexCard UI components for Salesforce Industries. Generate production-ready FlexCard definitions that display at-a-glance information with declarative data binding, Integration Procedure data sources, conditional rendering, and proper SLDS styling. All FlexCards are validated against a 130-point scoring rubric across 7 categories.

Core Responsibilities

1. FlexCard Authoring: Design and build FlexCard definitions with proper layout, states, and field mappings
2. Data Source Binding: Configure Integration Procedure data sources with correct field mapping and error handling
3. Test Generation: Validate cards against multiple data states (populated, empty, error, multi-record)
4. Documentation: Produce deployment-ready documentation with data source lineage and action mappings

Document Map

CRITICAL: Orchestration Order

FlexCards sit at the presentation layer of the OmniStudio stack. Ensure upstream components exist before building a FlexCard that depends on them.

sf-omnistudio-analyze → sf-datamapper → sf-integration-procedure → sf-omniscript → sf-flexcard (you are here)

FlexCards consume data from Integration Procedures and can launch OmniScripts. Build the data layer first, then the presentation layer.

Key Insights

Workflow (5-Phase Pattern)

Phase 1: Requirements Gathering

Before building, clarify these with the stakeholder:

Phase 2: Design & Layout

Card Layout Options

Data Source Configuration

Each FlexCard data source connects to an Integration Procedure (or other source type) and maps response fields to display elements.

FlexCard → Data Source (type: IntegrationProcedure)
         → IP Name + Input Mapping
         → Response Field Mapping → Card Elements

• Map IP response fields to card display elements using {datasource.fieldName} merge syntax
• Configure input parameters to pass record context (e.g., {recordId}) to the IP
• Set data source order when multiple sources feed the same card

Action Button Design

Conditional Visibility

• Show/hide fields based on data values using visibility conditions
• Show/hide entire card states based on data source results
• Display empty-state messaging when data source returns no records

Phase 3: Generation & Validation

1. Generate the FlexCard definition JSON
2. Validate all data source references resolve to active Integration Procedures
3. Run the 130-point scoring rubric (see Scoring section below)
4. Verify merge field syntax matches IP response structure
5. Check accessibility attributes on all interactive elements

Phase 4: Deployment

1. Ensure all upstream Integration Procedures are deployed and active
2. Deploy the FlexCard metadata (OmniUiCard)
3. Activate the FlexCard in the target org
4. Embed the FlexCard in the target Lightning page, OmniScript, or parent FlexCard

Phase 5: Testing

Test each FlexCard against multiple data scenarios:

Generation Guardrails

Avoid these patterns when generating FlexCard definitions:

Scoring Rubric (130 Points)

All FlexCards are validated against 7 categories. Thresholds: ✅ 90+ (Deploy) | ⚠️ 67-89 (Review) | ❌ <67 (Block - fix required)

Scoring Breakdown Detail

Design & Layout (25 points)

Data Binding (20 points)

Actions & Navigation (20 points)

Styling (20 points)

Accessibility (15 points)

Testing (15 points)

Performance (15 points)

CLI Commands

# Query active FlexCards in the org
sf data query -q "SELECT Id,Name,DataSourceConfig,PropertySetConfig,IsActive FROM OmniUiCard WHERE IsActive=true" -o <org>

# Retrieve a specific FlexCard by name
sf project retrieve start -m OmniUiCard:<Name> -o <org>

# Deploy a FlexCard to the target org
sf project deploy start -m OmniUiCard:<Name> -o <org>

# Retrieve all FlexCards
sf project retrieve start -m OmniUiCard -o <org>

# Deploy all OmniStudio metadata (FlexCards + dependencies)
sf project deploy start -m OmniUiCard -m OmniIntegrationProcedure -m OmniScript -o <org>

Data Source Binding

FlexCard Data Source Configuration

The DataSourceConfig field on OmniUiCard contains the data source bindings as JSON. The PropertySetConfig field contains the card layout, states, and field definitions.

IMPORTANT: There is NO Definition field on OmniUiCard in Core namespace. Use DataSourceConfig for data sources and PropertySetConfig for layout.

{
  "dataSource": {
    "type": "IntegrationProcedures",
    "value": {
      "ipMethod": "Type_SubType",
      "vlocityAsync": false,
      "inputMap": {
        "recordId": "{recordId}"
      },
      "resultVar": ""
    },
    "orderBy": {
      "name": "",
      "isReverse": ""
    },
    "contextVariables": []
  }
}

Data Source Types

Field Mapping from IP Response

Map IP response fields to card display elements using merge field syntax:

IP Response:                    FlexCard Merge Field:
─────────────                   ─────────────────────
{ "Name": "Acme Corp" }   →    {Name}
{ "Account": {            →    {Account.Name}
    "Name": "Acme Corp"
  }
}
{ "records": [             →    {records[0].Name}  (single)
    { "Name": "Acme" }          or iterate with Card List layout
  ]
}

Input Parameter Mapping

Pass context from the hosting page into the IP data source:

Cross-Skill Integration

Edge Cases

FlexCard vs LWC Decision Guide

Dependencies

Required: Target org with OmniStudio (Industries Cloud) license, sf CLI authenticated For Data Sources: Active Integration Procedures deployed to the target org For Actions: Active OmniScripts deployed (if action buttons launch OmniScripts) Scoring: Block deployment if score < 67

Creating FlexCards programmatically: Use REST API (sf api request rest --method POST --body @file.json). Required fields: Name, VersionNumber, OmniUiCardType (e.g., Child). Set DataSourceConfig (JSON string) for data source bindings and PropertySetConfig (JSON string) for card layout. The sf data create record --values flag cannot handle JSON in textarea fields. Activate by updating IsActive=true after creation.

External References

• OmniStudio FlexCards Trailhead - Official learning module
• OmniStudio Developer Guide - Technical reference
• Salesforce Industries Documentation - FlexCard configuration guide