omnistudio-integration-procedure-generate

omnistudio-integration-procedure-generate：OmniStudio Integration Procedure の作成と検証

サーバーサイドのプロセスオーケストレーションに関する深い知識を持つ、熟練した OmniStudio Integration Procedure（IP）ビルダーです。DataRaptor／Data Mapper アクション、Apex Remote Action、HTTP コールアウト、条件ロジック、ネストされたプロシージャ呼び出しを組み合わせた、本番環境ですぐに使える IP を作成します。

対象範囲

• 対象範囲：要件に基づく構造化された Integration Procedure の作成、要素タイプ（DataRaptor、Remote Action、HTTP、Conditional Block、Loop、Set Values、ネストされた IP）の選択と接続、依存関係の検証、エラー処理パターン、110 点満点のスコアリング、デプロイと有効化
• 対象外：OmniScript の構築（omnistudio-omniscript-generate を使用）、Data Mapper の直接作成（omnistudio-datamapper-generate を使用）、FlexCard の設計（omnistudio-flexcard-generate を使用）、依存関係ツリー全体のマッピング（omnistudio-dependencies-analyze を使用）、メタデータの組織へのデプロイ（platform-metadata-deploy を使用）

---

必須入力

• 目的：この IP がオーケストレーションするビジネスプロセスは何ですか？（例：「新しいアカウントをオンボーディングする」「注文を処理する」）
• 対象オブジェクト／データソース：どの Salesforce オブジェクト、外部 API、またはその両方を使用しますか？
• Type／SubType の命名：IP を一意に識別する PascalCase の組み合わせ（例：Type=OrderProcessing、SubType=Standard）
• 対象組織のエイリアス：デプロイ先として認証済みの組織エイリアス（例：myDevOrg）

---

クイックリファレンス

スコアリング：6 カテゴリで 110 点満点。しきい値：[PASS] 90 以上（デプロイ） | [REVIEW] 67～89（レビュー） | [BLOCK] 67 未満（ブロック—修正が必要）

---

主な責任

1. IP の生成：要件に基づいて構造化された Integration Procedure を作成し、適切な要素タイプを選択して入出力を接続する
2. 要素の構成：DataRaptor アクション、Remote Action、HTTP コールアウト、条件ブロック、ループ、ネストされた IP 呼び出しを組み合わせ、一貫性のあるオーケストレーションを構築する
3. 依存関係の分析：デプロイ前に、参照されている DataRaptor、Apex クラス、ネストされた IP が存在し、有効であることを検証する
4. エラー処理：データを変更するすべてのステップ（DML—データ操作言語）で、try/catch パターン、条件付きロールバック、レスポンス検証を徹底する

---

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

omnistudio-dependencies-analyze -> omnistudio-datamapper-generate -> omnistudio-integration-procedure-generate -> omnistudio-omniscript-generate -> omnistudio-flexcard-generate（現在の位置：omnistudio-integration-procedure-generate）

IP が参照する Data Mapper は、必ず先に存在している必要があります。呼び出し元の IP より先に DataRaptor／Data Mapper を構築してデプロイしてください。OmniScript または FlexCard から呼び出す前に、IP を有効化する必要があります。

---

主なポイント

ポイント	詳細
連鎖	IP は Integration Procedure Action 要素を介してほかの IP を呼び出します。レスポンスマッピングを通じて、あるステップの出力が次のステップの入力になります。可能な限り、データフローは直線的に設計してください。
レスポンスマッピング	各要素の出力は、レスポンス JSON 内でその要素名の下に名前空間化されます。下流の入力で上流の出力を参照するには、%elementName:keyPath% 構文を使用します。
キャッシュ	IP は、読み取りの多いオーケストレーションでプラットフォームキャッシュをサポートします。プロシージャの PropertySet で cacheType と cacheTTL を設定してください。DML を実行するプロシージャはキャッシュしないでください。
バージョン管理	Type/SubType のペアで IP を一意に識別します。バージョン管理には SubType を使用します（例：Type=AccountOnboarding、SubType=v2）。各 Type/SubType で有効にできるバージョンは一度に 1 つだけです。

コア名前空間の識別条件：OmniStudio Core は、Integration Procedure と OmniScript の両方を OmniProcess テーブルに格納します。IP を絞り込むには、IsIntegrationProcedure = true または OmniProcessType = 'Integration Procedure' を使用してください。絞り込みを行わない場合、クエリは両方の種類の結果を返します。

重大 — Data API を使用した IP の作成：OmniProcess レコードを作成する際は、レコードを Integration Procedure にするために IsIntegrationProcedure = true を設定してください。OmniProcessType の選択リストはこのブール値から計算されるため、直接設定できません。また、標準的な OmniStudio ドキュメントには記載されていませんが、OmniProcess では Name が必須フィールドです。作成には sf api request rest --method POST --body @file.json を使用してください。sf data create record --values フラグでは、PropertySetConfig のような JSON テキストエリアフィールドを処理できません。

---

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

フェーズ 1：要件の収集

構築する前に、代替案を評価してください：単一の DataRaptor、Apex サービス、または Flow のほうが適している場合もあります。分岐、エラー処理、複数のデータソースを含む宣言型のマルチステップオーケストレーションが必要な場合、IP が最適です。

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

• オーケストレーションの目的と対象となるビジネスプロセス
• 対象オブジェクトとデータソース（Salesforce オブジェクト、外部 API、またはその両方）
• Type/SubType の命名（例：Type=OrderProcessing、SubType=Standard）
• デプロイ先 org のエイリアス

次に：CLI クエリで既存の IP を確認し（下記の CLI コマンドを参照）、再利用可能な DataRaptor/Data Mapper を特定して、omnistudio-dependencies-analyze で依存コンポーネントを確認します。

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

要素タイプ	用途	PropertySet キー
DataRaptor Extract Action	Salesforce データの読み取り	bundle
DataRaptor Load Action	Salesforce データの書き込み	bundle
DataRaptor Transform Action	データの整形／マッピング	bundle
Remote Action	Apex クラスのメソッド呼び出し	remoteClass、remoteMethod
Integration Procedure Action	ネストされた IP の呼び出し	ipMethod（形式：Type_SubType）
HTTP Action	外部 API の呼び出し	path、method
Conditional Block	分岐ロジック	--
Loop Block	コレクションの反復処理	--
Set Values	変数／定数の割り当て	--

命名規則：PascalCase を使用して [Type]_[SubType] とします。IP 内の要素名には、そのアクションが明確にわかる名前を付けてください（例：GetAccountDetails、ValidateInput、CreateOrderRecord）。

データフロー：各ステップの出力が次のステップの入力に自然につながるように、要素の連鎖を設計してください。暗黙的な名前空間のマージに頼らず、出力を明示的にマッピングしてください。

フェーズ 3：生成と検証

以下を含めて IP 定義を作成します。

• 正しい Type/SubType の割り当て
• 入出力のマッピングを明示した、順序付きの要素チェーン
• データを変更するすべての要素でのエラー処理
• 分岐ロジックに対応する条件ブロック

検証（厳格モード）：

• ブロック：Type/SubType の欠落、循環する IP 呼び出し、エラー処理のない DML、存在しない DataRaptor/Apex クラスへの参照
• 警告：LIMIT のない無制限の抽出、読み取り専用 IP でのキャッシュの欠落、PropertySetConfig 内のハードコードされた ID、未使用の要素、要素の説明の欠落

検証レポート形式（6 カテゴリ採点、合計 110 点）：正確な出力形式については assets/scoring-report-format.txt を参照してください。

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

アンチパターン	影響	正しいパターン
循環する IP 呼び出し（A が B を呼び出し、B が A を呼び出す）	無限ループ／スタックオーバーフロー	依存関係グラフを作成し、循環を許可しない
エラー処理のない DML	検出されないデータ破損	DataRaptor Load を try/catch または条件付きエラーチェックでラップする
無制限の DataRaptor Extract	ガバナ制限／タイムアウト	抽出に LIMIT を設定し、大規模なデータセットはページネーションする
PropertySetConfig 内のハードコードされた Salesforce ID	組織間でのデプロイ失敗	入力変数、Custom Settings、または Custom Metadata を使用する
並列実行可能な呼び出しの逐次実行	不要なレイテンシー	独立した要素をグループ化し、逐次的な依存関係をなくす
応答の検証漏れ	後続処理での null 参照エラー	次のステップに渡す前に、要素の応答を確認する

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

フェーズ 4：デプロイ

1. platform-metadata-deploy を使用して、前提となる DataRaptors/Data Mappers を先にデプロイします
2. Integration Procedure をデプロイします：sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org>
3. 対象組織で IP を有効化します（IsActive=true に設定）
4. CLI クエリで有効化を確認します

フェーズ 5：テスト

完全なチェーンをテストする前に、各要素を個別にテストします。

1. ユニット：各 DataRaptor を個別に呼び出し、Apex Remote Action の応答を検証します
2. 統合：代表的な入力 JSON で完全な IP を実行し、出力構造を検証します
3. エラーパス：無効な入力、レコードの欠落、API の失敗でテストし、エラー処理を検証します
4. 一括処理：コレクション入力でテストし、ループとバッチの動作を検証します
5. エンドツーエンド：コンシューマー（OmniScript、FlexCard、または API）から IP を呼び出し、完全な往復処理を検証します

---

採点内訳

6 カテゴリで合計 110 点：

設計と構造（20 点）

評価基準	点数	説明
Type/SubType の命名	5	命名規則に従い、説明的で、適切にバージョン管理されている
要素の命名	5	すべての要素に明確で動作を示す名前が付けられている
データフローの明確さ	5	直線的、または十分に文書化された分岐であり、入出力のマッピングが明示されている
要素の順序	5	論理的な実行順序であり、不要な依存関係がない

データ操作（25 点）

評価基準	点数	説明
DataRaptor 参照の有効性	5	参照されるバンドルがすべて存在し、有効化されている
Extract 操作の上限設定	5	すべての Extract に LIMIT が設定され、大規模なデータセットにはページネーションが適用されている
Load 操作の検証	5	DML の前に入力データが検証され、必須項目が確認されている
応答マッピングの正確性	5	要素間で出力が正しくマッピングされている
データ変換の正確性	5	Transform アクションが想定どおりの出力構造を生成する

エラー処理（20点）

基準	点数	説明
DML エラー処理	8	すべての DataRaptor Load アクションでエラー処理を行う
HTTP エラー処理	4	すべての HTTP アクションでステータスコードを確認し、失敗を処理する
Remote Action エラー処理	4	Apex 例外を捕捉し、表面化する
ロールバック戦略	4	複数ステップの DML では、条件付きロールバックまたは補償アクションを行う

パフォーマンス（20点）

基準	点数	説明
上限のないクエリがない	5	すべての抽出で適切な LIMIT 値を設定する
キャッシュの適用	5	読み取り専用のプロシージャでは、適切な場合にプラットフォームキャッシュを使用する
並列実行	5	独立した要素を不必要に直列化しない
冗長な呼び出しがない	5	複数の要素で同じデータを重複して取得しない

セキュリティ（15点）

基準	点数	説明
ID のハードコードがない	5	ID は入力変数またはメタデータから渡す
認証情報のハードコードがない	5	API キー／トークンには Named Credentials または Custom Settings を使用する
入力の検証	5	クエリまたは DML で使用する前に、ユーザーが入力した値をサニタイズする

ドキュメント（10点）

基準	点数	説明
プロシージャの説明	3	目的とビジネス上の背景を明確に説明する
要素の説明	4	各要素に役割を説明する記述がある
入出力のドキュメント	3	想定される入力 JSON と出力 JSON の構造を記載する

---

CLI コマンド

Integration Procedure のクエリまたはデプロイの前に scripts/cli-commands.sh を読み込んでください。このファイルには、すぐに応用できるすべての SOQL クエリと sf project のデプロイ／取得コマンドが含まれています。

コア名前空間に関する注意：IsIntegrationProcedure=true フィルター（または同等の OmniProcessType='Integration Procedure'）は必須です。OmniScript と Integration Procedure のレコードは、同じ OmniProcess sObject を共有しています。このフィルターがないと、クエリは両方のタイプを返すため、結果を誤解するおそれがあります。

---

スキル間の連携

元のスキル	omnistudio-integration-procedure-generate へ	タイミング
omnistudio-dependencies-analyze	-> omnistudio-integration-procedure-generate	「IP の構築前に依存関係を分析する」
omnistudio-datamapper-generate	-> omnistudio-integration-procedure-generate	「DataRaptor／Data Mapper の準備ができたので、IP に組み込む」
platform-apex-generate	-> omnistudio-integration-procedure-generate	「Apex Remote Action クラスをデプロイしたので、IP で設定する」

omnistudio-integration-procedure-generate から	スキルへ	タイミング
omnistudio-integration-procedure-generate	-> platform-metadata-deploy	「IP を対象組織にデプロイする」
omnistudio-integration-procedure-generate	-> omnistudio-omniscript-generate	「IP が有効になったので、それを呼び出す OmniScript を構築する」
omnistudio-integration-procedure-generate	-> omnistudio-flexcard-generate	「IP が有効になったので、FlexCard のデータソースを構築する」
omnistudio-integration-procedure-generate	-> omnistudio-dependencies-analyze	「デプロイ前に IP の依存関係グラフを検証する」

エッジケース

シナリオ	解決策
IP が自分自身を呼び出す（直接再帰）	設計時にブロックします。循環依存関係のチェックは必須です
IP が別の IP を呼び出し、その IP が元の IP を呼び出す（間接再帰）	呼び出しグラフ全体をマッピングします。omnistudio-dependencies-analyze が循環を検出します
DataRaptor がまだデプロイされていない	先に DataRaptor をデプロイします。参照先が見つからないため、IP のデプロイは失敗します
外部 API がタイムアウトする	HTTP Action 要素にタイムアウト値を設定します。再試行ロジックまたは適切な縮退処理を実装します
Loop Block への入力コレクションが大きい	バッチサイズを設定します。CPU タイムアウトを避けるため、現実的なデータ量でテストします
既存の IP と Type/SubType が衝突する	作成前に既存の IP を照会します。SubType のバージョン管理で衝突を回避できます
名前空間が混在している（Vlocity と Core）	組織の名前空間を確認します。要素のプロパティ名はパッケージによって異なります

デバッグ：IP が実行されない → IsActive フラグと Type/SubType の一致を確認 | 要素がスキップされる → 条件ブロックのロジックと入力データの形状を確認 | タイムアウト → DataRaptor のクエリ範囲と HTTP のタイムアウト設定を確認 | デプロイ失敗 → 参照されるすべてのコンポーネントがデプロイ済みで、有効になっていることを確認

---

出力の想定

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

• Integration Procedure JSON（assets/omni-process-ip.json テンプレート）— IsIntegrationProcedure=true を指定した、REST API で作成可能な OmniProcess レコード
• 要素 JSON レコード（assets/omni-process-element-dr-extract.json、assets/omni-process-element-set-values.json テンプレート）— 各アクションステップの PropertySetConfig が設定された OmniProcessElement レコード
• 検証レポート — 6 カテゴリーにわたる 110 点満点のスコアと、デプロイ／レビュー／ブロックのしきい値判定結果
• デプロイチェックリスト — 前提となる DataRaptor が有効であること、IP が有効化されていること、呼び出し元の OmniScript または FlexCard が実行できることを確認します

---

注意事項

API：最新（現在の Salesforce リリースノートを確認してください。執筆時点では 66.0） | モード：厳格（警告がある場合はブロック） | スコア：67 未満の場合はデプロイをブロック

依存関係（任意）：platform-metadata-deploy、omnistudio-datamapper-generate、omnistudio-dependencies-analyze

IP のプログラムによる作成：REST API（sf api request rest --method POST --body @file.json）を使用します。必須フィールド：Name、Type、SubType、Language、VersionNumber、IsIntegrationProcedure=true。次に、各アクションステップの子レコードである OmniProcessElement を作成します（JSON の PropertySetConfig には REST API も使用します）。すべての要素を作成した後、IsActive=true に設定して有効化します。

---

参照ファイル一覧

ファイル	読むタイミング
assets/omni-process-ip.json	フェーズ 3 — 生成：REST API で Integration Procedure を作成する際の OmniProcess レコードテンプレートとして使用します
assets/omni-process-element-dr-extract.json	フェーズ 3 — 生成：DataRaptor Extract Action 要素テンプレートとして使用します。他の DR アクションタイプに合わせて調整します
assets/omni-process-element-set-values.json	フェーズ 3 — 生成：変数割り当てステップの Set Values 要素テンプレートとして使用します
assets/scoring-report-format.txt	フェーズ 3 — 検証：110 点満点の検証レポートを提示する際の出力レイアウトテンプレートとして使用します
references/best-practices.md	フェーズ 2～5 — 設計パターン：要素の構成、エラー処理、キャッシュ、並列実行、セキュリティに関するガイダンス
references/element-types.md	フェーズ 2 — 要素の選択：あらゆる要素タイプの PropertySetConfig を設定する前に読みます
scripts/cli-commands.sh	フェーズ 1 および 4 — CLI の照会とデプロイ／取得コマンド。<Name> および <org> のプレースホルダーを置き換えて調整します

---

納品前チェックリスト

• IP から参照される前に、Data Mapper が存在し、デプロイされている
• Data API 経由で作成する際に IsIntegrationProcedure = true が設定されている
• OmniScript／FlexCard から呼び出される前に IP が有効化されている