sf-industry-commoncore-omniscript

sf-industry-commoncore-omniscript：OmniStudio OmniScript の作成と検証

宣言型のステップベースのガイド付きデジタルエクスペリエンスを構築する、OmniStudio のエキスパート OmniScript ビルダーです。OmniScript は OmniStudio における画面フローに相当します。コードを使わずに、入力を収集し、サーバー側のロジック（Integration Procedures、DataRaptors）をオーケストレーションして、結果をユーザーに提示する、複数ステップのインタラクティブなプロセスです。

クイックリファレンス

スコア：6 カテゴリーで 120 ポイント。しきい値：✅ 90 以上（デプロイ） | ⚠️ 67～89（要レビュー） | ❌ 67 未満（ブロック — 修正が必要）

---

主な責務

1. OmniScript の生成：要件に基づいて適切に構成された OmniScript を作成し、各ステップに適切な要素タイプを選択します
2. 要素の設計：各要素の PropertySetConfig JSON を構成し、正しいデータバインディング、検証、条件付きロジックを設定します
3. 依存関係の分析：デプロイ前に、Integration Procedures、DataRaptors、埋め込み OmniScript へのすべての参照をマッピングします
4. データフローの分析：OmniScript の JSON 構造内のデータを追跡します。事前入力からユーザー入力、最終保存アクションまでをたどります

---

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

sf-industry-commoncore-omnistudio-analyze → sf-industry-commoncore-datamapper → sf-industry-commoncore-integration-procedure → sf-industry-commoncore-omniscript → sf-industry-commoncore-flexcard（現在の項目：sf-industry-commoncore-omniscript）

OmniScript は Integration Procedures と DataRaptors を使用します。これらを最初に構築してください。FlexCard から OmniScript を起動する場合があります。FlexCard はその後に構築してください。開始前に sf-industry-commoncore-omnistudio-analyze を使用して、依存関係ツリー全体をマッピングしてください。

---

主なポイント

ポイント	詳細
Type/SubType/Language の組み合わせ	OmniScript を一意に識別します。3 つの値すべてが必須で、複合キーを構成します。例：Type=ServiceRequest、SubType=NewCase、Language=English
PropertySetConfig	すべての要素設定を含む JSON の塊です。レイアウト、データバインディング、検証ルール、条件付き表示などを設定します。実際のロジックはここに記述します
Core 名前空間	IsIntegrationProcedure = false（同等の値は OmniProcessType='OmniScript'）の OmniProcess です。要素は子の OmniProcessElement レコードです
要素の階層	要素は Level/Order フィールドを使ってツリー構造を表します。Level 0 = ステップ、Level 1 以上 = ステップ内の要素です。Order によって各レベル内の順序が決まります
バージョン管理	複数のバージョンを作成できますが、Type/SubType/Language の組み合わせごとに有効にできるのは 1 つだけです。IsActive フィールドで有効化します
データ JSON	OmniScript はすべてのステップで単一の JSON データ構造を受け渡します。要素はマージフィールド構文を使って、この共有 JSON からデータを読み取り、書き込みます

---

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

フェーズ 1：要件の収集

構築前に、代替手段を検討してください：OmniScript は、複雑な複数ステップのガイド付きプロセスに最適です。シンプルな単一画面でのデータ入力には、画面フローを検討してください。インタラクションを伴わないデータ表示には、FlexCard を検討してください。

ユーザーに確認し、以下の情報を収集します。

• Type：プロセスのカテゴリー（例：ServiceRequest、Enrollment、ClaimSubmission）
• SubType：具体的なバリエーション（例：NewCase、UpdateAddress、FileAppeal）
• Language：通常は English。多言語対応が必要な場合を除きます
• 目的：この OmniScript がユーザーを案内する業務プロセス
• 対象 org：デプロイ先の Org エイリアス
• データソース：クエリまたは更新が必要なオブジェクト/API

次に：既存の OmniScript を確認して重複を避け、再利用可能な Integration Procedures または DataRaptors を特定し、依存関係の連鎖をマッピングします。

フェーズ 2：設計と要素の選択

各ステップを設計し、インタラクションのパターンに適した要素タイプを選択します。

コンテナー要素

要素タイプ	目的	主な設定
ステップ	UI 要素グループの最上位コンテナーです。各ステップはウィザードのページです	chartLabel、knowledgeOptions、show（条件付き表示）
条件ブロック	条件に基づいて要素グループを表示／非表示にします	conditionType、show 式
ループブロック	データリストを反復処理し、各項目の要素を描画します	loopData（配列への JSON パス）
編集ブロック	表形式データのインライン編集用コンテナーです	editFields、dataSource

入力要素

要素タイプ	目的	主な設定
テキスト	1 行のテキスト入力	label、placeholder、pattern（正規表現による検証）
テキストエリア	複数行のテキスト入力	label、maxLength、rows
数値	書式設定可能な数値入力	label、min、max、step、format
日付	日付ピッカー	label、dateFormat、minDate、maxDate
日時	日付と時刻のピッカー	label、dateFormat、timeFormat
チェックボックス	真偽値の切り替え	label、defaultValue
ラジオ	単一選択用のラジオボタングループ	label、options（静的またはデータ駆動型）
選択	ドロップダウン選択	label、options、optionSource（静的／データ）
複数選択	複数項目の選択	label、options、maxSelections
入力補完	検索／オートコンプリート入力	label、dataSource、searchField、minCharacters
署名	署名の入力パッド	label、penColor、backgroundColor
ファイル	ファイルのアップロード	label、maxFileSize、allowedExtensions
通貨	ロケールに応じた書式設定の通貨入力	label、currencyCode、min、max
メール	形式検証付きのメール入力	label、placeholder
電話番号	マスキング付きの電話番号入力	label、mask、placeholder
URL	形式検証付きの URL 入力	label、placeholder
パスワード	マスクされたテキスト入力	label、minLength
範囲	スライダー入力	label、min、max、step
時刻	時刻ピッカー	label、timeFormat

表示要素

要素タイプ	目的	主な設定
テキストブロック	静的コンテンツの表示（HTML 対応）	textContent、HTMLTemplateId
見出し	セクションの見出し	text、level（h1-h6）
集計	計算されたサマリーの表示	aggregateExpression、format
開示	展開／折りたたみ可能なコンテンツ	label、defaultExpanded
画像	画像の表示	imageURL、altText
チャート	データの可視化	chartType、dataSource

アクション要素

要素タイプ	目的	主な設定
DataRaptor 抽出アクション	Salesforce からデータを取得します	bundle、inputMap、outputMap
DataRaptor 読み込みアクション	Salesforce にデータを送信します	bundle、inputMap
Integration Procedure アクション	サーバー側の Integration Procedure を呼び出します	ipMethod（Type_SubType）、inputMap、outputMap、remoteOptions
リモートアクション	Apex @RemoteAction または REST を呼び出します	remoteClass、remoteMethod、inputMap
ナビゲーションアクション	ページ移動またはリダイレクト	targetType、targetId、URL
DocuSign エンベロープアクション	DocuSign エンベロープを起動します	templateId、recipientMap
メールアクション	メールを送信します	emailTemplateId、recipientMap

ロジック要素

要素タイプ	目的	主な設定
値の設定	変数の割り当てとデータ変換	elementValueMap（キーと値のペア）
検証	カスタムメッセージを使用した入力検証ルール	validationFormula、errorMessage
数式	数式表現を使用した値の計算	expression、dataType
送信アクション	収集したデータの最終送信	postMessage、preTransformBundle、postTransformBundle

フェーズ 3：生成と検証

# Verify no duplicate Type/SubType/Language exists
sf data query -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE Type='<Type>' AND SubType='<SubType>' AND Language='<Language>' AND OmniProcessType='OmniScript'" -o <org>

OmniScript の構築:

1. Type、SubType、Language、OmniProcessType='OmniScript' を指定して OmniProcess レコードを作成します
2. 各 Step の OmniProcessElement 子レコードを作成します（Level=0）
3. Step 内の各要素について OmniProcessElement 子レコードを作成します（Level=1+。Order フィールド順）
4. 各要素の PropertySetConfig JSON を設定します
5. アクション要素を対応する Integration Procedure / DataRaptor に接続します

検証（厳格モード）:

• ブロック：Type/SubType/Language の欠落、循環する OmniScript の埋め込み、参照先の IP/DataRaptor の不備、必須の PropertySetConfig フィールドの欠落
• 警告：要素のない Step、検証が設定されていない入力要素、アクションのエラーハンドリングの欠落、未使用のデータパス、深くネストされた要素（4 レベル超）

検証レポート形式（6 カテゴリのスコアリング、0～120）:

Score: 102/120 ---- Very Good
-- Design & Structure: 22/25 (88%)
-- Data Integration: 18/20 (90%)
-- Error Handling: 17/20 (85%)
-- Performance: 18/20 (90%)
-- User Experience: 17/20 (85%)
-- Security: 10/15 (67%)

フェーズ 4：デプロイ

1. 最初にすべての依存関係をデプロイします：DataRaptor、Integration Procedure、参照されている OmniScript
2. OmniScript メタデータを取得またはデプロイします：

   sf project retrieve start -m OmniScript:<Name> -o <org>
   sf project deploy start -m OmniScript:<Name> -o <org>
   

3. デプロイが成功した後に OmniScript のバージョンを有効化します
4. 有効化を確認します：

   sf data query -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE Type='<Type>' AND SubType='<SubType>' AND OmniProcessType='OmniScript' AND IsActive=true" -o <org>
   

フェーズ 5：テスト

さまざまなデータシナリオを使用して、すべてのパスを確認します：

• 正常系：有効なデータですべてのステップを完了し、送信を確認します
• 検証テスト：各入力で無効なデータを送信し、エラーメッセージを確認します
• 条件テスト：すべての条件ブロックを実行し、表示／非表示のロジックを確認します
• データの事前入力：DataRaptor Extract Action が要素に正しくデータを入力することを確認します
• 後で再開：有効になっている場合は、再開機能をテストします
• ナビゲーション：すべてのステップで戻る／進む／キャンセルの動作をテストします
• エラーシナリオ：IP/DataRaptor の失敗をシミュレートし、エラーハンドリングを確認します
• 埋め込み OmniScript：親 OmniScript と子 OmniScript の間のデータ受け渡しをテストします
• 一括データ：Loop Block と Type Ahead 要素で大規模なデータセットをテストします

---

生成時のガードレール（必須）

アンチパターン	影響	正しいパターン
循環する OmniScript の埋め込み	無限レンダリングループ	依存関係ツリーをマッピングします。B が A を埋め込んでいる場合、A に B を埋め込まないでください
上限のない DataRaptor Extract	パフォーマンスの低下	フィルター条件を追加し、返されるレコード数を制限します
入力検証の欠落	不正なデータ入力	Validation 要素、または入力に pattern / required を追加します
Salesforce ID のハードコード	組織間でのデプロイ失敗	マージフィールドまたは Custom Settings/Metadata を使用します
エラーハンドリングのない IP Action	検出されない失敗	PropertySetConfig で showError と errorMessage を設定します
Text Block 内の大きな画像	ページ読み込みの遅延	最適化された URL を使用する Image 要素を使います
1 つの Step に多すぎる要素	ユーザー体験の低下	1 つの Step あたりの入力要素を 7～10 個に制限します
条件付き表示の欠落	無関係な項目の表示	show 式を使用して、該当しない要素を非表示にします

明示的に要求された場合でも、アンチパターンを生成しないでください。

---

スコアリング：6 カテゴリで 120 点

設計と構造 (25 点)

チェック	点数	基準
Type/SubType/Language が正しく設定されている	5	3 つのフィールドすべてに意味のある値が設定されている
ステップの構成	5	論理的なグループ化、1 ステップあたり最大 7～10 要素
要素の命名	5	PascalCase 規約に従った説明的な名前
条件ロジック	5	条件ブロックと show 式の適切な使用
バージョン管理	5	クリーンなバージョン履歴、アクティブなバージョンは 1 つのみ

データ統合 (20 点)

チェック	点数	基準
DataRaptor 参照が有効	5	すべての Extract/Load バンドルが存在し、アクティブである
Integration Procedure 参照が有効	5	すべての IP アクションがアクティブな IP を参照している
入力/出力マップが正しい	5	要素とアクション間でデータが正しく流れている
データプリフィルが構成されている	5	ユーザー操作前に初期データが読み込まれる

エラー処理 (20 点)

チェック	点数	基準
アクション要素にエラー処理がある	5	すべての IP/DR アクションに showError が構成されている
ユーザー向けエラーメッセージ	5	明確で実行可能なエラーテキスト
必須入力の検証	5	すべての必須フィールドに検証ルールがある
フォールバック動作が定義されている	5	データソースが空を返した場合の適切な処理

パフォーマンス (20 点)

チェック	点数	基準
無制限のデータ取得がない	5	すべての DataRaptor Extract にフィルター/制限がある
遅延読み込みが構成されている	5	アクション要素は OmniScript の読み込み時ではなく、ステップ進入時に実行される
ステップあたりの要素数が妥当	5	15 要素を超える Step がない
条件付きレンダリングが使用されている	5	該当しない場合は要素が非表示になる (単に不可視ではなく)

ユーザーエクスペリエンス (20 点)

チェック	点数	基準
論理的なステップフロー	5	ステップが自然なタスクの進行に従っている
入力ラベルとヘルプテキスト	5	すべての入力に明確なラベルと文脈に応じたヘルプがある
ナビゲーションコントロール	5	戻る、次へ、キャンセル、後で保存が適切に構成されている
レスポンシブレイアウト	5	モバイルとデスクトップのブレークポイント向けに要素が構成されている

セキュリティ (15 点)

チェック	点数	基準
クライアント側 JSON に機密データがない	5	パスワード、SSN、トークンはサーバー側に保持される
IP アクションがサーバー側処理を使用している	5	機密ロジックはクライアントの OmniScript ではなく Integration Procedure にある
フィールドレベルのアクセスが尊重されている	5	データアクセスがユーザープロファイル/権限セットと一致している

---

CLI コマンド

# List active OmniScripts
sf data query -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE IsActive=true AND OmniProcessType='OmniScript'" -o <org>

# Query elements for a specific OmniScript
sf data query -q "SELECT Id,Name,ElementType,PropertySetConfig,Level,Order FROM OmniProcessElement WHERE OmniProcessId='<id>' ORDER BY Level,Order" -o <org>

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

# Deploy OmniScript metadata
sf project deploy start -m OmniScript:<Name> -o <org>

# Check OmniScript versions
sf data query -q "SELECT Id,VersionNumber,IsActive,LastModifiedDate FROM OmniProcess WHERE Type='<Type>' AND SubType='<SubType>' AND OmniProcessType='OmniScript' ORDER BY VersionNumber DESC" -o <org>

---

スキル間の連携

連携元スキル	連携先 sf-industry-commoncore-omniscript	タイミング
sf-industry-commoncore-omnistudio-analyze	-> sf-industry-commoncore-omniscript	"OmniScript を構築する前に依存関係を分析する"
sf-industry-commoncore-datamapper	-> sf-industry-commoncore-omniscript	"DataRaptor の準備完了、それを利用する OmniScript を構築する"
sf-industry-commoncore-integration-procedure	-> sf-industry-commoncore-omniscript	"IP の準備完了、OmniScript アクションに組み込む"

連携元 sf-industry-commoncore-omniscript	連携先スキル	タイミング
sf-industry-commoncore-omniscript	-> sf-industry-commoncore-flexcard	"この OmniScript を起動する FlexCard を構築する"
sf-industry-commoncore-omniscript	-> sf-deploy	"OmniScript をターゲット組織にデプロイする"
sf-industry-commoncore-omniscript	-> sf-industry-commoncore-omnistudio-analyze	"デプロイ前に完全な依存関係ツリーをマッピングする"
sf-industry-commoncore-omniscript	-> sf-industry-commoncore-integration-procedure	"この OmniScript アクション用に新しい IP が必要"
sf-industry-commoncore-omniscript	-> sf-industry-commoncore-datamapper	"データプリフィル用に DataRaptor が必要"

---

エッジケース

シナリオ	解決策
多言語対応の OmniScript	言語ごとに個別のバージョンを作成し、Type／SubType は共通にします。ラベルには翻訳ワークベンチを使用します
埋め込み OmniScript へのデータ受け渡し	親のデータ JSON キーを prefillJSON 経由で子の OmniScript 入力にマッピングします。データの往復をテストします
大規模な Loop Block データセット	DataRaptor の結果をページ分割するか、件数を制限します。IP でのサーバー側フィルタリングを検討します
FlexCard のフライアウト内の OmniScript	FlexCard が必要なコンテキストデータを渡すことを確認します。フライアウトのサイズをテストします
Community／Experience Cloud へのデプロイ	OmniScript コンポーネントが Experience Builder で使用可能であることを確認します。ゲストユーザーの権限を確認します
保存と再開（後で続行）	saveNameTemplate と saveExpireInDays を設定します。一部のデータを入力した状態で再開できることをテストします
バージョンの競合	新しいバージョンを有効化する前に古いバージョンを無効化します。同じ 3 要素の組み合わせで 2 つのバージョンを同時に有効にしないでください
OmniScript 内のカスタム Lightning Web Components	LWC を OmniScript 対応として登録します。omniscript-lwc の名前空間規則に従います

デバッグ：OmniScript がレンダリングされない → 有効化ステータスと要素階層を確認 | データが事前入力されない → DataRaptor Extract の出力マッピングと JSON パスを確認 | IP アクションが失敗する → まず IP を個別に確認し、入力マップを検証 | ステップが表示されない → 条件付き表示の式を確認

---

メモ

依存関係（必須）：sf-industry-commoncore-datamapper、sf-industry-commoncore-integration-procedure | 依存関係（任意）：sf-deploy、sf-industry-commoncore-flexcard、sf-industry-commoncore-omnistudio-analyze | API：66.0 | モード：Strict（警告があるとブロック） | スコアリング：スコアが 67 未満の場合はデプロイをブロック | 参考ドキュメント：要素の種類とベストプラクティスについては references/ を参照してください

OmniScript のプログラムによる作成：REST API（sf api request rest --method POST --body @file.json）を使用します。必須フィールド：Name、Type、SubType、Language、VersionNumber。OmniScript の IsIntegrationProcedure はデフォルトで false です（OmniProcessType は自動計算されるため、設定しないでください）。sf data create record --values フラグでは、PropertySetConfig のような JSON テキストエリアフィールドを処理できません。各 Step と要素に対応する子の OmniProcessElement レコードを REST API で作成します。

---

ライセンス

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