Blueprint & Codeblocks

Norbital keeps custom logic small and explicit. When configuration alone is not enough, you add a typed codeblock to the blueprint instead of building a separate service.

When To Use Codeblocks

Use a codeblock when you need logic such as:

a custom record interface,
a page UI block,
domain validation,
a notification audience or message template,
an export transform,
a web automation template.

CEL vs TypeScript

Use CEL for short expressions and TypeScript when you need structure, branching, async work, or a return object with a defined shape.

CEL is ideal for record labels, simple conditions, visibility rules, and subjects.
TypeScript is ideal for forms, notifications, export logic, and automation runs.

The Execution Pipeline

When a blueprint codeblock runs, Norbital:

resolves the codeblock by its blueprint path,
generates the appropriate type surface for the codeblock context,
compiles the block,
executes it in an isolated sandbox,
returns the result to the calling route or UI surface.

Host Functions

Depending on the codeblock type, the sandbox can inject platform helpers such as collection queries or browser automation session access.

Those helpers are scoped to the current request context, which is why permissions and redaction still matter even inside custom logic.

Codeblocks stay close to the workflow

The best codeblocks are small and specific. Use them to finish a workflow the platform already models, not to recreate an external application layer inside the sandbox.

Common Codeblock Types

FORM for record interfaces
UIBLOCK_CUSTOM for page surfaces
DOMAIN_VALIDATOR for mutation rules
EXPORT_TRANSFORM and PDF document blocks for exports
AUDIENCE_MATRIX and MESSAGE_TEMPLATE for notifications
WEB_AUTOMATION for automation templates

CEL Expressions

For simple logic, CEL is often the better choice because it is shorter, easier to audit, and closer to declarative configuration.

Choose TypeScript only when the logic truly needs it.

Validation And Runtime Behavior

Norbital does substantial validation around codeblocks, especially during fork processing and preview flows. The hot runtime path is intentionally leaner so normal execution stays responsive.

Do not assume every deep invariant is rechecked on every request

For configurators, the practical rule is simple: use forks, review issues, and treat validation as part of the staging workflow rather than something you can postpone until production usage.