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

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)

Read references/scoring-rubric.md for the full per-criterion breakdown of all 7 categories.

---

CLI Commands

Read scripts/flexcard-commands.sh for all FlexCard CLI commands (query, retrieve, deploy). Replace <org> with your org alias and <Name> with the FlexCard API name.

---

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.

Read assets/omni-ui-card.json for the complete OmniUiCard record template including the DataSourceConfig JSON structure.

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

---

Gotchas

---

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

Idempotency: sf project deploy start upserts metadata — safe to re-run without creating duplicates. Query first to confirm current state: see scripts/flexcard-commands.sh.

Namespace handling: In managed-package orgs, the metadata type may be prefixed (e.g., omnistudio__OmniUiCard). Check sfdx-project.json for the namespace. See scripts/flexcard-commands.sh for the namespaced deploy command.

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.

---

Output Expectations

Deliverables produced by this skill:

• FlexCard JSON definition (assets/omni-ui-card.json template) — OmniUiCard record ready for REST API creation or metadata deployment
• Data source binding block — DataSourceConfig JSON mapping Integration Procedure inputs and response fields to card elements
• Card layout config — PropertySetConfig JSON defining card states, field display, conditional visibility, and action buttons
• Validation report — 130-point score across 7 categories with deploy/review/block threshold result
• Deployment checklist — confirms upstream IPs are active, FlexCard is activated, and embedded in target Lightning page or parent FlexCard

---

External References

• OmniStudio FlexCards (Trailhead) — Official learning module for FlexCard fundamentals and guided setup
• OmniStudio Developer Guide — Technical reference for FlexCard metadata, data source configuration, and component properties
• Salesforce Industries Documentation — FlexCard configuration guide covering layout, states, and actions

---

Reference File Index

Credits

Official Salesforce OmniStudio tooling for FlexCard metadata authoring and validation. Primary inspiration for the skill's data source binding patterns and definition structure.

---

<!-- Parent: building-omnistudio-flexcard/SKILL.md -->

FlexCard Best Practices

Layout Design Patterns

Single Card

Use for displaying summary information about a single record. Group related fields into logical sections.

┌──────────────────────────────────┐
│  Header: Record Name             │
├──────────────────────────────────┤
│  Section 1: Key Details          │
│  ┌────────────┬─────────────┐    │
│  │ Field A    │ Field B     │    │
│  │ Field C    │ Field D     │    │
│  └────────────┴─────────────┘    │
├──────────────────────────────────┤
│  Section 2: Status               │
│  ┌──────────────────────────┐    │
│  │ Status Badge  │ Date     │    │
│  └──────────────────────────┘    │
├──────────────────────────────────┤
│  [Action Button 1] [Action 2]   │
└──────────────────────────────────┘

Guidelines:

• Limit to 8-10 fields per card to avoid information overload
• Place the most important fields in the top section
• Use consistent field alignment (label-left or label-top)
• Group related fields in the same row when they share context

Card List

Use for displaying a collection of related records. Each card in the list renders from one item in the data source array.

┌──────────────────────────────────┐
│  Card 1: Record A                │
│  Field 1 | Field 2 | [Action]   │
├──────────────────────────────────┤
│  Card 2: Record B                │
│  Field 1 | Field 2 | [Action]   │
├──────────────────────────────────┤
│  Card 3: Record C                │
│  Field 1 | Field 2 | [Action]   │
└──────────────────────────────────┘
  Showing 1-3 of 15  [Next →]

Guidelines:

• Keep each list card compact (3-5 fields maximum)
• Include a clear identifier field (Name, Title, or ID) in each card
• Add pagination when the data source can return more than 10 records
• Use consistent card height to maintain visual rhythm
• Provide a "View All" link when the list is truncated

Tabbed Card

Use when a single record has multiple contexts worth displaying. Each tab represents a different state with its own data source or field set.

┌──────────────────────────────────┐
│  [Tab 1: Overview] [Tab 2: History] [Tab 3: Related] │
├──────────────────────────────────┤
│  Tab 1 Content                   │
│  ┌──────────────────────────┐    │
│  │ Fields for this context  │    │
│  └──────────────────────────┘    │
└──────────────────────────────────┘

Guidelines:

• Limit to 3-5 tabs to avoid horizontal overflow
• Use concise tab labels (1-2 words)
• Load non-active tab data lazily (on tab selection)
• Mark the default active tab based on the most common use case

Flyout Card

Use for progressive disclosure: show a summary, then expand for details on demand.

┌──────────────────────────────────┐
│  Summary: Key Fields  [▼ More]   │
└──────────────────────────────────┘
       ↓ (on click)
┌──────────────────────────────────┐
│  Summary: Key Fields  [▲ Less]   │
├──────────────────────────────────┤
│  Detail Section                  │
│  Additional fields, history,     │
│  related records, etc.           │
└──────────────────────────────────┘

Guidelines:

• Keep the summary to 2-3 fields that answer "what is this?"
• Load flyout content on demand, not on initial card render
• Provide a clear visual indicator for the expand/collapse action
• Maintain the flyout state if the user scrolls away and returns

---

Data Source Optimization

Minimize IP Calls

• Use a single IP that returns all required data rather than multiple IPs for individual fields
• If the card has multiple data sources, ensure they do not query overlapping data
• Cache IP responses where the data does not change frequently (use IP caching options)

Input Parameter Efficiency

• Pass only the parameters the IP needs; do not forward the entire page context
• Use {recordId} as the primary context parameter for record-level cards
• Avoid passing large objects as input parameters; pass IDs and let the IP query

Response Structure

• Design IP responses to match the FlexCard's field mapping structure directly
• Avoid deep nesting in IP responses when the FlexCard only needs top-level fields
• Use resultListPath to point directly to the array node in list-type cards

Error Handling in Data Sources

• Configure a fallback state for when the IP returns an error
• Set reasonable timeout values for data source calls
• Log data source errors for debugging without exposing raw error messages to end users

---

Action Configuration

OmniScript Launch Actions

Navigation Actions

Action Button Placement

• Place primary actions at the bottom of the card or in the card header
• Limit to 2-3 actions per card; use a "More Actions" overflow menu for additional actions
• Use descriptive button labels ("Submit Claim", not "Submit" or "Go")
• Visually distinguish primary actions (filled button) from secondary actions (outline button)

---

SLDS Compliance for Styling

Required Practices

• Use SLDS design tokens for all colors, spacing, font sizes, and border radii
• Use slds-card or slds-tile patterns for card containers
• Use slds-grid and slds-col for multi-column layouts within cards
• Apply slds-text-heading_small and related text utilities for consistent typography

Color Usage

Correct:  Use SLDS token  →  var(--slds-g-color-brand-base-50)
Wrong:    Hardcoded hex    →  #0176d3
Wrong:    Hardcoded rgb    →  rgb(1, 118, 211)

• Status indicators: use slds-badge with appropriate color variants
• Background colors: use slds-box with slds-theme_shade or slds-theme_default
• Text colors: rely on inherited SLDS text colors; override only when necessary

Spacing

• Use SLDS spacing utilities: slds-m-top_small, slds-p-around_medium, etc.
• Maintain consistent spacing between card sections (use slds-m-bottom_medium)
• Do not use pixel values directly; map to the SLDS spacing scale

Dark Mode Compatibility

• All colors must come from SLDS CSS custom properties (--slds-g-color-*)
• Test card rendering in both light and dark modes
• Avoid background images that only work on light backgrounds
• Use currentColor for icon fills so they adapt to the text color

---

Accessibility Requirements

Interactive Elements

• Every button must have an aria-label or visible text label
• Links must have descriptive text (not "Click here" or "Learn more" without context)
• Icon-only buttons require aria-label describing the action

Keyboard Navigation

• All action buttons must be focusable via Tab key
• Buttons must activate on Enter and Space key presses
• Tab order must follow the visual reading order (top-to-bottom, left-to-right)
• Flyout expand/collapse must be keyboard accessible

Screen Reader Support

• Use semantic heading elements for card titles and section headers
• Data fields should have associated labels readable by screen readers
• Status indicators must convey meaning through text, not color alone
• Dynamic content updates should use aria-live regions

Color Contrast

• Text on card backgrounds must meet WCAG 2.1 AA contrast ratio (4.5:1)
• Interactive element boundaries must have 3:1 contrast against their background
• Do not use color as the sole method of conveying information (add icons or text)

---

Performance with Large Data Sets

Data Volume Guidelines

Rendering Performance

• Limit child card nesting to 2 levels maximum
• Avoid rendering more than 25 cards simultaneously in a card list
• Use conditional visibility to hide sections rather than rendering and hiding with CSS
• Lazy-load tab content and flyout details on user interaction

Data Source Performance

• Set appropriate IP cache durations for data that does not change frequently
• Avoid chaining multiple IPs when a single IP can return all needed data
• Use resultListPath to avoid client-side data transformation
• Monitor IP execution times; optimize IPs that take longer than 2 seconds

---

Child Card Composition

When to Use Child Cards

• The parent card displays summary data and the child card shows related detail
• Multiple cards share a common layout pattern that should be defined once
• Different sections of a card require independent data sources

Composition Guidelines

• Pass data from parent to child via input parameters, not global variables
• Keep child cards self-contained: they should work independently for testing
• Limit nesting to 2 levels (parent → child → grandchild maximum)
• Document the parent-child data flow in the FlexCard's description

Data Flow Pattern

Parent FlexCard
  ├── Data Source: IP_GetAccountSummary
  │     └── Passes {AccountId} to child
  └── Child FlexCard: AccountContacts
        └── Data Source: IP_GetContacts
              └── Input: {AccountId} from parent

Avoiding Composition Anti-Patterns

<!-- Parent: building-omnistudio-flexcard/SKILL.md -->

FlexCard Data Binding Guide

Integration Procedure Data Source Configuration

Basic IP Binding

The most common FlexCard data source is an Integration Procedure. The data source configuration specifies which IP to call, what input to send, and where to find the results in the IP response.

{
  "dataSource": {
    "type": "IntegrationProcedures",
    "value": {
      "ipMethod": "Type_SubType",
      "inputMap": {
        "recordId": "{recordId}"
      },
      "resultListPath": ""
    }
  }
}

IP Method Naming Convention

The ipMethod value combines the IP's Type and SubType fields:

IP Type:    "Account"
IP SubType: "GetSummary"
ipMethod:   "Account_GetSummary"

Ensure the IP is active and the Type/SubType match exactly (case-sensitive).

Input Map Parameters

Input parameters pass context from the FlexCard's hosting environment into the IP:

{
  "inputMap": {
    "recordId": "{recordId}",
    "accountId": "{Account.Id}",
    "status": "Active",
    "limit": 10
  }
}

---

Field Mapping Syntax

Basic Field Mapping

Map IP response fields to FlexCard display elements using curly-brace merge syntax:

IP Response JSON:                    FlexCard Merge Field:
─────────────────                    ─────────────────────
{ "Name": "Acme Corp" }        →    {Name}
{ "Status": "Active" }         →    {Status}
{ "Amount": 50000 }            →    {Amount}

Nested Field Mapping

Access nested objects in the IP response using dot notation:

IP Response JSON:                         FlexCard Merge Field:
─────────────────                         ─────────────────────
{                                    →    {Account.Name}
  "Account": {                       →    {Account.Industry}
    "Name": "Acme Corp",            →    {Account.Owner.Name}
    "Industry": "Technology",
    "Owner": {
      "Name": "Jane Smith"
    }
  }
}

Array Field Mapping

For card list layouts, set resultListPath to the array node. Each card in the list renders one item from the array:

{
  "dataSource": {
    "value": {
      "ipMethod": "Contact_GetRelated",
      "resultListPath": "contacts"
    }
  }
}

IP Response:                              Each Card Renders:
────────────                              ──────────────────
{                                         Card 1: {Name} → "Alice"
  "contacts": [                                   {Email} → "alice@acme.com"
    { "Name": "Alice", "Email": "..." },
    { "Name": "Bob",   "Email": "..." }, Card 2: {Name} → "Bob"
    { "Name": "Carol", "Email": "..." }          {Email} → "bob@acme.com"
  ]
}                                         Card 3: {Name} → "Carol"
                                                  {Email} → "carol@acme.com"

Formatted Field Display

Apply formatting to merge fields for display:

---

Conditional Rendering Based on Data

Field-Level Visibility

Show or hide individual fields based on a data value:

Condition:  {Status} == "Active"
Action:     Show the "Renewal Date" field

Condition:  {Amount} > 100000
Action:     Show the "High Value" badge

Condition:  {Email} != null
Action:     Show the email field (hide when null)

State-Level Visibility

FlexCards support multiple states. Each state can have visibility conditions:

Conditional Rendering Operators

Conditional Styling

Apply different styles based on data values:

If {Status} == "Active"    → Green badge (slds-badge slds-theme_success)
If {Status} == "Expired"   → Red badge (slds-badge slds-theme_error)
If {Status} == "Pending"   → Yellow badge (slds-badge slds-theme_warning)

Use SLDS theme classes rather than inline color styles to maintain dark mode compatibility.

---

Multi-Data-Source Cards

When to Use Multiple Data Sources

• The card displays data from unrelated objects that cannot be fetched in a single IP
• Different sections of the card have different refresh requirements
• A child card needs its own independent data source

Configuration Pattern

FlexCard: AccountOverview
├── Data Source 1: "Account_GetSummary"
│     Input: { "recordId": "{recordId}" }
│     Fields: {ds1.Name}, {ds1.Industry}, {ds1.Status}
│
├── Data Source 2: "Case_GetOpenCount"
│     Input: { "accountId": "{recordId}" }
│     Fields: {ds2.openCaseCount}, {ds2.lastCaseDate}
│
└── Data Source 3: "Opportunity_GetPipeline"
      Input: { "accountId": "{recordId}" }
      Fields: {ds3.totalPipeline}, {ds3.nextCloseDate}

Data Source Naming

When a card has multiple data sources, reference fields using the data source name prefix:

Single data source:     {Name}
Multiple data sources:  {ds1.Name}  or  {accountSummary.Name}

Load Order and Dependencies

• Data sources load in parallel by default
• If Data Source 2 depends on a value from Data Source 1, configure the dependency order
• Use conditional rendering to hide sections until their data source has loaded
• Display a loading indicator while data sources are in progress

Coordinating Multiple Sources

---

Error Handling for Failed Data Sources

Common Failure Modes

Error State Design

Configure an explicit error state rather than letting the card fail silently:

┌──────────────────────────────────┐
│  ⚠ Unable to load account data   │
│                                  │
│  The data source returned an     │
│  error. Try refreshing the page. │
│                                  │
│  [Refresh]  [Contact Support]    │
└──────────────────────────────────┘

Error State Guidelines:

• Use plain language, not technical error codes
• Provide an actionable next step (refresh, retry, contact admin)
• Log the technical error details for debugging (not displayed to end users)
• Do not show a blank card with no explanation

Fallback Strategies

Debugging Data Source Issues

1. Check IP activation: Query SELECT Name, IsActive FROM OmniProcess WHERE Name = 'Type_SubType' 2. Verify IP input: Use the OmniStudio Preview tool to test the IP with the same input parameters 3. Check field paths: Ensure merge field paths ({field.subfield}) match the actual IP response structure 4. Review permissions: Confirm the running user has access to the IP and the underlying objects 5. Inspect browser console: FlexCard data source errors appear in the browser developer console 6. Test with static data: Temporarily configure the FlexCard with a static JSON data source to isolate whether the issue is the IP or the card

Data Source Validation Checklist

Before deploying a FlexCard, verify each data source:

• [ ] IP exists in the target org
• [ ] IP is activated
• [ ] IP Type and SubType match the ipMethod value exactly (case-sensitive)
• [ ] Input parameters use correct merge field syntax
• [ ] resultListPath points to the correct array node (for list cards)
• [ ] All merge fields in the card map to actual fields in the IP response
• [ ] Error state is configured for graceful failure
• [ ] Empty state is configured for zero-record responses
• [ ] Data source has been tested with real data in a sandbox

FlexCard Scoring Rubric: Breakdown Detail

Detailed point-by-point scoring criteria for the 130-point FlexCard validation. Read during Phase 3 when running the full scoring rubric.

Design & Layout (25 points)

Data Binding (20 points)

Actions & Navigation (20 points)

Styling (20 points)

Accessibility (15 points)

Testing (15 points)

Performance (15 points)