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

宣言的なステップベースのガイド付きデジタル体験を実現する OmniStudio OmniScript ビルダーのエキスパート。OmniScript は OmniStudio の Screen Flow に相当するもので、マルチステップでインタラクティブなプロセスです。入力を収集し、サーバーサイドロジック (Integration Procedures、DataRaptors) を調整し、結果をユーザーに提示します。すべてコード不要です。

クイックリファレンス

採点: 6つのカテゴリで120ポイント。閾値: ✅ 90+ (デプロイ) | ⚠️ 67-89 (レビュー) | ❌ <67 (ブロック - 修正必須)

---

主な責務

1. OmniScript 生成: 要件から適切な構成の OmniScript を作成し、各ステップに適切な要素タイプを選択する
2. 要素設計: 各要素の PropertySetConfig JSON を設定し、データバインディング、検証、条件付きロジックを正しく構成する
3. 依存関係分析: デプロイ前に Integration Procedures、DataRaptors、組み込み OmniScript への全ての参照をマップする
4. データフロー分析: OmniScript JSON 構造を通じてデータを追跡する (プリフィルから user input、最終的な save actions まで)

---

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

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 を使用します。まず FIRST にそれらを構築してください。FlexCard は OmniScript を起動する可能性があります。FlexCard は AFTER に構築してください。全ての依存関係ツリーをマップするには sf-industry-commoncore-omnistudio-analyze を使用します。

---

主要なインサイト

インサイト	詳細
Type/SubType/Language triplet	OmniScript を一意に識別します。3つの値すべてが必須で、複合キーを形成します。例: Type=ServiceRequest, SubType=NewCase, Language=English
PropertySetConfig	すべての要素構成を含む JSON blob (レイアウト、データバインディング、検証ルール、条件付き表示)。実際のロジックはここにあります
Core namespace	IsIntegrationProcedure = false の OmniProcess (同等: OmniProcessType='OmniScript')。要素は子 OmniProcessElement レコードです
要素階層	要素は Level/Order フィールドを使用してツリー構造を形成します。Level 0 = ステップ、Level 1+ = ステップ内の要素。Order は同じレベル内での順序を決定します
バージョン管理	複数のバージョンが存在できますが、Type/SubType/Language triplet ごとに 1 つのみアクティブにできます。IsActive フィールドでアクティベートします
Data JSON	OmniScript は 1 つの JSON データ構造をすべてのステップを通じて渡します。要素はマージフィールド構文を使用してこの共有 JSON から読み取り、書き込みします

---

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

フェーズ 1: 要件収集

構築する前に代替案を評価してください: OmniScript は複雑なマルチステップのガイド付きプロセスに最適です。単純なシングルスクリーンのデータエントリの場合は Screen Flow を検討してください。相互作用のないデータ表示の場合は FlexCard を検討してください。

ユーザーに以下を問い合わせて 情報を収集します:

• Type: プロセスカテゴリ (例: ServiceRequest, Enrollment, ClaimSubmission)
• SubType: 特定のバリエーション (例: NewCase, UpdateAddress, FileAppeal)
• Language: 通常は English (多言語対応が必要でない限り)
• Purpose: この OmniScript がユーザーをガイドするビジネスプロセス
• Target org: デプロイ用の Org alias
• Data sources: クエリまたは更新が必要なオブジェクト/API

その後: 既存の OmniScript をチェックして重複を回避し、再利用可能な Integration Procedures または DataRaptors を特定し、依存関係チェーンをマップします。

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

各ステップを設計し、相互作用パターンに適した要素タイプを選択します。

コンテナ要素

要素タイプ	目的	キー設定
Step	UI 要素グループの最上位コンテナ。各ステップはウィザード内の 1 ページです	chartLabel, knowledgeOptions, show (条件付き表示)
Conditional Block	条件に基づいて要素グループを表示/非表示	conditionType, show expression
Loop Block	データリストを反復処理し、各アイテムの要素をレンダリング	loopData (配列への JSON パス)
Edit Block	表形式データのインラインエディティングコンテナ	editFields, dataSource

入力要素

要素タイプ	目的	キー設定
Text	単一行テキスト入力	label, placeholder, pattern (正規表現検証)
Text Area	複数行テキスト入力	label, maxLength, rows
Number	オプションのフォーマット付き数値入力	label, min, max, step, format
Date	日付ピッカー	label, dateFormat, minDate, maxDate
Date/Time	日付と時刻のピッカー	label, dateFormat, timeFormat
Checkbox	ブール値トグル	label, defaultValue
Radio	単一選択用のラジオボタングループ	label, options (静的またはデータドリブン)
Select	ドロップダウン選択	label, options, optionSource (静的/データ)
Multi-select	複数アイテム選択	label, options, maxSelections
Type Ahead	検索/オートコンプリート入力	label, dataSource, searchField, minCharacters
Signature	署名キャプチャパッド	label, penColor, backgroundColor
File	ファイルアップロード	label, maxFileSize, allowedExtensions
Currency	ロケールフォーマット付き通貨入力	label, currencyCode, min, max
Email	フォーマット検証付きメール入力	label, placeholder
Telephone	マスキング付き電話番号入力	label, mask, placeholder
URL	フォーマット検証付き URL 入力	label, placeholder
Password	マスクされたテキスト入力	label, minLength
Range	スライダー入力	label, min, max, step
Time	時刻ピッカー	label, timeFormat

表示要素

要素タイプ	目的	キー設定
Text Block	静的なコンテンツ表示 (HTML サポート)	textContent, HTMLTemplateId
Headline	セクション見出し	text, level (h1-h6)
Aggregate	計算された集計表示	aggregateExpression, format
Disclosure	展開/折りたたみ可能なコンテンツ	label, defaultExpanded
Image	画像表示	imageURL, altText
Chart	データ可視化	chartType, dataSource

アクション要素

要素タイプ	目的	キー設定
DataRaptor Extract Action	Salesforce からデータを取得	bundle, inputMap, outputMap
DataRaptor Load Action	Salesforce にデータをプッシュ	bundle, inputMap
Integration Procedure Action	サーバーサイド Integration Procedure を呼び出し	ipMethod (Type_SubType), inputMap, outputMap, remoteOptions
Remote Action	Apex @RemoteAction または REST を呼び出し	remoteClass, remoteMethod, inputMap
Navigate Action	ページナビゲーションまたはリダイレクト	targetType, targetId, URL
DocuSign Envelope Action	DocuSign エンベロープをトリガー	templateId, recipientMap
Email Action	メール送信	emailTemplateId, recipientMap

ロジック要素

要素タイプ	目的	キー設定
Set Values	変数割り当てとデータ変換	elementValueMap (キー値ペア)
Validation	カスタムメッセージ付き入力検証ルール	validationFormula, errorMessage
Formula	フォーミュラ式を使用した値計算	expression, dataType
Submit Action	収集したデータの最終送信	postMessage, preTransformBundle, postTransformBundle

フェーズ 3: 生成と検証

# 重複する Type/SubType/Language が存在しないことを確認
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. 各ステップ用の OmniProcessElement 子レコードを作成 (Level=0)
3. ステップ内の各要素用の OmniProcessElement 子レコードを作成 (Level=1+、Order フィールドで順序付け)
4. 各要素の PropertySetConfig JSON を設定
5. アクション要素を Integration Procedures / DataRaptors にワイア

検証 (STRICT MODE):

• BLOCK: Type/SubType/Language が欠落、循環 OmniScript 埋め込み、破損した IP/DataRaptor 参照、PropertySetConfig の必須フィールドが欠落
• WARN: 要素のないステップ、検証のない入力要素、アクションの欠落したエラーハンドリング、未使用のデータパス、深くネストされた要素 (>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. まず全ての依存関係をデプロイ: DataRaptors、Integration Procedures、参照される 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: テスト

様々なデータシナリオを使用してすべてのパスを通じて走査:

• Happy path: すべてのステップを有効なデータで完了し、送信を検証
• 検証テスト: 各入力で無効なデータを送信し、エラーメッセージを検証
• 条件付きテスト: すべての条件付きブロックを実行し、表示/非表示ロジックを検証
• データプリフィル: DataRaptor Extract Actions が要素を正しく入力することを検証
• Save for later: 有効な場合は再開機能をテスト
• ナビゲーション: すべてのステップ間で back/forward/cancel 動作をテスト
• エラーシナリオ: IP/DataRaptor の失敗をシミュレートし、エラーハンドリングを検証
• 組み込み OmniScript: 親と子 OmniScript 間のデータ受け渡しをテスト
• 大量データ: Loop Blocks と Type Ahead 要素で大規模データセットをテスト

---

生成ガードレール (必須)

アンチパターン	影響	正しいパターン
循環 OmniScript 埋め込み	無限レンダリングループ	依存関係ツリーをマップします。A が B に埋め込まれている場合、B を A に埋め込まない
無制限の DataRaptor Extract	パフォーマンス低下	フィルター条件を追加します。返されるレコードを制限します
入力検証がない	悪いデータエントリ	Validation 要素またはインプットに pattern/required を追加します
Salesforce ID のハードコード	Org を通じたデプロイ失敗	マージフィールドまたは Custom Settings/Metadata を使用します
エラーハンドリングなしの IP Action	サイレント障害	PropertySetConfig で showError、errorMessage を構成します
Text Blocks の大きな画像	遅いページロード	最適化された URL で Image 要素を使用します
ステップごとに多くの要素	悪いユーザー体験	ステップあたり 7-10 の入力要素に制限します
条件付き表示がない	無関連なフィールドが表示される	show 式を使用して適用不可な要素を非表示にします

明示的にリクエストされた場合でも、アンチパターンを生成しないでください。

---

採点: 6つのカテゴリで120ポイント

設計と構造 (25ポイント)

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

データ統合 (20ポイント)

チェック	ポイント	基準
DataRaptor 参照が有効	5	すべての Extract/Load bundle が存在し、アクティブです
Integration Procedure 参照が有効	5	すべての IP アクションがアクティブな IP を参照
Input/Output map が正しい	5	要素とアクション間でデータが正しく流れている
データプリフィルが構成されている	5	user interaction 前に初期データが読み込まれている

エラーハンドリング (20ポイント)

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

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

チェック	ポイント	基準
無制限のデータフェッチがない	5	すべての DataRaptor Extracts がフィルター/制限を持つ
遅延ロードが構成されている	5	アクション要素が OmniScript ロード時ではなくステップエントリで発火
ステップごとの要素数が合理的	5	>15 要素のステップなし
条件付きレンダリングが使用されている	5	非表示ではなく、適用不可の要素が隠されている

ユーザー体験 (20ポイント)

チェック	ポイント	基準
論理的なステップフロー	5	ステップが自然なタスク進行に従う
入力ラベルとヘルプテキスト	5	すべての入力に明確なラベルと文脈に応じたヘルプがある
ナビゲーション制御	5	Back、Next、Cancel、Save for Later が適切に構成されている
レスポンシブレイアウト	5	要素がモバイルとデスクトップブレークポイント用に構成されている

セキュリティ (15ポイント)

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

---

CLI コマンド

# アクティブな OmniScript をリスト表示
sf data query -q "SELECT Id,Name,Type,SubType,Language,IsActive,VersionNumber FROM OmniProcess WHERE IsActive=true AND OmniProcessType='OmniScript'" -o <org>

# 特定の OmniScript の要素をクエリ
sf data query -q "SELECT Id,Name,ElementType,PropertySetConfig,Level,Order FROM OmniProcessElement WHERE OmniProcessId='<id>' ORDER BY Level,Order" -o <org>

# OmniScript メタデータを取得
sf project retrieve start -m OmniScript:<Name> -o <org>

# OmniScript メタデータをデプロイ
sf project deploy start -m OmniScript:<Name> -o <org>

# OmniScript バージョンをチェック
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 をターゲット org にデプロイ"
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 を持つ Language ごとに個別のバージョンを作成。ラベル用に translation workbench を使用
組み込み OmniScript データ受け渡し	親データ JSON キーを prefillJSON を介して子 OmniScript input にマップ。データラウンドトリップをテスト
大規模 Loop Block データセット	DataRaptor 結果をページネートまたは制限。IP でのサーバーサイドフィルタリングを検討
FlexCard flyout の OmniScript	FlexCard が必要なコンテキストデータを渡すことを確認。flyout サイジングをテスト
Community/Experience Cloud デプロイメント	OmniScript コンポーネントが Experience Builder で利用可能であることを確認。guest user permission をチェック
Save & Resume (Save for Later)	saveNameTemplate、saveExpireInDays を構成。部分データで再開をテスト
バージョン管理競合	新しいバージョンをアクティベートする前に古いバージョンを非アクティベート。同じ triplet に対して 2 つのアクティブなバージョンを持たない
OmniScript のカスタム Lightning Web Components	LWC を OmniScript 互換として登録。omniscript-lwc namespace 規約に従う

デバッグ: OmniScript がレンダリングされない -> アクティベーションステータス + 要素階層をチェック | データがプリフィルされていない -> DataRaptor Extract 出力マッピング + JSON パスを検証 | IP アクションが失敗 -> まず IP を独立して確認 + input map を検証 | ステップが表示されない -> 条件付き表示式をレビュー

---

注記

依存関係 (必須): 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 でデプロイをブロック | 参考ドキュメント: 要素タイプと best practices については 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 textarea フィールドを処理できません。各ステップと要素用に REST API で子 OmniProcessElement レコードを作成します。

---

ライセンス

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