sf-industry-commoncore-integration-procedure

sf-industry-commoncore-integration-procedure：OmniStudio Integration Procedure の作成と検証

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

クイックリファレンス

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

---

主な責務

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

---

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

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-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 つだけです。

Core 名前空間の識別子：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 コマンドを参照）、再利用可能な DataRaptors/Data Mappers を特定し、sf-industry-commoncore-omnistudio-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、存在しない DataRaptors/Apex クラスへの参照
• 警告：LIMIT のない上限なしの抽出、読み取り専用 IP でのキャッシュの欠落、PropertySetConfig 内のハードコードされた ID、未使用の要素、要素の説明の欠落

検証レポートの形式（6 カテゴリ評価、0～110）：

Score: 95/110  Very Good
|- Design & Structure: 18/20 (90%)
|- Data Operations: 23/25 (92%)
|- Error Handling: 18/20 (90%)
|- Performance: 18/20 (90%)
|- Security: 13/15 (87%)
|- Documentation: 5/10 (50%)

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

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

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

フェーズ 4：デプロイ

1. sf-deploy を使用して、前提となる DataRaptors/Data Mappers を先にデプロイします
2. Integration Procedure をデプロイします：sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org>
3. 対象 org で 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	すべての Extract に妥当な LIMIT 値が設定されている
キャッシュの適用	5	適切な場合、読み取り専用のプロシージャでプラットフォームキャッシュを使用している
並列実行	5	独立した要素を不必要に直列化していない
重複した呼び出しがない	5	同じデータを複数の要素で繰り返し取得していない

セキュリティ（15 点）

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

ドキュメント（10 点）

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

---

CLI コマンド

# Query active Integration Procedures
sf data query -q "SELECT Id,Name,Type,SubType,IsActive FROM OmniProcess WHERE IsActive=true AND IsIntegrationProcedure=true" -o <org>

# Query all Integration Procedures (including inactive)
sf data query -q "SELECT Id,Name,Type,SubType,IsActive,LastModifiedDate FROM OmniProcess WHERE IsIntegrationProcedure=true ORDER BY LastModifiedDate DESC" -o <org>

# Retrieve an Integration Procedure
sf project retrieve start -m OmniIntegrationProcedure:<Name> -o <org>

# Deploy an Integration Procedure
sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org>

# Deploy with dry-run validation first
sf project deploy start -m OmniIntegrationProcedure:<Name> -o <org> --dry-run

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

---

スキル間の連携

From Skill	To sf-industry-commoncore-integration-procedure	When
sf-industry-commoncore-omnistudio-analyze	-> sf-industry-commoncore-integration-procedure	「IP の構築前に依存関係を分析する」
sf-industry-commoncore-datamapper	-> sf-industry-commoncore-integration-procedure	「DataRaptor／Data Mapper の準備ができたので、IP に組み込む」
sf-apex	-> sf-industry-commoncore-integration-procedure	「Apex Remote Action クラスをデプロイしたので、IP で設定する」

From sf-industry-commoncore-integration-procedure	To Skill	When
sf-industry-commoncore-integration-procedure	-> sf-deploy	「IP をターゲット組織にデプロイする」
sf-industry-commoncore-integration-procedure	-> sf-industry-commoncore-omniscript	「IP が有効になったので、それを呼び出す OmniScript を構築する」
sf-industry-commoncore-integration-procedure	-> sf-industry-commoncore-flexcard	「IP が有効になったので、FlexCard のデータソースを構築する」
sf-industry-commoncore-integration-procedure	-> sf-industry-commoncore-omnistudio-analyze	「デプロイ前に IP の依存関係グラフを検証する」

---

エッジケース

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

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

---

注記

依存関係（任意）：sf-deploy、sf-industry-commoncore-datamapper、sf-industry-commoncore-omnistudio-analyze | API：66.0 | モード：厳格（警告がある場合はブロック） | スコアリング：スコアが 67 未満の場合はデプロイをブロック | 詳細なガイダンスについては、references/best-practices.md と references/element-types.md を参照してください。

プログラムによる 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 に設定して有効化します。

---

ライセンス

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