sf-omnistudio

OmniStudio 開発ガイド

Salesforce OmniStudio のスペシャリストとして、OmniScript、FlexCard、Integration Procedure、Data Mapper など、すべての OmniStudio コンポーネントを構築、レビュー、トラブルシューティングします。

OmniStudio の概要

OmniStudio は、コードを使わずにガイド付きデジタルエクスペリエンスを構築するための、Salesforce Industries の宣言型開発フレームワークです。連携して機能する主要なコンポーネントタイプを 4 つ備えています。

コンポーネント	目的	類似するもの
OmniScript	ユーザー操作のための複数ステップのガイド付きウィザード	Screen Flow
FlexCard	データを一目で確認できる UI カード	Lightning Component
Integration Procedure	サーバー側のプロセスオーケストレーション	Apex Service Layer
Data Mapper	データの抽出、変換、読み込み	SOQL + DML の抽象化

コンポーネントの依存関係（下から順に構築します）：

Data Mapper --> Integration Procedure --> OmniScript --> FlexCard
   (data)        (orchestration)          (wizard)      (display)

Data Mapper は Salesforce のデータを読み書きします。Integration Procedure は Data Mapper、Apex、HTTP 呼び出しをオーケストレーションします。OmniScript は、Integration Procedure を呼び出すガイド付き UI を表示します。FlexCard は概要データを表示し、OmniScript を起動できます。

名前空間ガイド

OmniStudio には 3 種類の名前空間があります。コンポーネントのメタデータをクエリする前に、必ず名前空間を検出してください。

名前空間	パッケージ	業界
Core（接頭辞なし）	OmniStudio managed package / Industries Cloud	すべての業界（Spring '22 以降）
vlocity_cmt	Vlocity CMT	通信、メディア、エネルギー
vlocity_ins	Vlocity INS	保険、ヘルスケア

名前空間の検出

各名前空間の既知のオブジェクトをクエリします。INVALID_TYPE エラーが返された場合、その種類はインストールされていません。有効な応答（totalSize: 0 を含む）があれば、その名前空間が使用可能であることを確認できます。

名前空間	テストクエリ	プローブするオブジェクト
Core	sf data query -q "SELECT Id FROM OmniProcess LIMIT 1" -o <org>	OmniProcess
vlocity_cmt	sf data query -q "SELECT Id FROM vlocity_cmt__OmniScript__c LIMIT 1" -o <org>	vlocity_cmt__OmniScript__c
vlocity_ins	sf data query -q "SELECT Id FROM vlocity_ins__OmniScript__c LIMIT 1" -o <org>	vlocity_ins__OmniScript__c

まず Core（最新の方法）を試し、失敗した場合は Vlocity の各種名前空間に切り替えます。

オブジェクト名の対応表

概念	Core	vlocity_cmt	vlocity_ins
OmniScript / IP	OmniProcess	vlocity_cmt__OmniScript__c	vlocity_ins__OmniScript__c
要素	OmniProcessElement	vlocity_cmt__Element__c	vlocity_ins__Element__c
FlexCard	OmniUiCard	vlocity_cmt__VlocityUITemplate__c	vlocity_ins__VlocityUITemplate__c
Data Mapper	OmniDataTransform	vlocity_cmt__DRBundle__c	vlocity_ins__DRBundle__c
Data Mapper 項目	OmniDataTransformItem	vlocity_cmt__DRMapItem__c	vlocity_ins__DRMapItem__c

フィールドレベルの対応表については、references/omnistudio-reference.md を参照してください。

OmniScript

OmniScript は、複数ステップで操作できるガイド付きエクスペリエンス（ウィザード）です。ユーザー入力を収集し、サーバー側のロジックを呼び出して、結果を表示します。これらはすべて宣言型で実現されます。

識別

各 OmniScript は、Type / SubType / Language の 3 つの組み合わせによって一意に識別されます（例：ServiceRequest / NewCase / English）。複数のバージョンが存在する場合がありますが、各組み合わせで有効にできるバージョンは 1 つだけです。

Core 名前空間では、OmniScript は OmniProcess に格納され、IsIntegrationProcedure = false となります。

Element Types

Containers：Step、Conditional Block、Loop Block、Edit Block

Inputs：Text、Text Area、Number、Date、Date/Time、Checkbox、Radio、Select、Multi-select、Type Ahead、File、Currency、Email、Telephone、URL、Signature、Password、Range、Time

Display：Text Block、Headline、Aggregate、Disclosure、Image、Chart

Actions：DataRaptor Extract Action、DataRaptor Load Action、Integration Procedure Action、Remote Action、Navigate Action、Email Action、DocuSign Envelope Action

Logic：Set Values、Validation、Formula、Submit Action

Element Hierarchy

要素は Level と Order の各フィールドを使ってツリーを形成します。Level 0 は Step（ウィザードのページ）です。Level 1 以上は Step 内の要素です。Order によって、同じレベル内の順序が決まります。

Data Flow

OmniScript は、すべてのステップで受け渡される単一の JSON データ構造を維持します。要素はマージフィールド構文（%fieldName%）を使って、この共有 JSON の読み取りと書き込みを行います。アクション要素は、JSON とサーバー呼び出しとの間で入力と出力をマッピングします。

LWC-Enabled OmniScripts

LWC OmniScript は、Aura ではなく Lightning Web Components を使ってレンダリングします。主な違いは次のとおりです。

• ベースコンポーネントとして omnistudio-omniscript を使用します
• カスタム要素は OmniscriptBaseMixin を拡張する必要があります
• CSS スタイルには Aura 固有のクラスではなく、SLDS トークンを使用します
• イベントモデルが異なります（LWC のカスタムイベントと Aura イベント）
• LWC OmniScript 内に Aura コンポーネントを埋め込むことはできません

OmniScript Best Practices

• 使いやすさを考慮し、1 つの Step につき入力要素を 7～10 個に制限します
• すべての必須入力に検証を追加します
• すべてのアクション要素でエラー処理（showError、errorMessage）を設定します
• 条件付き表示（show 式）を使って、関係のないフィールドを非表示にします
• データ読み込みアクションは OmniScript の読み込み時ではなく、ステップ開始時に実行します
• B が A を埋め込んでいる場合に、A を B に埋め込まないでください（循環埋め込みによって無限ループが発生します）
• PropertySetConfig に Salesforce レコード ID をハードコードしないでください

FlexCards

FlexCards は、Integration Procedures、SOQL、REST ソースのデータを使って情報を一目で確認できる、宣言型 UI カードです。

Data Sources

FlexCards は、OmniUiCard の DataSourceConfig JSON フィールドで設定されたデータソースにバインドします。Core namespace では、Vlocity が単一の Definition blob に保存していた内容を、個別の DataSourceConfig フィールドと PropertySetConfig フィールドに分割しています。

Source Type	dataSource.type Value	Use Case
Integration Procedure	IntegrationProcedures（複数形である必要があります）	ライブデータでの主要なパターン
SOQL	SOQL	直接クエリ（抽象化には IP を推奨）
Apex Remote	ApexRemote	カスタム Apex クラスの呼び出し
REST	REST	Named Credential 経由の外部 API

データソースは入力パラメーター（例：{recordId}）を使ってコンテキストを受け渡し、マージ構文 {fieldName} を使ってレスポンスフィールドをカード要素にマッピングします。

Layout Types

Layout	Use Case
Single Card	レコードの概要表示
Card List	配列データからカードを繰り返し表示
Tabbed Card	タブとして複数のビューを表示
Flyout Card	展開可能な詳細パネル

Actions and Child Cards

FlexCards は、コンテキストデータを入力として渡しながら、アクションボタンから OmniScript を起動できます。カードには他の FlexCards を子カードとして埋め込めます（パフォーマンスのため、ネストは 2 レベルまでに制限してください）。LWC FlexCards も同じパターンに従いますが、Lightning Web Components としてレンダリングします。

FlexCard Best Practices

• データソースからレコードが返されない場合に備えて、必ず空状態のメッセージを設定します
• スタイルには SLDS デザイントークンを使用します（色をハードコードしないでください）
• アクセシビリティのため、すべてのインタラクティブ要素に aria-label を追加します
• 子カードのネストは 2 レベルまでに制限します
• デプロイ前に、参照されているすべての Integration Procedures が有効であることを確認します

Integration Procedures

Integration Procedures（IP）は、Data Mapper アクション、Apex 呼び出し、HTTP コールアウト、条件ロジックを組み合わせて、宣言型の複数ステップ処理を実行するサーバーサイドのオーケストレーションです。

識別

IP は Type / SubType のペアをキーとして使用します（例：AccountOnboarding / Standard）。Core 名前空間では、IP は IsIntegrationProcedure = true を設定した OmniProcess に保存されます。

アクションタイプ

要素タイプ	用途	主な PropertySet フィールド
DataRaptor Extract アクション	Salesforce データの読み取り	bundle（Data Mapper 名）
DataRaptor Load アクション	Salesforce データの書き込み	bundle
DataRaptor Transform アクション	インメモリでのデータ再構成	bundle
Remote アクション	Apex クラスのメソッド呼び出し	remoteClass、remoteMethod
Integration Procedure アクション	ネストされた IP の呼び出し	ipMethod（Type_SubType 形式）
HTTP アクション	外部 API の呼び出し	path、method、httpUrl
Matrix アクション	決定テーブルの検索	matrixName
Email アクション	メールの送信	emailTemplateId
Conditional ブロック	分岐ロジック	条件式
Loop ブロック	コレクションの反復処理	ループ元のパス
Set Values	変数の割り当て	キーと値のペア

レスポンスのマッピング

各要素の出力は、レスポンス JSON 内でその要素名の下に名前空間付きで格納されます。下流の入力で上流の出力を参照するには、%elementName:keyPath% 構文を使用します。

キャッシュ

IP は、読み取り中心のオーケストレーションでプラットフォームキャッシュをサポートします。プロシージャの PropertySet で cacheType と cacheTTL を設定します。DML を実行するプロシージャはキャッシュしないでください。キャッシュされた結果では、実際のデータ操作が省略されます。

Integration Procedure のベストプラクティス

• IP をデプロイする前に、参照されるすべての Data Mapper をデプロイします
• ガバナ制限を避けるため、すべての DataRaptor Extract アクションに LIMIT を設定します
• DataRaptor Load アクションをエラーハンドリング（try/catch または条件チェック）で囲みます
• 循環する IP 呼び出しチェーン（A が B を呼び出し、B が A を呼び出す）を作成しないでください
• 独立した要素には並列実行を使用します
• PropertySetConfig に Salesforce ID や API 認証情報をハードコードしないでください
• 外部 API 認証には Named Credentials を使用します

Data Mapper / DataRaptor

Data Mapper（旧 DataRaptor）は、OmniStudio の宣言型データアクセスを提供します。Salesforce オブジェクトに対する Extract、Transform、Load 操作を処理します。

タイプ

タイプ	用途	データの読み取り	データの書き込み	命名プレフィックス
Extract	リレーションをサポートしたレコードのクエリ	はい（SOQL）	いいえ	DR_Extract_
Turbo Extract	大量データ向けのコンパイル済みクエリ（10 倍高速）	はい（コンパイル済み）	いいえ	DR_TurboExtract_
Transform	インメモリでのデータ再構成（JSON から JSON）	いいえ	いいえ	DR_Transform_
Load	レコードの挿入、更新、アップサート、削除	いいえ	はい（DML）	DR_Load_

メタデータ構造

Data Mapper は、親の OmniDataTransform レコードと、フィールドマッピングを格納する OmniDataTransformItem レコードとして保存されます。注意してください。子から親への参照項目には、省略されていない綴りの OmniDataTransformationId が使用されます。開発者はよく、存在しない OmniDataTransformId を誤って指定しようとします。

Turbo Extract の制限事項

Turbo Extract は、数式項目、関連リスト、集計クエリ、多態項目をサポートしていません。これらの場合は標準の Extract を使用してください。

Data Mapper のベストプラクティス

• 常に明示的な項目リストを指定します（ワイルドカードは使用しません）
• すべての Extract クエリに LIMIT とフィルター条件を追加します
• Load Data Mapper をデプロイする前に、項目レベルのセキュリティを検証します
• Load でのレコード重複を防ぐため、アップサートキーを使用します
• デプロイ後に Data Mapper を有効化します（無効なものは呼び出せません）
• PascalCase で DR_[Type]_[Object]_[Purpose] の命名規則を使用します

依存関係のマッピング

OmniStudio コンポーネントは、有向依存関係グラフを形成します。コンポーネントを変更する前に依存関係をたどり、影響を把握してください。

依存関係のソース

コンポーネント	依存関係の格納場所	解析する内容
OmniScript	OmniProcessElement の PropertySetConfig	bundle（Data Mapper）、ipMethod（IP）、omniScriptKey（ネストされた OS）
Integration Procedure	OmniProcessElement の PropertySetConfig	bundle、remoteClass、integrationProcedureKey、httpUrl
FlexCard	OmniUiCard の DataSourceConfig	dataSource.value.ipMethod（IP）、dataSource.value.className（Apex）
Data Mapper	OmniDataTransformItem の InputObjectName / OutputObjectName	ソースとターゲットの sObject

依存関係クエリ（Core 名前空間）

# OmniScript/IP elements with config
sf data query -q "SELECT Id, OmniProcessId, Name, Type, PropertySetConfig FROM OmniProcessElement WHERE OmniProcessId = '<id>'" -o <org> --json

# FlexCard data sources
sf data query -q "SELECT Id, Name, DataSourceConfig FROM OmniUiCard WHERE IsActive = true" -o <org> --json

# Data Mapper object references
sf data query -q "SELECT Id, OmniDataTransformationId, InputObjectName, OutputObjectName FROM OmniDataTransformItem" -o <org> --json

影響分析

コンポーネントを変更する際は、上流にあるすべての依存元をたどります。

1. Data Mapper を変更しますか？その bundle 名を参照しているすべての IP と OmniScript を見つけます
2. IP を変更しますか？一致する ipMethod を持つすべての OmniScript と、一致するデータソースを持つ FlexCard を見つけます
3. OmniScript を変更しますか？その OmniScript を対象とする起動アクションを持つすべての FlexCard を見つけます
4. 有効なコンポーネントと無効なコンポーネントの両方を確認します。無効なコンポーネントは後で有効になる可能性があります

移行パターン

Vlocity から OmniStudio Core への移行

Vlocity（vlocity_cmt または vlocity_ins）から OmniStudio Core に移行する場合：

1. インベントリ作成：分析クエリを使用して、ソース名前空間内のすべてのコンポーネントを一覧化します
2. 名前空間の変換：すべてのオブジェクト名とフィールド API 名を、Vlocity から Core の相当する名前に対応付けます（上記の Namespace Guide を参照）
3. エクスポート：ソース組織からコンポーネント定義を JSON として抽出します
4. 変換：PropertySetConfig、DataSourceConfig、要素設定内の名前空間プレフィックス付きフィールド参照を変換します
5. デプロイ順序：まず Data Mapper、次に Integration Procedure、続いて OmniScript、最後に FlexCard をデプロイします
6. 検証：ターゲット組織で各コンポーネントを実行し、エンドツーエンドでデータフローを検証します
7. 廃止：Core の相当するコンポーネントが検証されてから、Vlocity のコンポーネントを無効化します

主な変換箇所：

• vlocity_cmt__OmniScript__c は OmniProcess になります
• vlocity_cmt__PropertySet__c は PropertySetConfig になります
• vlocity_cmt__DRBundle__c は OmniDataTransform になります
• FlexCard の vlocity_cmt__Definition__c は OmniUiCard の DataSourceConfig になります
• IsIntegrationProcedure ブール値により、Core では OmniScript と IP が区別されます

注意事項

問題	詳細
名前空間の競合	移行中は、旧名前空間と新名前空間の両方のオブジェクトが存在する場合があります。クエリを実行する前に、必ず名前空間を検出してください。
DataRaptor と Data Mapper の名称	「DataRaptor」は旧名称です。Core 名前空間では「Data Mapper」という用語と OmniDataTransform API 名を使用しますが、PropertySetConfig 内の要素タイプには引き続き「DataRaptor」と記載されています。
バージョン管理	Type／SubType／Language の組み合わせごとに、有効化できるバージョンは 1 つだけです。新しいバージョンを有効化すると、以前のバージョンは自動的に無効化されます。
LWC と Aura の OmniScripts	LWC OmniScripts には Aura コンポーネントを埋め込めません。CSS クラスも異なります。イベント処理も異なります。移行する場合は、両方をテストしてください。
DML を伴う IP のキャッシュ	DML を実行する IP をキャッシュすると、キャッシュヒット時に DML が通知なくスキップされます。書き込み操作は決してキャッシュしないでください。
デプロイ順序	コンポーネントは依存関係の下位から順にデプロイする必要があります。Data Mappers、IP、OmniScripts、FlexCards の順です。順序を誤ってデプロイすると、参照が壊れます。
Core では FlexCard の設定の保存方法が異なる	Core 名前空間の OmniUiCard では、設定が DataSourceConfig フィールドと PropertySetConfig フィールドに分割されています。Vlocity のような単一の Definition blob はありません。
OmniProcessType は自動計算される	OmniProcess の OmniProcessType 選択リストは、IsIntegrationProcedure から導出されます。作成時に直接設定することはできません。
CLI で JSON フィールドを含むレコードを作成できない	JSON を含むテキストエリアフィールド（PropertySetConfig など）は、sf data create record を失敗させます。代わりに、sf api request rest --body @file.json を使用してレコード全体の本文を POST してください。
外部キーのスペルに関する注意点	OmniDataTransformItem は OmniDataTransformationId を介して親にリンクします。このフィールドは長い形式のスペルを使用しているため、短い形式を使用したクエリでは問題が発生します。
データソースタイプは複数形	FlexCard が IP を呼び出すよう設定する場合、dataSource.type の値は IntegrationProcedures である必要があります。単数形では通知なく失敗します。
ドラフトコンポーネント	ドラフトの Data Mappers は sf project retrieve start では取得できません。有効化済みのものだけ取得できます。

ワークフロー

1. 上記のプローブクエリを使用して、名前空間を検出します
2. 既存のコンポーネントを棚卸しします -- すべての OmniScripts、IP、FlexCards、Data Mappers をクエリします
3. 変更を加える前に、コンポーネント間の依存関係をマッピングします
4. 下位から構築します -- Data Mappers、IP、OmniScripts、FlexCards の順です
5. 参照が壊れないよう、依存関係の順にデプロイします
6. デプロイ後にコンポーネントを有効化します（無効なコンポーネントは実行時に呼び出せません）
7. エンドツーエンドでテストします -- Data Mapper から IP を経て OmniScript／FlexCard へデータが流れることを確認します

CLI クイックリファレンス

# List OmniScripts
sf data query -q "SELECT Id,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE IsIntegrationProcedure=false" -o <org>

# List Integration Procedures
sf data query -q "SELECT Id,Type,SubType,IsActive FROM OmniProcess WHERE IsIntegrationProcedure=true" -o <org>

# List FlexCards
sf data query -q "SELECT Id,Name,IsActive FROM OmniUiCard" -o <org>

# List Data Mappers
sf data query -q "SELECT Id,Name,Type,IsActive FROM OmniDataTransform" -o <org>

# Retrieve OmniStudio metadata
sf project retrieve start -m OmniScript:<Name> -o <org>
sf project retrieve start -m OmniIntegrationProcedure:<Name> -o <org>
sf project retrieve start -m OmniUiCard:<Name> -o <org>
sf project retrieve start -m OmniDataTransform:<Name> -o <org>

# Deploy OmniStudio metadata (respect dependency order)
sf project deploy start -m OmniDataTransform -o <org>
sf project deploy start -m OmniIntegrationProcedure -o <org>
sf project deploy start -m OmniScript -o <org>
sf project deploy start -m OmniUiCard -o <org>

参考資料

• OmniStudio リファレンス -- 名前空間のフィールドマッピング、メタデータ構造、要素タイプ、デプロイ順序、移行チェックリスト