sf-industry-commoncore-flexcard: OmniStudio FlexCard 作成と検証

Salesforce Industries 向け FlexCard UI コンポーネント専門の OmniStudio エンジニア。一目で分かる情報を表示する本番環境対応の FlexCard 定義を生成します。宣言的なデータバインディング、Integration Procedure データソース、条件付きレンダリング、適切な SLDS スタイルに対応しています。すべての FlexCards は 7つのカテゴリにわたる130ポイントスコアリングルーブリック に対して検証されます。

主要責務

1. FlexCard オーサリング: 適切なレイアウト、状態、フィールドマッピングで FlexCard 定義を設計・構築
2. データソースバインディング: 正しいフィールドマッピングとエラーハンドリングで Integration Procedure データソースを構成
3. テスト生成: 複数のデータ状態 (データ入力済み、空、エラー、複数レコード) に対してカードを検証
4. ドキュメント: データソース系統とアクション マッピングを含むデプロイ対応ドキュメントを作成

ドキュメントマップ

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

---

重大事項: オーケストレーション順序

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

sf-industry-commoncore-omnistudio-analyze → sf-industry-commoncore-datamapper → sf-industry-commoncore-integration-procedure → sf-industry-commoncore-omniscript → sf-industry-commoncore-flexcard (ここにいます)

FlexCards は Integration Procedures からデータを消費し、OmniScripts を起動できます。まずデータレイヤーを構築し、次にプレゼンテーション層を構築します。

---

主要な洞察

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

---

ワークフロー (5フェーズパターン)

フェーズ 1: 要件収集

構築前に、ステークホルダーにこれらを明確にしてください:

質問	重要な理由
カードの目的は何か?	レイアウトタイプとデータ密度を決定します
どのデータソースが必要か?	必要な Integration Procedures を特定します
どのオブジェクトコンテキストで実行されるか?	レコードレベルとリストレベルの表示を決定します
カードが公開すべきアクションは何か?	ボタン/リンク設定と OmniScript 統合を推進します
ユースケースに最適なレイアウトは何か?	単一カード、リスト、タブ付き、またはフライアウト
条件付き表示ルールはあるか?	データ値に基づいて表示/非表示になるフィールドまたはセクション

フェーズ 2: 設計とレイアウト

カードレイアウトオプション

レイアウトタイプ	ユースケース	説明
単一カード	レコードサマリー	単一レコードのフィールドを表示する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 テンプレート
カスタムアクション	Platform イベント、LWC など	ペイロードマッピング付きカスタムアクションハンドラー

条件付き表示

• データ値に基づいて可視性条件を使用してフィールドを表示/非表示
• データソース結果に基づいてカード状態全体を表示/非表示
• データソースがレコードを返さない場合、空状態メッセージを表示

フェーズ 3: 生成と検証

1. FlexCard 定義 JSON を生成
2. すべてのデータソース参照がアクティブな Integration Procedures に解決されることを検証
3. 130ポイントスコアリングルーブリックを実行 (スコアリングセクションを参照)
4. マージフィールド構文が IP レスポンス構造と一致することを確認
5. すべてのインタラクティブ要素のアクセシビリティ属性をチェック

フェーズ 4: デプロイ

1. すべての上流 Integration Procedures がデプロイされてアクティブであることを確認
2. FlexCard メタデータ (OmniUiCard) をデプロイ
3. ターゲット org で FlexCard をアクティベート
4. ターゲット Lightning ページ、OmniScript、または親 FlexCard に FlexCard を埋め込み

フェーズ 5: テスト

複数のデータシナリオに対して各 FlexCard をテストします:

シナリオ	検証項目
データ入力済み	すべてのフィールドが正しくレンダリングされ、マージフィールドが解決される
空データ	空状態メッセージが表示され、マージフィールドが破断していない
エラー状態	IP がエラーを返すかタイムアウトする場合、優雅に処理される
複数レコード	カードリストが正しい数のアイテムをレンダリングし、ページネーションが機能する
アクションボタン	OmniScript が正しい事前入力されたデータで起動される
条件付きフィールド	可視性ルールがデータ値に基づいて正しく切り替わる
モバイル	カードレイアウトがより小さいビューポート幅に適応する

---

生成ガードレール

FlexCard 定義を生成するときにこれらのパターンを避けます:

アンチパターン	何が間違っているか	正しいアプローチ
存在しない IP データソースを参照	カードは実行時にデータをロードできない	バインド前に IP が存在してアクティブであることを確認
スタイル内のハードコード色	SLDS テーマとダークモードを破損	SLDS デザイントークンと CSS カスタムプロパティを使用
アクセシビリティ属性がない	WCAG コンプライアンス失敗	aria-label、role、キーボードハンドラーを追加
過度にネストされた子カード	ネストが深いとパフォーマンスが低下	最大2レベルのネストに制限。可能な限りフラット化
空状態を無視	データソースがレコードを返さない場合、UI が破損	明示的な空状態メッセージを設定
ハードコードされたレコード ID	カードは環境全体で破損	マージフィールドとコンテキスト駆動パラメータを使用

---

スコアリングルーブリック (130ポイント)

すべての FlexCards は7つのカテゴリに対して検証されます。閾値: ✅ 90+ (デプロイ) | ⚠️ 67-89 (レビュー) | ❌ <67 (ブロック - 修正必須)

カテゴリ	ポイント	基準
設計とレイアウト	25	適切なレイアウトタイプ、論理的フィールドグループ化、レスポンシブ設計、一貫した間隔、明確な視覚階層
データバインディング	20	正しい IP 参照、適切なマージフィールド構文、入力パラメータマッピング、マルチソース調整
アクションとナビゲーション	20	アクションボタンが正しく設定、OmniScript 起動パラム マッピング、ナビゲーションターゲット有効、アクションラベルが説明的
スタイル	20	SLDS トークン使用 (ハードコード色なし)、一貫したタイポグラフィ、カード/タイルパターンの適切な使用、ダークモード互換
アクセシビリティ	15	インタラクティブ要素の aria-label、キーボードナビゲート可能なアクション、十分な色コントラスト、スクリーンリーダーフレンドリーなフィールドラベル
テスト	15	データ入力済み、空状態、エラー状態、複数レコードシナリオ、モバイルビューポートで検証済み
パフォーマンス	15	データソース呼び出しが最小化、子カードネストが制限 (最大2レベル)、冗長な IP 呼び出しなし、非表示状態のレイジーロード

スコアリング内訳詳細

設計とレイアウト (25ポイント)

基準	ポイント	説明
レイアウトタイプがユースケースと一致	5	単一、リスト、タブ付き、またはフライアウトが適切に選択されている
フィールドグループ化が論理的	5	関連フィールドが視覚的にグループ化されている
レスポンシブ動作	5	カードがさまざまなビューポート幅に適応する
一貫した間隔	5	マージンとパディングが SLDS 間隔スケールに従う
視覚階層	5	主要情報が目立ち、次要情報が強調解除されている

データバインディング (20ポイント)

基準	ポイント	説明
IP 参照が有効	5	すべての参照 IP が存在してアクティブ
マージフィールド構文が正確	5	{datasource.field} パスが実際の IP レスポンスフィールドに解決される
入力パラメータがマップ	5	レコードコンテキストが IP 入力に正しく渡される
マルチソース調整	5	複数のデータソースが正しい順序でロードされ、衝突しない

アクションとナビゲーション (20ポイント)

基準	ポイント	説明
アクションボタン機能	5	すべてのボタンが設定されたアクションをトリガーする
OmniScript パラムマップ	5	コンテキストデータが起動された OmniScripts に正しく流れる
ナビゲーションターゲット有効	5	レコードと URL ナビゲーションが正しく解決される
ラベルが説明的	5	アクションラベルがアクション内容を明確に伝える

スタイル (20ポイント)

基準	ポイント	説明
SLDS トークン使用	5	色、フォント、間隔はデザイントークン経由
一貫したタイポグラフィ	5	テキストサイズが SLDS タイプスケールに従う
カードパターン準拠	5	標準 SLDS カードまたはタイルパターンを使用
ダークモード互換	5	ハードコード色がなく、SLDS ダークテーマで機能する

アクセシビリティ (15ポイント)

基準	ポイント	説明
インタラクティブ要素の ARIA ラベル	5	ボタン、リンク、入力がアクセス可能な名前を持つ
キーボードナビゲート可能	5	すべてのアクションが Tab 経由で到達可能、Enter/Space で起動
色コントラストが十分	5	WCAG 2.1 AA コントラスト比 (テキスト 4.5:1) を満たす

テスト (15ポイント)

基準	ポイント	説明
データ入力済み検証	3	カードが完全なデータで正しくレンダリングされる
空状態検証	3	空状態メッセージが正しく表示される
エラー状態検証	3	IP エラーを優雅に処理する
複数レコード検証	3	カードリストが正しいアイテムをレンダリングする
モバイルビューポート検証	3	レイアウトが小さい画面に適応する

パフォーマンス (15ポイント)

基準	ポイント	説明
データソース呼び出し最小化	5	冗長または重複する IP 呼び出しがない
子カードネスト制限	5	ネストされた子カードの最大2レベル
非表示状態のレイジーロード	5	非表示タブ/フライアウトはオンデマンドでロード

---

CLI コマンド

# org 内のアクティブな FlexCards をクエリ
sf data query -q "SELECT Id,Name,DataSourceConfig,PropertySetConfig,IsActive FROM OmniUiCard WHERE IsActive=true" -o <org>

# 名前で特定の FlexCard を取得
sf project retrieve start -m OmniUiCard:<Name> -o <org>

# ターゲット org に FlexCard をデプロイ
sf project deploy start -m OmniUiCard:<Name> -o <org>

# すべての FlexCards を取得
sf project retrieve start -m OmniUiCard -o <org>

# すべての OmniStudio メタデータ (FlexCards + 依存関係) をデプロイ
sf project deploy start -m OmniUiCard -m OmniIntegrationProcedure -m OmniScript -o <org>

---

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

FlexCard データソース設定

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

重要: Core namespace の OmniUiCard に Definition フィールドはありません。データソース用に DataSourceConfig を使用し、レイアウト用に PropertySetConfig を使用します。

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

データソースタイプ

タイプ	dataSource.type	使用時期
Integration Procedure	IntegrationProcedures (複数形、P は大文字)	プライマリパターン。ライブデータ用に IP を呼び出す
SOQL	SOQL	直接クエリ (抽象化用に IP を優先)
Apex Remote	ApexRemote	カスタム Apex クラス呼び出し
REST	REST	Named Credential 経由の外部 API 呼び出し
カスタム	Custom	カスタムデータプロバイダー (JSON 本体を直接渡す)

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

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

IP レスポンス:                    FlexCard マージフィールド:
─────────────                   ─────────────────────
{ "Name": "Acme Corp" }   →    {Name}
{ "Account": {            →    {Account.Name}
    "Name": "Acme Corp"
  }
}
{ "records": [             →    {records[0].Name}  (単一)
    { "Name": "Acme" }          または Card List レイアウトで反復
  ]
}

入力パラメータマッピング

ホスティングページからホストページから IP データソースにコンテキストを渡します:

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

---

クロススキル統合

スキル	sf-industry-commoncore-flexcard との関係
sf-industry-commoncore-integration-procedure	FlexCards が消費する IP データソースを構築
sf-industry-commoncore-omniscript	FlexCard アクションボタンが起動する OmniScripts を構築
sf-industry-commoncore-datamapper	IPs が内部で使用する DataRaptors/DataMappers を構築
sf-industry-commoncore-omnistudio-analyze	FlexCards、IPs、OmniScripts 全体の依存関係チェーンを分析
sf-deploy	上流の依存関係と共に FlexCard メタデータをデプロイ
sf-lwc	FlexCards 内に埋め込むカスタム LWC コンポーネントを構築

---

エッジケース

シナリオ	処理
空データ	明示的な空状態をユーザーフレンドリーなメッセージで設定。生の「データなし」または空白カードを表示しない
エラー状態	IP データソースが失敗する場合、意味のあるエラーメッセージを表示。デバッグ用にエラーをログ
モバイルレスポンシブ性	モバイル用に単一列レイアウトを使用。水平スクロールを避ける。320px ビューポート幅でテスト
長いテキスト値	省略記号で切り詰めて、完全なテキストのフライアウトまたはツールチップを提供
大規模レコードセット	カードリストとページネーションを使用。初期ロードを 10-25 レコードに制限
Null フィールド値	空のラベルを表示するのではなく、条件付き可視性を使用して null 値のフィールドを非表示
混合データ鮮度	複数のデータソースが異なるリフレッシュレート持つ場合、「最終更新」インジケーターを表示

---

FlexCard と LWC の決定ガイド

要因	FlexCard	LWC
構築方法	宣言的 (ドラッグ&ドロップ)	コード (JS、HTML、CSS)
データバインディング	Integration Procedure マージフィールド	Wire サービス、Apex、GraphQL
最適用途	一目で分かる情報表示	複雑なインタラクティブ UI
テスト	手動 + データ状態検証	Jest ユニットテスト + 手動
カスタマイズ	OmniStudio フレームワークに制限	フルプラットフォーム柔軟性
再利用	子カードとして埋め込み	子コンポーネントとしてインポート
選択時期	標準カードレイアウトと IP データ	カスタム動作、アニメーション、複雑な状態

---

依存関係

必須: OmniStudio (Industries Cloud) ライセンス付きターゲット org、認証済み sf CLI データソース用: デプロイ済みのアクティブな Integration Procedures アクション用: デプロイ済みのアクティブな OmniScripts (アクションボタンが OmniScripts を起動する場合) スコアリング: スコアが 67 未満の場合、デプロイをブロック

FlexCards をプログラムで作成: 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 を更新してアクティベートします。

---

外部リファレンス

• OmniStudio FlexCards Trailhead - 公式学習モジュール
• OmniStudio Developer Guide - 技術リファレンス
• Salesforce Industries Documentation - FlexCard 設定ガイド

---

ライセンス

MIT License。 Copyright (c) 2026 David Ryan (weytani)