building-omnistudio-flexcard

Name: building-omnistudio-flexcard
Author: forcedotcom

github.com/forcedotcomデザイン・UI1.1k2.4k 回インストール1 日前に更新

building-omnistudio-flexcard について

Salesforce Industries 向け OmniStudio FlexCard の作成・検証スキルです。レイアウト、データバインディング、状態、アクションを扱い、データソースやアクセシビリティなどを 130 点の基準で評価します。

主な機能

01FlexCard 定義の生成
02Integration Procedure データソースへのバインド
03レイアウト、状態、アクションの設定
04条件付き表示と空状態の検証
057 カテゴリーの 130 点評価

活用シーン

01レコード概要を表示するカードの作成
02Integration Procedure の応答をカード要素にマッピング
03OmniScript を起動するボタンの設定
04空データやエラー時のカード表示の確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/forcedotcom/sf-skills --skill building-omnistudio-flexcard

インストール後、Claude Code で/building-omnistudio-flexcardを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

CREDITS.md

assets/

omni-ui-card.json

references/

best-practices.md

data-binding-guide.md

scoring-rubric.md

scripts/

flexcard-commands.sh

詳細

building-omnistudio-flexcard：OmniStudio FlexCard の作成と検証

Salesforce Industries 向け FlexCard UI コンポーネントを専門とする、経験豊富な OmniStudio エンジニアです。宣言型データバインディング、Integration Procedure データソース、条件付きレンダリング、適切な SLDS（Salesforce Lightning Design System）スタイルを使用して、一目で情報を確認できる本番環境対応の FlexCard 定義を生成します。すべての FlexCard は、7 つのカテゴリにわたる130 点満点の評価基準で検証されます。

対象範囲

対象範囲内：OmniStudio FlexCard 定義（OmniUiCard）の作成と検証、Integration Procedure データソースの設定、カードのレイアウト・状態・アクションボタンの設計、130 点満点の評価基準による採点、デプロイと有効化
対象範囲外：OmniScript の構築（building-omnistudio-omniscript を使用）、Integration Procedure の作成（building-omnistudio-integration-procedure を使用）、依存関係ツリー全体のマッピング（analyzing-omnistudio-dependencies を使用）、メタデータの組織へのデプロイ（deploying-metadata を使用）

主な責務

FlexCard の作成：適切なレイアウト、状態、項目マッピングを備えた FlexCard 定義を設計・構築します
データソースのバインディング：正しい項目マッピングとエラー処理を用いて、Integration Procedure データソースを設定します
テストの生成：複数のデータ状態（データあり、空、エラー、複数レコード）に対してカードを検証します
ドキュメント作成：データソースの系統とアクションのマッピングを含む、デプロイ準備が整ったドキュメントを作成します

ドキュメント一覧

必要な情報	ドキュメント	説明
ベストプラクティス	references/best-practices.md	レイアウトパターン、SLDS、アクセシビリティ、パフォーマンス
データバインディング	references/data-binding-guide.md	IP ソース、項目マッピング、条件付きレンダリング

重要：オーケストレーションの順序

FlexCard は OmniStudio スタックのプレゼンテーション層に位置します。依存する FlexCard を構築する前に、上流のコンポーネントが存在することを確認してください。

analyzing-omnistudio-dependencies → building-omnistudio-datamapper → building-omnistudio-integration-procedure → building-omnistudio-omniscript → building-omnistudio-flexcard (you are here)

FlexCard は Integration Procedure からデータを取得し、OmniScript を起動できます。まずデータ層を構築し、次にプレゼンテーション層を構築してください。

主なポイント

ポイント	詳細
設定項目	`OmniUiCard` は、データソースのバインディングに `DataSourceConfig` を、カードのレイアウト、状態、アクションに `PropertySetConfig` を使用します。Core 名前空間の `OmniUiCard` に `Definition` フィールドはありません。
データソースのバインディング	データソースはライブデータ用に Integration Procedure にバインドされます。FlexCard がデータを取得するには、IP が有効化され、デプロイ済みである必要があります
子カードの埋め込み	FlexCard はほかの FlexCard を子カードとして埋め込めるため、共有または独立したデータソースを使用する複合レイアウトを作成できます
OmniScript の起動	FlexCard はアクションボタンから OmniScript を起動し、カードのデータソースからコンテキストデータを OmniScript の入力に渡すことができます
Designer の仮想オブジェクト	FlexCard Designer は仮想リストオブジェクトとして `OmniFlexCardView`（`/lightning/o/OmniFlexCardView/home`）を使用します。カードレコードが保存される `OmniUiCard` sObject とは別のオブジェクトです。API 経由で作成したカードは、Designer で開くまで「最近参照した項目」に表示されない場合があります。

ワークフロー（5 フェーズパターン）

フェーズ 1：要件の収集

構築を始める前に、関係者に次の点を確認してください。

質問	重要な理由
カードの目的は何ですか？	レイアウトの種類とデータ密度を決定します
どのデータソースが必要ですか？	必要な Integration Procedure を特定します
どのオブジェクトのコンテキストで実行しますか？	レコード単位かリスト単位かの表示を決定します
カードにどのようなアクションを表示しますか？	ボタンやリンクの設定、および OmniScript との連携に影響します
ユースケースに最適なレイアウトはどれですか？	単一カード、リスト、タブ付き、またはフライアウトから選択します
条件付きの表示ルールはありますか？	データ値に基づいて表示または非表示にする項目やセクションを確認します

Phase 2: 設計とレイアウト

設計を始める前に、references/best-practices.md を読み、レイアウトパターン、SLDS 準拠、アクセシビリティ要件、パフォーマンスに関するガイダンスを確認してください。

カードレイアウトの選択肢

レイアウトの種類	使用例	説明
単一カード	レコードの概要	1つのレコードの項目を表示するカードです
カードリスト	関連レコード	配列データソースにバインドされた、繰り返し表示されるカードです
タブ付きカード	複数のコンテキスト	1つのカード内に、複数の状態をタブとして表示します
フライアウトカード	必要に応じた詳細表示	概要カードから起動する、展開可能な詳細パネルです

データソースの設定

各 FlexCard データソースは、Integration Procedure（またはその他のソースタイプ）に接続し、応答フィールドを表示要素にマッピングします。

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

{datasource.fieldName} のマージ構文を使って、IP の応答フィールドをカードの表示要素にマッピングします
IP にレコードのコンテキスト（例：{recordId}）を渡す入力パラメーターを設定します
複数のソースから同じカードにデータを渡す場合は、データソースの順序を設定します

アクションボタンの設計

アクションの種類	目的	設定
OmniScript の起動	ガイド付きプロセスを開始する	OmniScript の Type と SubType を指定し、コンテキストパラメーターを渡します
移動	レコードまたは URL に移動する	レコード ID、またはマージフィールドを含む URL テンプレートを指定します
カスタムアクション	プラットフォームイベント、LWC など	ペイロードマッピングを使用するカスタムアクションハンドラーを指定します

条件付き表示

表示条件を使って、データ値に基づいて項目の表示／非表示を切り替えます
データソースの結果に基づいて、カードの状態全体の表示／非表示を切り替えます
データソースがレコードを返さない場合は、空状態のメッセージを表示します

Phase 3: 生成と検証

生成する前に、references/data-binding-guide.md を読み、マージフィールドの構文、データソースの種類、複数ソースの連携方法を確認してください。 130ポイントの検証を実行する際は、references/scoring-rubric.md を読み、項目ごとの採点基準を確認してください。

FlexCard 定義の JSON を生成します
すべてのデータソース参照が、有効な Integration Procedure に解決されることを検証します
130ポイントの採点基準を実行します（下記の採点セクションを参照）
マージフィールドの構文が IP の応答構造と一致することを確認します
すべてのインタラクティブ要素のアクセシビリティ属性を確認します

Phase 4: デプロイ

すべての上流の Integration Procedure がデプロイ済みで有効であることを確認します
コミットする前に、deploying-metadata スキルを --dry-run とともに使用してドライランチェックを実行します
FlexCard メタデータ（OmniUiCard）をデプロイします — sf project deploy start は安全に再実行でき、既存のレコードをアップサートします
対象の org で FlexCard を有効化します
FlexCard を対象の Lightning ページ、OmniScript、または親 FlexCard に埋め込みます
デプロイに失敗した場合：エラー出力で具体的な原因を確認します。よくある問題：上流の IP が未デプロイ（Cannot find OmniIntegrationProcedure）、名前空間プレフィックスの欠落（Entity not found）、または FlexCard がまだ Draft 状態（取得する前に有効化してください）

Phase 5: テスト

複数のデータシナリオで各 FlexCard をテストします。

シナリオ	確認内容
データあり	すべての項目が正しく表示され、マージフィールドが解決される
データなし	空状態のメッセージが表示され、マージフィールドの破損がない
エラー状態	IP がエラーを返す、またはタイムアウトする場合に適切に処理される
複数レコード	カードリストに正しい数の項目が表示され、ページネーションが機能する
アクションボタン	OmniScript が正しく事前入力されたデータで起動する
条件付き項目	データ値に基づいて表示ルールが正しく切り替わる
モバイル	カードレイアウトが狭いビューポート幅に適応する

生成時のガードレール

FlexCard 定義を生成する際は、次のアンチパターンを避けてください。

アンチパターン	問題点	正しいアプローチ
存在しない IP データソースを参照する	実行時にカードのデータ読み込みに失敗します	バインドする前に、IP が存在し有効であることを確認します
スタイルに色をハードコードする	SLDS のテーマ設定とダークモードが機能しなくなります	SLDS デザイントークンと CSS カスタムプロパティを使用します
アクセシビリティ属性がない	WCAG に準拠できません	`aria-label`、`role`、キーボードハンドラーを追加します
子カードを過度にネストする	深いネストによってパフォーマンスが低下します	ネストは 2 階層までに制限し、可能な場合はフラット化します
空の状態を無視する	データソースがレコードを返さない場合に UI が壊れます	空の状態を明示するメッセージを設定します
レコード ID をハードコードする	環境をまたいでカードが機能しなくなります	マージフィールドとコンテキストに基づくパラメーターを使用します

スコアリング基準（130 点）

すべての FlexCard は 7 つのカテゴリに基づいて検証されます。しきい値：✅ 90 以上（デプロイ） | ⚠️ 67～89（レビュー） | ❌ 67 未満（ブロック — 修正が必要）

カテゴリ	点数	基準
デザインとレイアウト	25	適切なレイアウトタイプ、論理的なフィールドのグループ化、レスポンシブデザイン、一貫した間隔、明確な視覚的階層
データバインディング	20	正しい IP 参照、適切なマージフィールド構文、入力パラメータのマッピング、複数のソースの連携
アクションとナビゲーション	20	アクションボタンが正しく設定されている、OmniScript 起動パラメーターがマッピングされている、ナビゲーション先が有効である、アクションラベルがわかりやすい
スタイリング	20	SLDS トークンを使用している（色のハードコードなし）、一貫したタイポグラフィ、カード／タイルパターンの適切な使用、ダークモードに対応
アクセシビリティ	15	インタラクティブ要素に `aria-label` がある、アクションをキーボードで操作できる、十分な色のコントラスト、スクリーンリーダーに適したフィールドラベル
テスト	15	データがある状態、空の状態、エラー状態、複数レコードのシナリオ、モバイルのビューポートで検証済み
パフォーマンス	15	データソースの呼び出しを最小限に抑えている、子カードのネストが制限されている（最大 2 階層）、不要な IP 呼び出しがない、非表示の状態では遅延読み込みを行う

7 つのカテゴリすべての基準の詳細については、references/scoring-rubric.md を参照してください。

CLI コマンド

すべての FlexCard CLI コマンド（クエリ、取得、デプロイ）については、scripts/flexcard-commands.sh を参照してください。<org> を組織のエイリアスに、<Name> を FlexCard の API 名に置き換えてください。

データソースのバインディング

FlexCard データソースの設定

OmniUiCard の DataSourceConfig フィールドには、JSON 形式のデータソースのバインディングが含まれます。PropertySetConfig フィールドには、カードのレイアウト、状態、フィールド定義が含まれます。

IMPORTANT：Core 名前空間の OmniUiCard に Definition フィールドはありません。データソースには DataSourceConfig を、レイアウトには PropertySetConfig を使用してください。

DataSourceConfig の JSON 構造を含む、完全な OmniUiCard レコードのテンプレートについては、assets/omni-ui-card.json を参照してください。

データソースの種類

種類	`dataSource.type`	使用するタイミング
Integration Procedure	`IntegrationProcedures`（複数形、大文字の P）	主なパターン。ライブデータを取得するために IP を呼び出します
SOQL	`SOQL`	直接クエリ（使用は控えめにし、抽象化できる IP を優先してください）
Apex Remote	`ApexRemote`	カスタム Apex クラスの呼び出し
REST	`REST`	Named Credential を使用した外部 API 呼び出し
Custom	`Custom`	カスタムデータプロバイダー（JSON 本文を直接渡します）

IP レスポンスからのフィールドマッピング

マージフィールド構文を使用して、IP レスポンスのフィールドをカードの表示要素にマッピングします。

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 データソースに渡します。

コンテキスト変数	ソース	例
`{recordId}`	現在のレコードページ	関連データをクエリするために IP に渡す
`{userId}`	実行中のユーザー	現在のユーザーでデータを絞り込む
`{param.customKey}`	URL パラメーターまたは親カード	親 FlexCard または URL から渡す

スキル間の連携

スキル	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 コンポーネントを構築します

注意事項

シナリオ	対応方法
データが空の場合	ユーザーフレンドリーなメッセージを表示する明示的な空状態を設定します。生の「No data」や空白のカードは表示しないでください
エラー状態	IP データソースが失敗した場合は、意味のあるエラーメッセージを表示し、デバッグ用にエラーを記録します
モバイル対応	モバイルでは 1 列レイアウトを使用し、横スクロールを避けます。ビューポート幅 320px でテストしてください
長いテキスト値	省略記号で切り詰め、フライアウトまたはツールチップで全文を表示します
大量のレコード	ページネーション付きカードリストを使用し、初期読み込みを 10～25 件に制限します
フィールド値が null の場合	空のラベルを表示するのではなく、条件付き表示を使って null 値のフィールドを非表示にします
データの鮮度が異なる場合	複数のデータソースで更新頻度が異なる場合は、「最終更新」インジケーターを表示します

FlexCard と LWC の選択ガイド

要素	FlexCard	LWC
構築方法	宣言型（ドラッグ＆ドロップ）	コード（JS、HTML、CSS）
データバインディング	Integration Procedure のマージフィールド	Wire Service、Apex、GraphQL
最適な用途	一目で把握できる情報の表示	複雑なインタラクティブ UI
テスト	手動＋データ状態の検証	Jest の単体テスト＋手動
カスタマイズ	OmniStudio フレームワークの範囲内	プラットフォーム全体の柔軟性
再利用	子カードとして埋め込み	子コンポーネントとしてインポート
選択する場合	IP データを使った標準的なカードレイアウト	カスタム動作、アニメーション、複雑な状態

依存関係

必須：OmniStudio（Industries Cloud）ライセンスを持つターゲット組織、認証済みの sf CLI
データソースの場合：ターゲット組織にデプロイ済みの有効な Integration Procedure
アクションの場合：有効な 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 フラグでは、textarea フィールドの JSON を処理できません。作成後、IsActive=true に更新して有効化します。

出力内容

このスキルで作成される成果物：

FlexCard JSON 定義（assets/omni-ui-card.json テンプレート）— REST API による作成またはメタデータのデプロイに対応した OmniUiCard レコード
データソースのバインディングブロック — Integration Procedure の入力と応答フィールドをカード要素にマッピングする DataSourceConfig JSON
カードレイアウト設定 — カードの状態、フィールドの表示、条件付き表示、アクションボタンを定義する PropertySetConfig JSON
検証レポート — 7 カテゴリーにわたる 130 点満点のスコアと、デプロイ／レビュー／ブロックの判定結果
デプロイチェックリスト — 上流の IP が有効であること、FlexCard が有効化されていること、および対象の Lightning ページまたは親 FlexCard に埋め込まれていることを確認

外部リファレンス

OmniStudio FlexCards（Trailhead）— FlexCard の基礎とガイド付きセットアップを学べる公式モジュール
OmniStudio Developer Guide — FlexCard メタデータ、データソース設定、コンポーネントのプロパティに関する技術リファレンス
Salesforce Industries Documentation — レイアウト、状態、アクションを網羅した FlexCard 設定ガイド

リファレンスファイル一覧

ファイル	読むタイミング
`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 コマンド

Markdown 対応

ログインしてコメント

基本情報

作者: forcedotcom
リポジトリ: forcedotcom/sf-skills
カテゴリ: デザイン・UI
インストール数: 2,389
GitHub スター: 1,127

問題を報告