building-omnistudio-flexcard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

building-omnistudio-flexcard: OmniStudio FlexCard Creation and Validation

building-omnistudio-flexcard：OmniStudio FlexCard 创建与验证

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.

专注于Salesforce Industries领域FlexCard UI组件的资深OmniStudio工程师。可生成用于生产环境的FlexCard定义，通过声明式数据绑定、Integration Procedures数据源、条件渲染及标准SLDS（Salesforce Lightning Design System）样式，展示概览式信息。所有FlexCard均需通过涵盖7个类别的130分评分准则验证。

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
```
)

包含范围：创建与验证OmniStudio FlexCard定义（
```
OmniUiCard
```
）；配置Integration Procedures数据源；设计卡片布局、状态与操作按钮；依据130分准则评分；部署与激活
排除范围：构建OmniScript（请使用
```
building-omnistudio-omniscript
```
）、创建Integration Procedures（请使用
```
building-omnistudio-integration-procedure
```
）、映射完整依赖树（请使用
```
analyzing-omnistudio-dependencies
```
）、将元数据部署到组织（请使用
```
deploying-metadata
```
）

Core Responsibilities

核心职责

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

FlexCard 创作：设计并构建具备合理布局、状态与字段映射的FlexCard定义
数据源绑定：配置Integration Procedures数据源，实现正确的字段映射与错误处理
测试生成：针对多种数据状态（已填充、空值、错误、多记录）验证卡片
文档编制：生成包含数据源谱系与操作映射的可部署文档

Document Map

文档映射

Need	Document	Description
Best practices	references/best-practices.md	Layout patterns, SLDS, accessibility, performance
Data binding	references/data-binding-guide.md	IP sources, field mapping, conditional rendering

需求	文档	描述
最佳实践	references/best-practices.md	布局模式、SLDS规范、可访问性、性能优化
数据绑定	references/data-binding-guide.md	IP数据源、字段映射、条件渲染

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.

FlexCard位于OmniStudio技术栈的展示层。在构建依赖上游组件的FlexCard前，需确保这些上游组件已存在。

analyzing-omnistudio-dependencies → building-omnistudio-datamapper → building-omnistudio-integration-procedure → building-omnistudio-omniscript → building-omnistudio-flexcard（当前环节）

FlexCard从Integration Procedures获取数据，且可启动OmniScript。需先构建数据层，再构建展示层。

Key Insights

关键要点

Insight	Detail
Configuration fields	`OmniUiCard` uses `DataSourceConfig` for data source bindings and `PropertySetConfig` for card layout, states, and actions. There is NO `Definition` field on `OmniUiCard` in Core namespace.
Data source binding	Data sources bind to Integration Procedures for live data; the IP must be active and deployed before the FlexCard can retrieve data
Child card embedding	FlexCards can embed other FlexCards as child cards, enabling composite layouts with shared or independent data sources
OmniScript launching	FlexCards can launch OmniScripts via action buttons, passing context data from the card's data source into the OmniScript's input
Designer virtual object	The FlexCard Designer uses `OmniFlexCardView` as a virtual list object ( `/lightning/o/OmniFlexCardView/home` ), separate from the `OmniUiCard` sObject where card records are stored. Cards created via API may not appear in "Recently Viewed" until opened in the Designer.

要点	细节
配置字段	`OmniUiCard` 使用 `DataSourceConfig` 进行数据源绑定，使用 `PropertySetConfig` 配置卡片布局、状态与操作。Core命名空间下的 `OmniUiCard` 无 `Definition` 字段。
数据源绑定	数据源与Integration Procedures绑定以获取实时数据；IP必须先激活并部署，FlexCard才能获取数据
子卡片嵌入	FlexCard可嵌入其他FlexCard作为子卡片，实现共享或独立数据源的复合布局
OmniScript 启动	FlexCard可通过操作按钮启动OmniScript，并将卡片数据源的上下文数据传入OmniScript的输入参数
设计器虚拟对象	FlexCard设计器使用 `OmniFlexCardView` 作为虚拟列表对象（ `/lightning/o/OmniFlexCardView/home` ），与存储卡片记录的 `OmniUiCard` sObject相互独立。通过API创建的卡片在设计器中打开前，可能不会显示在“最近查看”列表中。

Workflow (5-Phase Pattern)

工作流程（5阶段模式）

Phase 1: Requirements Gathering

阶段1：需求收集

Before building, clarify these with the stakeholder:

Question	Why It Matters
What is the card's purpose?	Determines layout type and data density
Which data sources are needed?	Identifies required Integration Procedures
What object context does it run in?	Determines record-level vs. list-level display
What actions should the card expose?	Drives button/link configuration and OmniScript integration
What layout best fits the use case?	Single card, list, tabbed, or flyout
Are there conditional display rules?	Fields or sections that appear/hide based on data values

构建前，需与利益相关方明确以下内容：

问题	重要性
卡片的用途是什么？	决定布局类型与数据密度
需要哪些数据源？	确定所需的Integration Procedures
卡片运行在何种对象上下文？	决定是记录级还是列表级展示
卡片需暴露哪些操作？	驱动按钮/链接配置与OmniScript集成
哪种布局最适合使用场景？	单卡片、列表、标签页或弹出式
是否存在条件显示规则？	根据数据值显示/隐藏字段或区域

Phase 2: Design & Layout

阶段2：设计与布局

Read

references/best-practices.md

for layout patterns, SLDS compliance, accessibility requirements, and performance guidance before designing.

设计前，请阅读

references/best-practices.md

，了解布局模式、SLDS合规要求、可访问性规范与性能优化指南。

Card Layout Options

卡片布局选项

Layout Type	Use Case	Description
Single Card	Record summary	One card displaying fields from a single record
Card List	Related records	Repeating cards bound to an array data source
Tabbed Card	Multi-context	Multiple states displayed as tabs within one card
Flyout Card	Detail on demand	Expandable detail panel triggered from a summary card

布局类型	使用场景	描述
单卡片	记录摘要	展示单条记录字段的单个卡片
卡片列表	关联记录	绑定到数组数据源的重复卡片
标签页卡片	多上下文	在单个卡片内以标签页形式展示多种状态
弹出式卡片	按需查看详情	从摘要卡片触发的可展开详情面板

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

每个FlexCard数据源连接到Integration Procedures（或其他类型数据源），并将响应字段映射到展示元素。

FlexCard → 数据源（类型：IntegrationProcedure）
         → IP名称 + 输入映射
         → 响应字段映射 → 卡片元素

使用
```
{datasource.fieldName}
```
合并语法将IP响应字段映射到卡片展示元素
配置输入参数以传递记录上下文（例如
```
{recordId}
```
）到IP
当多个数据源为同一卡片提供数据时，设置数据源顺序

Action Button Design

操作按钮设计

Action Type	Purpose	Configuration
Launch OmniScript	Start a guided process	OmniScript Type + SubType, pass context params
Navigate	Go to record or URL	Record ID or URL template with merge fields
Custom Action	Platform event, LWC, etc.	Custom action handler with payload mapping

操作类型	用途	配置
启动OmniScript	启动引导流程	OmniScript类型+子类型，传递上下文参数
导航	跳转到记录或URL	记录ID或包含合并字段的URL模板
自定义操作	平台事件、LWC等	包含负载映射的自定义操作处理器

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

阶段3：生成与验证

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.

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

生成前，请阅读

references/data-binding-guide.md

，了解合并字段语法、数据源类型与多数据源协调规则。运行130分验证时，请阅读

references/scoring-rubric.md

了解完整的逐点细则。

生成FlexCard定义JSON
验证所有数据源引用均指向已激活的Integration Procedures
运行130分评分准则（见下方评分部分）
验证合并字段语法与IP响应结构匹配
检查所有交互元素的可访问性属性

Phase 4: Deployment

阶段4：部署

Ensure all upstream Integration Procedures are deployed and active
Run a dry-run check: use the
```
deploying-metadata
```
skill with
```
--dry-run
```
before committing
Deploy the FlexCard metadata (
```
OmniUiCard
```
) —
```
sf project deploy start
```
is safe to re-run; it upserts existing records
Activate the FlexCard in the target org
Embed the FlexCard in the target Lightning page, OmniScript, or parent FlexCard
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)

确保所有上游Integration Procedures已部署并激活
执行预检查：在提交前使用
```
deploying-metadata
```
技能并添加
```
--dry-run
```
参数
部署FlexCard元数据（
```
OmniUiCard
```
）——
```
sf project deploy start
```
可安全重复执行；它会更新现有记录
在目标组织中激活FlexCard
将FlexCard嵌入目标Lightning页面、OmniScript或父FlexCard
若部署失败：检查错误输出确定具体原因——常见问题：上游IP未部署（
```
Cannot find OmniIntegrationProcedure
```
）、缺少命名空间前缀（
```
Entity not found
```
）、或FlexCard仍处于草稿状态（检索前需激活）

Phase 5: Testing

阶段5：测试

Test each FlexCard against multiple data scenarios:

Scenario	What to Verify
Populated data	All fields render correctly, merge fields resolve
Empty data	Empty-state message displays, no broken merge fields
Error state	Graceful handling when IP returns an error or times out
Multi-record	Card list renders correct number of items, pagination works
Action buttons	OmniScript launches with correct pre-populated data
Conditional fields	Visibility rules toggle correctly based on data values
Mobile	Card layout adapts to smaller viewport widths

针对多种数据场景测试每个FlexCard：

场景	验证内容
已填充数据	所有字段正确渲染，合并字段解析正常
空数据	显示空状态提示，无损坏的合并字段
错误状态	IP返回错误或超时后优雅处理
多记录	卡片列表渲染正确数量的条目，分页功能正常
操作按钮	OmniScript启动时预填充正确数据
条件字段	可见性规则根据数据值正确切换
移动端	卡片布局适配较小视窗宽度

Generation Guardrails

生成约束

Avoid these patterns when generating FlexCard definitions:

Anti-Pattern	Why It's Wrong	Correct Approach
Referencing non-existent IP data sources	Card fails to load data at runtime	Verify IP exists and is active before binding
Hardcoded colors in styles	Breaks SLDS theming and dark mode	Use SLDS design tokens and CSS custom properties
Missing accessibility attributes	Fails WCAG compliance	Add `aria-label` , `role` , and keyboard handlers
Excessive nested child cards	Performance degrades with deep nesting	Limit to 2 levels of nesting; flatten where possible
Ignoring empty states	Broken UI when data source returns no records	Configure explicit empty-state messaging
Hardcoded record IDs	Card breaks across environments	Use merge fields and context-driven parameters

生成FlexCard定义时需避免以下模式：

反模式	问题所在	正确做法
引用不存在的IP数据源	卡片在运行时无法加载数据	绑定前验证IP已存在并激活
样式中使用硬编码颜色	破坏SLDS主题与深色模式	使用SLDS设计令牌与CSS自定义属性
缺少可访问性属性	不符合WCAG合规要求	添加 `aria-label` 、 `role` 与键盘处理器
过度嵌套子卡片	深度嵌套会导致性能下降	限制嵌套层级为2级；尽可能扁平化
忽略空状态	数据源无记录返回时UI损坏	配置明确的空状态提示信息
硬编码记录ID	跨环境时卡片失效	使用合并字段与上下文驱动参数

Scoring Rubric (130 Points)

评分准则（130分）

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

Category	Points	Criteria
Design & Layout	25	Appropriate layout type, logical field grouping, responsive design, consistent spacing, clear visual hierarchy
Data Binding	20	Correct IP references, proper merge field syntax, input parameter mapping, multi-source coordination
Actions & Navigation	20	Action buttons configured correctly, OmniScript launch params mapped, navigation targets valid, action labels descriptive
Styling	20	SLDS tokens used (no hardcoded colors), consistent typography, proper use of card/tile patterns, dark mode compatible
Accessibility	15	`aria-label` on interactive elements, keyboard navigable actions, sufficient color contrast, screen reader friendly field labels
Testing	15	Verified with populated data, empty state, error state, multi-record scenario, and mobile viewport
Performance	15	Data source calls minimized, child card nesting limited (max 2 levels), no redundant IP calls, lazy loading for non-visible states

Read

references/scoring-rubric.md

for the full per-criterion breakdown of all 7 categories.

所有FlexCard均需通过7个类别的验证。阈值：✅ 90分及以上（可部署） | ⚠️ 67-89分（需审查） | ❌ 67分以下（需修复，阻止部署）

类别	分值	标准
设计与布局	25	布局类型合适、字段分组合理、响应式设计、间距一致、视觉层级清晰
数据绑定	20	IP引用正确、合并字段语法规范、输入参数映射正确、多数据源协调合理
操作与导航	20	操作按钮配置正确、OmniScript启动参数映射无误、导航目标有效、操作标签描述清晰
样式	20	使用SLDS令牌（无硬编码颜色）、排版一致、正确使用卡片/磁贴模式、兼容深色模式
可访问性	15	交互元素带有 `aria-label` 、操作支持键盘导航、颜色对比度充足、字段标签适合屏幕阅读器
测试	15	已验证已填充数据、空状态、错误状态、多记录场景及移动端视窗
性能	15	数据源调用最小化、子卡片嵌套受限（最多2级）、无冗余IP调用、非可见状态使用懒加载

查看

references/scoring-rubric.md

获取所有7个类别的完整逐标准细则。

CLI Commands

CLI命令

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.

查看

scripts/flexcard-commands.sh

获取所有FlexCard CLI命令（查询、检索、部署）。将

<org>

替换为你的组织别名，

<Name>

替换为FlexCard的API名称。

Data Source Binding

数据源绑定

FlexCard Data Source Configuration

FlexCard数据源配置

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.

OmniUiCard

上的

DataSourceConfig

字段包含JSON格式的数据源绑定信息。

PropertySetConfig

字段包含卡片布局、状态与字段定义。

重要提示：Core命名空间下的
OmniUiCard
无
Definition
字段。请使用
DataSourceConfig
配置数据源，使用
PropertySetConfig
配置布局。

查看

assets/omni-ui-card.json

获取完整的OmniUiCard记录模板，包括

DataSourceConfig

的JSON结构。

Data Source Types

数据源类型

Type	`dataSource.type`	When to Use
Integration Procedure	`IntegrationProcedures` (plural, capital P)	Primary pattern; calls an IP for live data
SOQL	`SOQL`	Direct query (use sparingly; prefer IP for abstraction)
Apex Remote	`ApexRemote`	Custom Apex class invocation
REST	`REST`	External API call via Named Credential
Custom	`Custom`	Custom data provider (pass JSON body directly)

类型	`dataSource.type`	使用场景
Integration Procedure	`IntegrationProcedures` （复数形式，首字母大写P）	主要模式；调用IP获取实时数据
SOQL	`SOQL`	直接查询（谨慎使用；优先使用IP实现抽象）
Apex Remote	`ApexRemote`	调用自定义Apex类
REST	`REST`	通过命名凭据调用外部API
Custom	`Custom`	自定义数据提供者（直接传递JSON主体）

Field Mapping from IP Response

IP响应字段映射

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
  ]
}

使用合并字段语法将IP响应字段映射到卡片展示元素：

IP响应:                    FlexCard合并字段:
─────────────                   ─────────────────────
{ "Name": "Acme Corp" }   →    {Name}
{ "Account": {            →    {Account.Name}
    "Name": "Acme Corp"
  }
}
{ "records": [             →    {records[0].Name} （单条记录）
    { "Name": "Acme" }          或使用卡片列表布局迭代
  ]
}

Input Parameter Mapping

输入参数映射

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

Context Variable	Source	Example
`{recordId}`	Current record page	Pass to IP to query related data
`{userId}`	Running user	Filter data by current user
`{param.customKey}`	URL parameter or parent card	Pass from parent FlexCard or URL

将宿主页面的上下文传递到IP数据源：

上下文变量	来源	示例
`{recordId}`	当前记录页面	传递到IP以查询关联数据
`{userId}`	当前运行用户	根据当前用户过滤数据
`{param.customKey}`	URL参数或父卡片	从父FlexCard或URL传递

Cross-Skill Integration

跨技能集成

Skill	Relationship to building-omnistudio-flexcard
building-omnistudio-integration-procedure	Build the IP data sources that FlexCards consume
building-omnistudio-omniscript	Build the OmniScripts that FlexCard action buttons launch
building-omnistudio-datamapper	Build DataRaptors/DataMappers that IPs use under the hood
analyzing-omnistudio-dependencies	Analyze dependency chains across FlexCards, IPs, and OmniScripts
deploying-metadata	Deploy FlexCard metadata along with upstream dependencies
generating-lwc-components	Build custom LWC components embedded within FlexCards

技能	与building-omnistudio-flexcard的关系
building-omnistudio-integration-procedure	构建FlexCard依赖的IP数据源
building-omnistudio-omniscript	构建FlexCard操作按钮启动的OmniScript
building-omnistudio-datamapper	构建IP底层使用的DataRaptor/DataMapper
analyzing-omnistudio-dependencies	分析FlexCard、IP与OmniScript之间的依赖链
deploying-metadata	将FlexCard元数据与上游依赖一同部署
generating-lwc-components	构建嵌入FlexCard的自定义LWC组件

Gotchas

常见问题处理

Scenario	Handling
Empty data	Configure an explicit empty-state with a user-friendly message; do not show raw "No data" or blank card
Error states	Display a meaningful error message when the IP data source fails; log the error for debugging
Mobile responsiveness	Use single-column layout for mobile; avoid horizontal scrolling; test at 320px viewport width
Long text values	Truncate with ellipsis and provide a flyout or tooltip for full text
Large record sets	Use card list with pagination; limit initial load to 10-25 records
Null field values	Use conditional visibility to hide fields with null values rather than showing empty labels
Mixed data freshness	When multiple data sources have different refresh rates, display a "last updated" indicator

场景	处理方式
空数据	配置明确的空状态与用户友好提示；请勿显示原始的“无数据”或空白卡片
错误状态	IP数据源失败时显示有意义的错误提示；记录错误用于调试
移动端响应性	移动端使用单列布局；避免横向滚动；在320px视窗宽度下测试
长文本值	使用省略号截断，提供弹出框或工具提示展示完整文本
大型记录集	使用带分页的卡片列表；初始加载限制为10-25条记录
空字段值	使用条件可见性隐藏空值字段，而非显示空白标签
混合数据新鲜度	当多个数据源刷新速率不同时，显示“最后更新”指示器

FlexCard vs LWC Decision Guide

FlexCard与LWC决策指南

Factor	FlexCard	LWC
Build method	Declarative (drag-and-drop)	Code (JS, HTML, CSS)
Data binding	Integration Procedure merge fields	Wire service, Apex, GraphQL
Best for	At-a-glance information display	Complex interactive UIs
Testing	Manual + data state verification	Jest unit tests + manual
Customization	Limited to OmniStudio framework	Full platform flexibility
Reuse	Embed as child cards	Import as child components
When to choose	Standard card layouts with IP data	Custom behavior, animations, complex state

因素	FlexCard	LWC
构建方式	声明式（拖放）	编码（JS、HTML、CSS）
数据绑定	Integration Procedure合并字段	Wire服务、Apex、GraphQL
最佳适用场景	概览式信息展示	复杂交互式UI
测试方式	手动+数据状态验证	Jest单元测试+手动测试
定制化程度	受限于OmniStudio框架	全平台灵活性
复用性	作为子卡片嵌入	作为子组件导入
选择时机	使用IP数据的标准卡片布局	需要自定义行为、动画、复杂状态

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.

必需：带有OmniStudio（Industries Cloud）许可证的目标组织、已认证的

sf

CLI 数据源依赖：已部署到目标组织的激活状态Integration Procedures 操作依赖：已部署的激活状态OmniScript（若操作按钮需启动OmniScript） 评分约束：评分低于67分时阻止部署

幂等性：

sf project deploy start

会更新元数据——可安全重复执行，不会创建重复记录。部署前先查询确认当前状态：查看

scripts/flexcard-commands.sh

。

命名空间处理：在托管包组织中，元数据类型可能带有前缀（例如

omnistudio__OmniUiCard

）。查看

sfdx-project.json

获取命名空间。查看

scripts/flexcard-commands.sh

获取带命名空间的部署命令。

程序化创建FlexCard：使用REST API（

sf api request rest --method POST --body @file.json

）。必填字段：

Name

、

VersionNumber

、

OmniUiCardType

（例如

Child

）。设置

DataSourceConfig

（JSON字符串）进行数据源绑定，设置

PropertySetConfig

（JSON字符串）配置卡片布局。

sf data create record --values

标志无法处理文本区域字段中的JSON。创建后通过更新

IsActive=true

激活卡片。

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

本技能生成的交付物：

FlexCard JSON定义（
```
assets/omni-ui-card.json
```
模板）——可用于REST API创建或元数据部署的
```
OmniUiCard
```
记录
数据源绑定块——
```
DataSourceConfig
```
JSON，将Integration Procedure的输入与响应字段映射到卡片元素
卡片布局配置——
```
PropertySetConfig
```
JSON，定义卡片状态、字段展示、条件可见性与操作按钮
验证报告——7个类别的130分评分结果，包含可部署/需审查/需修复阈值判定
部署检查清单——确认上游IP已激活、FlexCard已激活，并嵌入到目标Lightning页面或父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

OmniStudio FlexCards（Trailhead）——官方学习模块，涵盖FlexCard基础与引导式设置
OmniStudio开发者指南——FlexCard元数据、数据源配置与组件属性的技术参考
Salesforce Industries文档——FlexCard配置指南，涵盖布局、状态与操作

Reference File Index

参考文件索引

File	When to read
`assets/omni-ui-card.json`	Phase 3 — Generation: OmniUiCard record template including DataSourceConfig JSON structure
`references/best-practices.md`	Phase 2 — Layout patterns, SLDS compliance, accessibility requirements, and performance guidance
`references/data-binding-guide.md`	Phase 2-3 — Data source types, merge field syntax, input parameter mapping, and multi-source coordination
`references/scoring-rubric.md`	Phase 3 — Full per-criterion breakdown of all 7 scoring categories (130 points)
`scripts/flexcard-commands.sh`	Phase 4 — All CLI commands for querying, retrieving, and deploying FlexCard metadata

文件	阅读时机
`assets/omni-ui-card.json`	阶段3——生成：包含DataSourceConfig JSON结构的OmniUiCard记录模板
`references/best-practices.md`	阶段2——布局模式、SLDS合规、可访问性要求与性能优化指南
`references/data-binding-guide.md`	阶段2-3——数据源类型、合并字段语法、输入参数映射与多数据源协调
`references/scoring-rubric.md`	阶段3——所有7个评分类别的完整逐标准细则（130分）
`scripts/flexcard-commands.sh`	阶段4——查询、检索与部署FlexCard元数据的所有CLI命令