API リファレンス: SBlueprint

SBlueprint は ApexBlueprint で 単一レコードの設計図 を宣言するメソッドチェーンクラス。of(...) で起点を作り、値・identifier・親子関係・量産・参照などをチェーンで積み重ねて、最終的に SOrchestrator に渡して実行します。

使い方や典型シナリオは SBlueprint で単一レコードを宣言する と 親子・量産・参照のパターン を参照してください。

Static ファクトリ

recordType に null や非 SObject 型を渡すと例外が投げられます。

値設定 (Set & Template)

startAt / interval に 負の値 を渡すと例外が投げられます。

SBlueprint accountBp = SBlueprint.of(Account.class)
    .template(Blueprints.accBasic())     // 共通デフォルト
    .set('Name', 'CustomName')              // 個別上書き
    .set('Index', 'No.{#}', 1, 1);          // {#} 連番

識別子 (Alias)

alias は SOrchestrator 内で 一意である必要 があり、重複すると Duplicate alias detected で実行時エラーになります。.times(n) と組み合わせる場合は 'con_{#}' のような {#} 付き alias を使って、展開後に一意な値が払い出されるようにします。

SBlueprint.of(Contact.class)
    .alias('con_{#}')        // con_1 / con_2 / con_3
    .times(3);

参照 (Use)

別の blueprint からの値を、自分のフィールドにマッピングする多目的 API。「Id を子の lookup に転記する (リレーション作成)」と「任意のフィールド値を引き写す」の両方に使えます。

startAt / interval に 負の値 を渡すと例外が投げられます。詳細な使い方や「不揃いな対応」のパターンは 親子・量産・参照のパターン を参照してください。

SBlueprint.of(Contact.class)
    .use('acc_{#}', 'Id', 'AccountId', 6)   // acc_6 〜 acc_10 を参照
    .alias('con_{#}', 6)                    // 子側も 6 始まり
    .times(5);

量産 (Times)

.times(n) を .withChildren(...) のネスト内 で使うと、件数は階層をまたいで掛け算で増えます (親 2 × 子 2 = 子 4 件)。詳細は 親子・量産・参照のパターン > Multiplication を参照。

順序だけの依存 (After)

use() は「参照を作る」ため、値のコピーが伴います。値は要らないが順序だけ守りたいとき、たとえばトリガーの都合で「A が入ってから B を入れたい」ようなケースに after() を使います。

SOrchestrator.start()
  .add(SBlueprint.of(Account.class).template(Blueprints.accBasic()).alias('acc'))
  .add(
    SBlueprint.of(Contact.class)
      .set('LastName', 'Yamada')
      .after('acc')   // acc より後のレイヤーに置くだけ。値は引かない
  );

所有者と共有 (Owner & Share)

sharedWith を書くと、create() の際に Foo__Share / AccountShare といった兄弟 blueprint が自動生成され、そのレコードの 1 レイヤー後に insert されます。親 Id の配線も自動です。

「誰がこのレコードを持っていて、誰から見えるのか」は項目値と同じく宣言された最終状態の一部、という考え方から blueprint 側に置かれています。

// 管理者が所有し、rep には Read だけ与える = runAs 監査テストの「敵対的データ」
SOrchestrator.start()
  .add(
    SBlueprint.of(Invoice__c.class).alias('inv')
      .owner(admin)
      .sharedWith(rep, 'Read')
  );

times / ネスト / {Pn} と合成できます (子の共有は子と一緒に増殖します)。OWD が Public のオブジェクト、所有者自身への共有、不正な accessLevel は fail-fast で弾かれます。

親子関係

SBlueprint.of(Account.class)
    .alias('acc')
    .withChildren(
        SBlueprint.of(Contact.class)
            .parentIdField('AccountId')      // 複数 lookup を持つ場合に明示
            .set('LastName', 'TestContact')
    );

プレースホルダ

.set / .alias / .use の文字列引数の中で使える特殊プレースホルダ。

{P0} 〜 {Pn} は .times(...) で量産された親階層を持つネスト構造で、alias の {#} 展開だけでは「自分の真の親」を特定できない問題への構造的な解決手段です。動機と仕組みは 親子・量産・参照のパターン > {P0} / {P1} / ... を参照してください。

主な例外

フレームワークが検出したエラーは ApexBlueprintException として投げられます。

例外型で原因を切り分けられる

create() が失敗したとき、例外の型がそのまま原因の切り分けになります。

• ApexBlueprintException = 宣言のミス。テストコードを直す
• DmlException = org が insert を拒否した。template か org 設定を直す

項目適用のエラーは「どの blueprint (alias) の・どの経路 (set / template / use) で・なぜ (存在しない / 数式 / 自動採番 / 作成不可 / 型不一致)」まで自動で診断されます。

⚠️ v2.0.0 の破壊的変更です。それ以前は素の DmlException が投げられていたため、既存の catch (DmlException) では捕まらなくなります。移行時は catch 節の見直しが必要です。

関連ドキュメント

• SBlueprint で単一レコードを宣言する: 基本 5 メソッドの使い方
• 親子・量産・参照のパターン: withChildren / times / {P0} 等の応用
• API リファレンス: SOrchestrator: 実行エンジン側の API
• ApexBlueprint ガイドへ戻る