building-omnistudio-integration-procedure

building-omnistudio-integration-procedure：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 の作成（building-omnistudio-omniscript を使用）、Data Mapper の直接作成（building-omnistudio-datamapper を使用）、FlexCard の設計（building-omnistudio-flexcard を使用）、依存関係ツリー全体のマッピング（analyzing-omnistudio-dependencies を使用）、組織へのメタデータのデプロイ（deploying-metadata を使用）

---

必須入力

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

---

クイックリファレンス

採点：6 カテゴリで 110 点満点。基準：✅ 90 点以上（デプロイ）｜⚠️ 67～89 点（レビュー）｜❌ 67 点未満（ブロック — 修正が必要）

---

主な責務

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

---

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

analyzing-omnistudio-dependencies -> building-omnistudio-datamapper -> building-omnistudio-integration-procedure -> building-omnistudio-omniscript -> building-omnistudio-flexcard（現在の手順：building-omnistudio-integration-procedure）

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 の選択リストはこのブール値から計算されるため、直接設定できません。また、Name は OmniProcess の必須フィールドです（標準の OmniStudio ドキュメントには記載されていません）。作成には 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 を特定して、analyzing-omnistudio-dependencies で依存コンポーネントを確認します。

フェーズ 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 カテゴリのスコアリング、0～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. deploying-metadata を使用して、前提となる DataRaptor／Data Mapper を先にデプロイします
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	参照されているすべてのバンドルが存在し、有効になっている
抽出処理の制限	5	すべての抽出に LIMIT が設定され、大規模なデータセットではページネーションが使用されている
Load 処理の検証	5	DML の前に入力データが検証され、必須項目が確認されている
レスポンスマッピングの正確さ	5	要素間で出力が正しくマッピングされている
データ変換の正確さ	5	変換アクションが期待される出力構造を生成している

エラー処理（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 を共有しています。このフィルターを使わないと、クエリは両方のタイプを返し、誤解を招く結果になります。

---

スキル間の連携

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

元のスキル	連携先のスキル	タイミング
building-omnistudio-integration-procedure	-> deploying-metadata	「IP をターゲット組織にデプロイする」
building-omnistudio-integration-procedure	-> building-omnistudio-omniscript	「IP が有効になったので、それを呼び出す OmniScript を構築する」
building-omnistudio-integration-procedure	-> building-omnistudio-flexcard	「IP が有効になったので、FlexCard データソースを構築する」
building-omnistudio-integration-procedure	-> analyzing-omnistudio-dependencies	「デプロイ前に IP の依存関係グラフを検証する」

---

エッジケース

シナリオ	解決策
IP が自身を呼び出す（直接再帰）	設計時にブロックします。循環依存のチェックは必須です
IP が元の IP を呼び出す別の IP を呼び出す（間接再帰）	呼び出しグラフ全体をマッピングします。analyzing-omnistudio-dependencies が循環を検出します
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 テンプレート）— REST API で作成可能な IsIntegrationProcedure=true の OmniProcess レコード
• Element 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 未満の場合はデプロイをブロックします

依存関係（任意）：deploying-metadata、building-omnistudio-datamapper、analyzing-omnistudio-dependencies

プログラムによる 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> のプレースホルダーを置き換えて使用します