Building Omnistudio Flexcard

building-omnistudio-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 (Salesforce Lightning Design System) styling. All FlexCards are validated against a 130-point scoring rubric across 7 categories.

Scope

• In scope: Creating and validating OmniStudio FlexCard definitions (OmniUiCard); configuring Integration Procedure data sources; designing card layouts, states, and action buttons; scoring against the 130-point rubric; deployment and activation
• Out of scope: Building OmniScripts (use building-omnistudio-omniscript), creating Integration Procedures (use building-omnistudio-integration-procedure), mapping full dependency trees (use analyzing-omnistudio-dependencies), deploying metadata to org (use deploying-metadata)

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.

analyzing-omnistudio-dependencies → building-omnistudio-datamapper → building-omnistudio-integration-procedure → building-omnistudio-omniscript → building-omnistudio-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

Read references/best-practices.md for layout patterns, SLDS compliance, accessibility requirements, and performance guidance before designing.

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

Read references/data-binding-guide.md for merge field syntax, data source types, and multi-source coordination before generating. Read references/scoring-rubric.md for the full point-by-point breakdown when running the 130-point 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. Run a dry-run check: use the deploying-metadata skill with --dry-run before committing
3. Deploy the FlexCard metadata (OmniUiCard) — sf project deploy start is safe to re-run; it upserts existing records
4. Activate the FlexCard in the target org
5. Embed the FlexCard in the target Lightning page, OmniScript, or parent FlexCard
6. If deploy fails: check error output for specific cause — common issues: upstream IP not deployed (Cannot find OmniIntegrationProcedure), missing namespace prefix (Entity not found), or FlexCard still in Draft status (activate before retrieving)

Phase 5: Testing

Test each FlexCard against multiple data scenarios:

Generation Guardrails