building-omnistudio-omniscript

building-omnistudio-omniscript：OmniStudio OmniScript の作成と検証

宣言型のステップベースのガイド付きデジタルエクスペリエンスを構築する、OmniStudio OmniScript のエキスパートビルダーです。OmniScript は Screen Flow に相当する OmniStudio の機能です。入力を収集し、サーバー側のロジック（Integration Procedure、DataRaptor）を実行して、ユーザーに結果を提示する複数ステップのインタラクティブなプロセスを、コードを使わずに構築できます。

クイックリファレンス

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

---

対象範囲

• 対象：要件に基づく OmniScript の作成、要素の選択と PropertySetConfig の設計、依存関係の分析（Integration Procedure、DataRaptor）、データフローの追跡、120 点満点の検証スコアリング、デプロイと有効化
• 対象外：FlexCard の構築（building-omnistudio-flexcard を使用）、Integration Procedure の直接作成（building-omnistudio-integration-procedure を使用）、完全な依存関係ツリーのマッピング（analyzing-omnistudio-dependencies を使用）、メタデータの org へのデプロイ（deploying-metadata を使用）

---

必須入力

構築前に、次の情報を収集してください。

入力	説明	デフォルト
Type	プロセスのカテゴリ（例：ServiceRequest、Enrollment）	なし — 必須
SubType	具体的なバリエーション（例：NewCase、UpdateAddress）	なし — 必須
Language	OmniScript のロケール	English
Purpose	この OmniScript がガイドするビジネスプロセス	なし — 必須
ターゲット org	デプロイ先の org エイリアス	現在のデフォルト org
データソース	クエリまたは更新するオブジェクト／API	要件から特定

---

主な責務

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

---

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

analyzing-omnistudio-dependencies → building-omnistudio-datamapper → building-omnistudio-integration-procedure → building-omnistudio-omniscript → building-omnistudio-flexcard（現在の項目：building-omnistudio-omniscript）

OmniScript は Integration Procedure と DataRaptor を使用します。これらを先に構築してください。FlexCard から OmniScript を起動できるため、FlexCard は後で構築します。開始前に analyzing-omnistudio-dependencies を使用して、依存関係ツリー全体をマッピングしてください。

---

主なポイント

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

---

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

フェーズ 1：要件の収集

構築する前に、代替案を評価します：OmniScripts は、複雑で複数のステップからなるガイド付きプロセスに最適です。シンプルな単一画面でのデータ入力には、Screen Flows を検討してください。インタラクションを伴わないデータ表示には、FlexCards を検討してください。

ユーザーに質問して、以下の情報を収集します：

• Type：プロセスのカテゴリ（例：ServiceRequest、Enrollment、ClaimSubmission）
• SubType：具体的なバリエーション（例：NewCase、UpdateAddress、FileAppeal）
• Language：通常は English。複数言語のサポートが必要な場合を除きます
• Purpose：この OmniScript でユーザーを案内するビジネスプロセス
• Target org：デプロイ先の Org エイリアス
• Data sources：照会または更新が必要なオブジェクト／API

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

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

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

コンテナー要素

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

入力要素

要素タイプ	目的	主な設定
Text	1 行のテキスト入力	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 アクション	Salesforce からデータを取得	bundle、inputMap、outputMap
DataRaptor Load アクション	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: 生成と検証

scripts/check-duplicate-omniscript.sh <Type> <SubType> <Language> <org> を実行して、重複する Type/SubType/Language が存在しないことを確認します。

OmniScript をビルドする:

1. Type、SubType、Language、および OmniProcessType='OmniScript' を指定して OmniProcess レコードを作成します
2. 各ステップ (Level=0) に対して OmniProcessElement 子レコードを作成します
3. ステップ内の各要素 (Level=1 以上、Order フィールドで並び替え) に対して OmniProcessElement 子レコードを作成します
4. 各要素の PropertySetConfig JSON を設定します
5. アクション要素をそれぞれの Integration Procedure / DataRaptor に接続します

検証 (STRICT モード):

• ブロック: Type/SubType/Language の欠落、循環する OmniScript の埋め込み、壊れた IP/DataRaptor 参照、必須の PropertySetConfig フィールドの欠落
• 警告: 要素のないステップ、検証のない入力要素、アクションのエラー処理の欠落、未使用のデータパス、深くネストされた要素 (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. 前提条件: 組織の認証を確認します (sf org display -o <org>)。参照されているすべての DataRaptor と Integration Procedure がターゲット組織で有効であることを確認します。
2. まずすべての依存関係をデプロイします: DataRaptor、Integration Procedure、参照されている OmniScript。
3. scripts/deploy-omniscript.sh <Name> <Type> <SubType> <org> を実行します — これにより OmniScript がデプロイされ、有効化が確認されます。デプロイが失敗した場合、スクリプトは復旧手順 (部分的なレコードを無効化して削除し、再試行する) を出力します。
4. デプロイの成功後、自動有効化されていない場合は OmniScript のバージョンを有効化します。

フェーズ 5: テスト

さまざまなデータシナリオで全パスをたどります:

• ハッピーパス: 有効なデータで全ステップを完了し、送信を確認します
• 検証テスト: 各入力で無効なデータを送信し、エラーメッセージを確認します
• 条件テスト: すべての条件ブロックを実行し、表示/非表示ロジックを確認します
• データプリフィル: DataRaptor Extract アクションが要素を正しく設定することを確認します
• 後で保存: 有効になっている場合、再開機能をテストします
• ナビゲーション: 全ステップにわたって戻る/進む/キャンセルの動作をテストします
• エラーシナリオ: IP/DataRaptor の失敗をシミュレートし、エラー処理を確認します
• 埋め込み OmniScript: 親と子の OmniScript 間のデータ受け渡しをテストします
• 大量データ: ループブロックと Type Ahead 要素で大規模なデータセットを使用してテストします

---

ルール／制約

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

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

---

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

設計と構造（25 点）

チェック項目	点数	基準
Type／SubType／Language が正しく設定されている	5	3 つすべての項目に適切な値が設定されている
Step の構成	5	論理的にグループ化され、1 つの Step あたりの要素数が最大 7～10 個
要素の命名	5	PascalCase の命名規則に従った説明的な名前
条件付きロジック	5	Conditional Block と 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 の読み込み時ではなく、Step に入ったときに実行される
Step ごとの要素数が適切	5	要素数が 15 個を超える Step がない
条件付きレンダリングを使用している	5	該当しない要素は非表示になっている（単に見えない状態ではない）

ユーザーエクスペリエンス（20 点）

チェック項目	点数	基準
Step の流れが論理的	5	Step が自然なタスクの進行順に並んでいる
入力ラベルとヘルプテキスト	5	すべての入力に分かりやすいラベルと、状況に応じたヘルプがある
ナビゲーションコントロール	5	戻る、次へ、キャンセル、後で保存が適切に設定されている
レスポンシブレイアウト	5	要素がモバイルとデスクトップのブレークポイント向けに設定されている

セキュリティ（15 点）

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

---

CLI コマンド

すべてのコマンドリファレンスについては、scripts/cli-reference.sh を参照してください。よく使うコマンド：

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

# Query elements for a specific OmniScript
sf data query -q "SELECT Id,Name,ElementType,Level,Order FROM OmniProcessElement WHERE OmniProcessId='<id>' ORDER BY Level,Order LIMIT 200" -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 LIMIT 10" -o <org>

---

スキル間の連携

From Skill	To building-omnistudio-omniscript	When
analyzing-omnistudio-dependencies	-> building-omnistudio-omniscript	「OmniScript を構築する前に依存関係を分析する」
building-omnistudio-datamapper	-> building-omnistudio-omniscript	「DataRaptor の準備ができたので、それを使用する OmniScript を構築する」
building-omnistudio-integration-procedure	-> building-omnistudio-omniscript	「IP の準備ができたので、OmniScript のアクションに組み込む」

From building-omnistudio-omniscript	To Skill	When
building-omnistudio-omniscript	-> building-omnistudio-flexcard	「この OmniScript を起動する FlexCard を構築する」
building-omnistudio-omniscript	-> deploying-metadata	「OmniScript をターゲット組織にデプロイする」
building-omnistudio-omniscript	-> analyzing-omnistudio-dependencies	「デプロイ前に依存関係ツリー全体をマッピングする」
building-omnistudio-omniscript	-> building-omnistudio-integration-procedure	「この OmniScript アクション用の新しい IP が必要」
building-omnistudio-omniscript	-> building-omnistudio-datamapper	「データの事前入力用の DataRaptor が必要」

---

注意点

Issue	Resolution
多言語 OmniScript	Language ごとに個別のバージョンを作成し、Type／SubType は共通にします。ラベルには翻訳ワークベンチを使用します
埋め込み OmniScript のデータ受け渡し	親データの JSON キーを prefillJSON 経由で子 OmniScript の入力にマッピングします。データの往復をテストします
大規模な Loop Block データセット	DataRaptor の結果をページ分割するか、件数を制限します。Integration Procedure（IP）でのサーバー側フィルタリングを検討します
FlexCard のフライアウト内の OmniScript	FlexCard が必要なコンテキストデータを渡すことを確認し、フライアウトのサイズをテストします
Community／Experience Cloud へのデプロイ	OmniScript コンポーネントが Experience Builder で使用可能であることを確認します。ゲストユーザーの権限も確認します
保存と再開（後で保存）	saveNameTemplate、saveExpireInDays を設定し、部分的なデータで再開できることをテストします
バージョンの競合	新しいバージョンを有効化する前に古いバージョンを無効化します。同じ Type／SubType／Language の組み合わせで、2 つのバージョンを同時に有効化しないでください
OmniScript 内のカスタム LWC	LWC を OmniScript 互換として登録し、omniscript-lwc の名前空間規則に従います
名前空間付き組織	マネージド OmniStudio パッケージの組織にデプロイする場合は、適切な名前空間（例：omnistudio__）をバンドル名と API 名の前に付けます
作成時に OmniProcessType を設定できない	OmniProcessType は IsIntegrationProcedure から計算されます（OmniScript の場合は false）。直接設定しないでください

一般的なランタイムのトラブルシューティング（要素がレンダリングされない、データが事前入力されない、IP アクションがエラーを出さずに失敗する）については、references/best-practices.md のセクション 8 を参照してください。

---

メモ

API：66.0 | モード：Strict（警告があるとブロック） | スコアリング：スコアが 67 未満の場合はデプロイをブロック

必須の上流スキル：building-omnistudio-datamapper、building-omnistudio-integration-procedure

任意のスキル：deploying-metadata、building-omnistudio-flexcard、analyzing-omnistudio-dependencies

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 で作成します。

---

出力内容

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

• OmniScript JSON（assets/omni-process-omniscript.json テンプレート）— REST API で作成できる状態の OmniProcess レコード
• Step 要素 JSON（assets/omni-process-element-step.json テンプレート）— 各 Step（Level=0）用の OmniProcessElement レコード
• 要素 JSON（assets/omni-process-element-text-block.json など）— 子要素（Level=1+）用の OmniProcessElement レコード
• 検証レポート — 6 カテゴリにわたる120点満点のスコアと、合格／警告／ブロックの判定結果

---

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

ファイル	読み込むタイミング
references/element-types.md	フェーズ 2 — 要素の選択：任意の要素タイプの PropertySetConfig を設定する前に読み込みます
references/best-practices.md	フェーズ 2～5 — 設計パターン：Step の設計、データの事前入力、検証、ナビゲーション、パフォーマンス、トラブルシューティングのガイダンスを確認します
assets/omni-process-omniscript.json	フェーズ 3 — 生成：REST API を使用して OmniScript を構築する際の OmniProcess レコードテンプレートとして使用します
assets/omni-process-element-step.json	フェーズ 3 — 生成：Step（Level=0）用の OmniProcessElement レコードテンプレートとして使用します
assets/omni-process-element-text-block.json	フェーズ 3 — 生成：Text Block 要素テンプレートとして使用します。他の表示要素タイプに合わせて調整します
scripts/check-duplicate-omniscript.sh	フェーズ 3 — 新しい OmniScript を作成する前に実行し、Type/SubType/Language の組み合わせが重複していないことを確認します
scripts/deploy-omniscript.sh	フェーズ 4 — OmniScript をデプロイし、アクティベーションを検証するために実行します。前提条件の確認とエラー復旧が含まれます
scripts/cli-reference.sh	任意のフェーズ — OmniScript のクエリ、取得、デプロイ、検証に使用する CLI コマンドの完全なリファレンスです