ApexBlueprint API reference: SBlueprint

SBlueprint is the method-chain class used in ApexBlueprint to declare a blueprint for a single record. You start from of(...), then stack values, identifiers, parent-child relationships, bulk generation, and references via the chain, and finally hand it to SOrchestrator to execute.

For usage and typical scenarios, see Declaring a Single Record with SBlueprint and Relations, Bulk Generation, and Reference Patterns.

Static Factory

Passing null or a non-SObject type to recordType raises an exception.

Value Setters (Set & Template)

Passing a negative value to startAt / interval raises an exception.

SBlueprint accountBp = SBlueprint.of(Account.class)
    .template(Blueprints.accBasic())     // shared defaults
    .set('Name', 'CustomName')              // individual override
    .set('Index', 'No.{#}', 1, 1);          // {#} sequence

Identifier (Alias)

Aliases must be unique within SOrchestrator; duplicates raise Duplicate alias detected at runtime. When combining with .times(n), use {#}-bearing aliases like 'con_{#}' so that unique values are issued after expansion.

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

Reference (Use)

A multi-purpose API for mapping a value from another blueprint into a field on this one. Usable both for "copying an Id into a child's lookup (creating a relationship)" and "copying an arbitrary field value".

Passing a negative value to startAt / interval raises an exception. For detailed usage and "uneven mapping" patterns, see Relations, Bulk Generation, and Reference Patterns.

SBlueprint.of(Contact.class)
    .use('acc_{#}', 'Id', 'AccountId', 6)   // reference acc_6 to acc_10
    .alias('con_{#}', 6)                    // children also start from 6
    .times(5);

Bulk Generation (Times)

Using .times(n) inside nested .withChildren(...) causes record counts to multiply across hierarchies (parent 2 × child 2 = 4 children). See Relations, Bulk Generation, and Reference Patterns > Multiplication.

Ordering-Only Dependency (After)

use() exists to build a reference, so it always carries a value. Use after() when you don't want the value but do need the order — for example when a trigger requires that A already exists before B lands.

SOrchestrator.start()
  .add(SBlueprint.of(Account.class).template(Blueprints.accBasic()).alias('acc'))
  .add(
    SBlueprint.of(Contact.class)
      .set('LastName', 'Yamada')
      .after('acc')   // just place it in a later layer than acc; copy nothing
  );

Owner & Sharing (Owner & Share)

Writing sharedWith makes create() auto-generate a sibling blueprint (Foo__Share / AccountShare) that is inserted one layer after the record itself. The parent Id wiring is automatic too.

These live on the blueprint because "who owns this record, and who can see it" is part of the declared final state, exactly like a field value.

// Owned by an admin, rep gets Read only — the "hostile data" of a runAs audit test
SOrchestrator.start()
  .add(
    SBlueprint.of(Invoice__c.class).alias('inv')
      .owner(admin)
      .sharedWith(rep, 'Read')
  );

It composes with times / nesting / {Pn} (a child's share multiplies along with the child). An object whose OWD is Public, a share aimed at the owner itself, and an invalid accessLevel are all rejected fail-fast.

Parent-Child Relationships

SBlueprint.of(Account.class)
    .alias('acc')
    .withChildren(
        SBlueprint.of(Contact.class)
            .parentIdField('AccountId')      // specify when multiple lookups exist
            .set('LastName', 'TestContact')
    );

Placeholders

Special placeholders that can be used inside string arguments to .set / .alias / .use.

{P0} ~ {Pn} are the structural solution to the problem where, in nested structures with .times(...) at each tier, the {#} expansion of an alias alone cannot identify "the true parent for me". For motivation and mechanics, see Relations, Bulk Generation, and Reference Patterns > {P0} / {P1} / ....

Common Exceptions

Errors the framework detects are thrown as ApexBlueprintException.

The exception type tells you where to look

When create() fails, the type of the exception is itself the diagnosis.

• ApexBlueprintException = a mistake in the declaration. Fix the test code
• DmlException = the org refused the insert. Fix the template or the org configuration

Field-application errors are diagnosed all the way down to "which blueprint (alias), through which path (set / template / use), and why (non-existent / formula / auto-number / non-createable / type mismatch)".

⚠️ This is a breaking change in v2.0.0. Previously a plain DmlException was thrown, so existing catch (DmlException) blocks will no longer catch these. Review your catch clauses when migrating.

Related Documents

• Declaring a Single Record with SBlueprint: How to use the five core methods
• Relations, Bulk Generation, and Reference Patterns: Applications of withChildren / times / {P0} etc.
• API Reference: SOrchestrator: The execution engine API
• Back to the ApexBlueprint Guide