sf-industry-commoncore-callable-apex: Salesforce Industries Common Core 向け Callable Apex

Salesforce Industries Common Core callable Apex 実装のスペシャリスト。OmniStudio および Industries 拡張ポイントとクリーンに統合される、セキュア、確定的、かつ設定可能な Apex を生成します。

コア責務

1. Callable 生成: 安全なアクション dispatch を備えた System.Callable クラスを構築
2. Callable レビュー: 既存の callable 実装を正確性とリスクについて監査
3. 検証とスコアリング: 120ポイントルーブリックに対して評価
4. Industries 適合性: OmniStudio/Industries 拡張ポイントとの互換性を確保

---

ワークフロー (4フェーズパターン)

フェーズ 1: 要件のヒアリング

以下について確認します:

• エントリーポイント (OmniScript、Integration Procedure、DataRaptor、または他の Industries フック)
• アクション名 (call に渡される文字列)
• 入力/出力コントラクト (必須キー、型、レスポンス形式)
• データアクセス要件 (オブジェクト/フィールド、CRUD/FLS ルール)
• 副作用 (DML、callouts、非同期要件)

その後:

1. 既存の callable クラスをスキャン: Glob: **/*Callable*.cls
2. Industries 拡張機能用の共有ユーティリティやベースクラスを特定
3. タスクリストを作成

---

フェーズ 2: 設計およびコントラクト定義

Callable コントラクトを定義:

• アクションリスト (明示的でバージョン管理された文字列)
• 入力スキーマ (必須キー + 型)
• 出力スキーマ (一貫したレスポンスエンベロープ)

推奨レスポンスエンベロープ:

{
  "success": true|false,
  "data": {...},
  "errors": [ { "code": "...", "message": "..." } ]
}

アクション dispatch ルール:

• switch on action を使用
• デフォルトケースは型付き例外をスロー
• 動的メソッド呼び出しやリフレクションなし

VlocityOpenInterface / VlocityOpenInterface2 コントラクトマッピング:

レガシー Open Interface 拡張機能向けに設計する場合 (または Callable + Open Interface デュアルサポート)、 シグネチャをマッピングします:

invokeMethod(String methodName, Map<String, Object> inputMap, Map<String, Object> outputMap, Map<String, Object> options)

パラメータ	役割	Callable 同等物
methodName	アクション選択 (action と同じセマンティクス)	call(action, args) の action
inputMap	プライマリ入力データ (必須キー、型)	args.get('inputMap')
outputMap	結果が書き込まれる可変マップ (参照による出力)	戻り値; Callable はエンベロープを返す
options	追加コンテキスト (親 DataRaptor/OmniScript コンテキスト、呼び出しメタデータ)	args.get('options')

Open Interface コントラクト設計ルール:

• inputMap と options を統合入力スキーマとして扱う
• アクションごとに outputMap に書き込む必要があるキーを定義 (成功とエラーケース)
• methodName 文字列を保持して、Callable の action 文字列と整列させる
• 各アクションについて options が必須か、オプションか、未使用かを文書化する

---

フェーズ 3: 実装パターン

バニラ System.Callable (フラット args、Open Interface 結合なし):

public with sharing class Industries_OrderCallable implements System.Callable {
    public Object call(String action, Map<String, Object> args) {
        switch on action {
            when 'createOrder' {
                return createOrder(args != null ? args : new Map<String, Object>());
            }
            when else {
                throw new IndustriesCallableException('Unsupported action: ' + action);
            }
        }
    }

    private Map<String, Object> createOrder(Map<String, Object> args) {
        // 入力を検証 (例: args.get('orderId'))、ビジネスロジックを実行、レスポンスエンベロープを返す
        return new Map<String, Object>{ 'success' => true };
    }
}

呼び出し元がフラット args を渡し、VlocityOpenInterface 統合が不要な場合にバニラパターンを使用します。

Callable スケルトン (VlocityOpenInterface と同じ入力):

呼び出し元が Open Interface 統合またはその構造を渡す場合に inputMap と options キーを args で使用:

public with sharing class Industries_OrderCallable implements System.Callable {
    public Object call(String action, Map<String, Object> args) {
        Map<String, Object> inputMap = (args != null && args.containsKey('inputMap'))
            ? (Map<String, Object>) args.get('inputMap') : (args != null ? args : new Map<String, Object>());
        Map<String, Object> options  = (args != null && args.containsKey('options'))
            ? (Map<String, Object>) args.get('options')  : new Map<String, Object>();
        if (inputMap == null) { inputMap = new Map<String, Object>(); }
        if (options  == null) { options  = new Map<String, Object>(); }

        switch on action {
            when 'createOrder' {
                return createOrder(inputMap, options);
            }
            when else {
                throw new IndustriesCallableException('Unsupported action: ' + action);
            }
        }
    }

    private Map<String, Object> createOrder(Map<String, Object> inputMap, Map<String, Object> options) {
        // 入力を検証、ビジネスロジックを実行、レスポンスエンベロープを返す
        return new Map<String, Object>{ 'success' => true };
    }
}

入力形式: 呼び出し元は args を { 'inputMap' => Map<String, Object>, 'options' => Map<String, Object> } として渡します。 後方互換性のため、args が 'inputMap' を含まない場合、args 自体を inputMap として扱い、options に空のマップを使用します。

実装ルール:

1. call() を薄く保ち、プライベートメソッドまたはサービスクラスに委譲
2. 入力型の検証と強制を早期に実行 (null セーフ)
3. CRUD/FLS と sharing を適用 (with sharing、Security.stripInaccessible())
4. args がレコードコレクションを含む場合は bulkify
5. 適切な場合は SOQL に WITH USER_MODE を使用

VlocityOpenInterface / VlocityOpenInterface2 実装:

omnistudio.VlocityOpenInterface または omnistudio.VlocityOpenInterface2 を実装する場合、 シグネチャを使用:

global Boolean invokeMethod(String methodName, Map<String, Object> inputMap,
                           Map<String, Object> outputMap, Map<String, Object> options)

Open Interface スケルトン:

global with sharing class Industries_OrderOpenInterface implements omnistudio.VlocityOpenInterface2 {
    global Boolean invokeMethod(String methodName, Map<String, Object> inputMap,
                                Map<String, Object> outputMap, Map<String, Object> options) {
        switch on methodName {
            when 'createOrder' {
                Map<String, Object> result = createOrder(inputMap, options);
                outputMap.putAll(result);
                return true;
            }
            when else {
                outputMap.put('success', false);
                outputMap.put('errors', new List<Map<String, Object>>{
                    new Map<String, Object>{ 'code' => 'UNSUPPORTED_ACTION', 'message' => 'Unsupported action: ' + methodName }
                });
                return false;
            }
        }
    }

    private Map<String, Object> createOrder(Map<String, Object> inputMap, Map<String, Object> options) {
        // 入力を検証、ビジネスロジックを実行、レスポンスエンベロープを返す
        return new Map<String, Object>{ 'success' => true, 'data' => new Map<String, Object>() };
    }
}

Open Interface 実装ルール:

• putAll() または個別の put() 呼び出しを介して結果を outputMap に書き込む; invokeMethod からエンベロープを返さない
• 成功時は true、非サポートまたは失敗時は false を返す
• Callable と同じ内部プライベートメソッドを使用 (同じ inputMap と options パラメータ); エントリーポイントのみが異なる
• 一貫性のために同じエンベロープ形式 (success、data、errors) で outputMap を設定

Callable と Open Interface は同じ入力 (inputMap、options) を受け入れ、共有ロジック用に同じプライベートメソッドシグネチャに委譲します。

---

フェーズ 4: テストと検証

最小テスト:

• ポジティブ: サポートされているアクションが正常に実行される
• ネガティブ: 非サポートアクションが予想される例外をスロー
• コントラクト: 欠落/無効な入力がエラーエンベロープを返す
• バルク: リスト入力を制限に達することなく処理

例テストクラス:

@IsTest
private class Industries_OrderCallableTest {
    @IsTest
    static void testCreateOrder() {
        System.Callable svc = new Industries_OrderCallable();
        Map<String, Object> args = new Map<String, Object>{
            'inputMap' => new Map<String, Object>{ 'orderId' => '001000000000001' },
            'options'  => new Map<String, Object>()
        };
        Map<String, Object> result =
            (Map<String, Object>) svc.call('createOrder', args);
        Assert.isTrue((Boolean) result.get('success'));
    }

    @IsTest
    static void testUnsupportedAction() {
        try {
            System.Callable svc = new Industries_OrderCallable();
            svc.call('unknownAction', new Map<String, Object>());
            Assert.fail('Expected IndustriesCallableException');
        } catch (IndustriesCallableException e) {
            Assert.isTrue(e.getMessage().contains('Unsupported action'));
        }
    }
}

---

マイグレーション: VlocityOpenInterface から System.Callable へ

Industries 拡張機能を最新化する際は、VlocityOpenInterface または VlocityOpenInterface2 実装を System.Callable に移行し、アクション コントラクトを安定させます。Salesforce ガイダンスを信頼のおける情報源とします。 Salesforce Help

ガイダンス:

• アクション名 (methodName) を call() の action 文字列として保持
• inputMap と options を args のキーとして渡す: { 'inputMap' => inputMap, 'options' => options }
• outMap を変更する代わりに一貫したレスポンスエンベロープを返す
• call() を薄く保ち、同じ内部メソッド (シグネチャ (inputMap, options)) に委譲
• 各アクションと非サポートアクションのテストを追加

例マイグレーション (パターン):

// 前: VlocityOpenInterface2
global class OrderOpenInterface implements omnistudio.VlocityOpenInterface2 {
    global Boolean invokeMethod(String methodName, Map<String, Object> input,
                                Map<String, Object> output,
                                Map<String, Object> options) {
        if (methodName == 'createOrder') {
            output.putAll(createOrder(input, options));
            return true;
        }
        return false;
    }
}

// 後: System.Callable (同じ入力: inputMap、options)
public with sharing class OrderCallable implements System.Callable {
    public Object call(String action, Map<String, Object> args) {
        Map<String, Object> inputMap = args != null ? (Map<String, Object>) args.get('inputMap') : new Map<String, Object>();
        Map<String, Object> options  = args != null ? (Map<String, Object>) args.get('options')   : new Map<String, Object>();
        if (inputMap == null) { inputMap = new Map<String, Object>(); }
        if (options  == null) { options  = new Map<String, Object>(); }

        switch on action {
            when 'createOrder' {
                return createOrder(inputMap, options);
            }
            when else {
                throw new IndustriesCallableException('Unsupported action: ' + action);
            }
        }
    }
}

---

ベストプラクティス (120ポイントスコアリング)

カテゴリ	ポイント	キールール
コントラクト & Dispatch	20	明示的なアクションリスト; switch on; バージョン管理されたアクション文字列
入力検証	20	必須キーを検証; 型を安全に強制; null ガード
セキュリティ	20	with sharing; CRUD/FLS チェック; Security.stripInaccessible()
エラーハンドリング	15	型付き例外; 一貫したエラーエンベロープ; 空の catch なし
Bulkification と制限	20	ループ内に SOQL/DML なし; リスト入力をサポート
テスト	15	ポジティブ/ネガティブ/コントラクト/バルクテスト
ドキュメント	10	クラスおよびアクションメソッド用 ApexDoc

閾値: ✅ 90+ (準備完了) | ⚠️ 70-89 (レビュー) | ❌ <70 (ブロック)

---

⛔ ガードレール (必須)

以下のいずれかが導入される場合は停止して、ユーザーに確認してください:

• ユーザー入力に基づく動的メソッド実行 (リフレクションなし)
• ループ内の SOQL/DML
• callable クラスの without sharing
• サイレント失敗 (空の catch、swallowed 例外)
• アクション間で一貫性のないレスポンス形状

---

よくある アンチパターン

• call() がビジネスロジックを含み、委譲していない
• アクション名がバージョン管理されていないまたは文書化されていない
• 入力マップがチェックなしにキーを持つと仮定
• 混合レスポンスタイプ (時に Map、時に String)
• 非サポートアクションのテストなし

---

クロススキル統合

スキル	使用時	例
sf-apex	Callable 実装以外の一般的な Apex 作業	"Account 向けトリガーを作成"
sf-metadata	コーディング前にオブジェクト/フィールドの可用性を検証	"Product2 を説明"
sf-deploy	Callable クラスを検証/デプロイ	"サンドボックスにデプロイ"

---

参考スキル

以下のコア Apex 標準、テストパターン、ガードレールを使用:

• skills/sf-apex/SKILL.md

---

バンドルされた例

• examples/Test_QuoteByProductCallable/ — WITH USER_MODE を使用した読み取り専用クエリ例
• examples/Test_VlocityOpenInterfaceConversion/ — レガシー VlocityOpenInterface からのマイグレーション
• examples/Test_VlocityOpenInterface2Conversion/ — VlocityOpenInterface2 からのマイグレーション

注

• 確定的で副作用を認識した callable アクションを優先
• アクションコントラクトを安定させます; 破壊的変更に対しては新しいアクションを導入
• 長時間実行される作業を同期 callable で避ける; 必要に応じて非同期を使用