What runs when you save a record

Read the entity Execution Plan

Order entity Execution Plan under Design Studio → Entities → Order → Logic: header badges (Compiled storage, Plan complete, 35 steps across 7 phases, 6 unsequenced, 1 slots unordered), the Insert/Update/Delete/All ladder switch, and the numbered phases Load Defaults, Before Insert · Normalise and Before Insert · Validate expanded to show sequence slots -1000, 0 and 1 with platform steps and four business rules sharing slot 1 — The entity Execution Plan merges every participating surface — platform handlers, business rules, workflows, scripts — into the actual phase and sequence ladder for one operation, so 'what runs when this record is saved' is read from the plan, not guessed.UI captured 2026-09-06

The Execution Plan (Setup → Design Studio → Entities → the entity → Logic → Execution Plan) is the implementation-backed answer to “what runs when this record is saved?” The example shows the Order entity with the Insert ladder selected. The header confirms whether the plan is complete, identifies compiled or custom storage, counts steps and phases, and warns about unsequenced or unordered work. Each numbered phase then places platform handlers, business rules, workflows and scripts on the sequence slots they occupy, and every step carries badges for its sequence origin, inline execution and whether a failure blocks or continues.

Always choose the operation you are diagnosing—Insert, Update, Delete or All—before reading the ladder. Expand the affected phase, inspect every step in its slot, and treat warning badges as part of the contract. Recent runs answers what happened on actual saves; the plan answers what is configured to happen.

xMatix does not run each customization surface as one isolated global stage. It uses shared lifecycle phases, and the configured steps from several surfaces can appear together inside a phase. The Execution Plan is therefore more reliable than a memorized rule such as “all business rules run before all scripts.”

The lifecycle phases

Phase	Purpose	Can it prevent the operation?
Load Defaults	Insert-only audit stamps, defaults, numbering and other initial values	No; it prepares a new row before validation
PreValidate	Insert/update normalization that must happen before metadata validation	No; failures are treated as non-blocking by this phase
Validate	Metadata validation, blocking business rules, validation scripts and workflow steps mapped to validation	Yes
Before Save	In-transaction work immediately before an insert or update is written	Yes
Before Delete	Delete-specific in-transaction checks and effects	Yes
After Save	Work after the row is written while the enclosing transaction may still be open	Yes; a propagated failure can still roll back the save
After Delete	Delete-specific post-write work while the transaction may still be open	Yes for the same transactional reason
PostCommit	Saved triggers, post-save rule actions and deferred workflow/integration work after commit	No; the record is already committed
OnFailure	Compensation and failure observers when the save itself failed	It reacts to the failure rather than deciding the original save

Not every operation uses every phase. Load Defaults is insert-only; delete uses its delete-specific phases; PostCommit runs only after a successful commit; OnFailure appears only on failure. Select All when comparing ladders, not when trying to answer the order for one concrete save.

Sequence slots are shared within a phase

Within one phase, steps are ordered on a shared numeric sequence line. An explicitly sequenced script, workflow or other supported step can therefore be placed relative to a step from another surface in that same phase. A sequence does not move work into a different phase: a Validate step cannot be sequenced into PostCommit.

Three details matter:

Unsequenced means the artifact uses its surface's default slot. Make the sequence explicit when another step must reliably run before or after it.
Shared slot means multiple steps have the same effective sequence. Some, such as business rules sharing a slot, deliberately run as one engine call so StopOnFalse and SetValue priority can be resolved together. Other slots may be marked unordered, meaning their relative order is not defined.
Sequence not enforced means the plan can display the requested position but the current runtime path does not honor it. Treat that badge as a release blocker for any dependency on the shown order.

Business-rule Sequence positions a rule's slot on this cross-surface line where runtime support is active. Rules within the same slot are evaluated together; their Order supplies the intra-slot order and Priority resolves competing SetValue actions on the same field. Those fields are not interchangeable.

Platform logic, workflows, approvals and scripts

First-party module behavior is represented as platform or C# handler steps in the same phases. This is where sales, inventory, finance and other feature validation or derivation appears; it is not a single opaque “module logic after rules” stage.

Workflows and automation scripts are mapped to the phase configured for their binding. A validation-phase step can block; a PostCommit continuation cannot undo the committed row. Asynchronous steps can finish later, so never make the next synchronous save step depend on their completion.

Approval is not an automatic universal phase that every eligible save enters. A record reaches approval only through a configured entry point—for example a Request Approval rule action, an explicit record action, a workflow or feature-specific handler. Inspect that entry artifact and the entity's Approval Processes alongside the Execution Plan.

Diagnose a blocked save or changed value

Open Design Studio → Entities, select the exact entity, expand Logic, and open Execution Plan.
Select Insert, Update or Delete to match the failed operation.
Confirm Plan complete. If a source is unavailable, fix that visibility problem before assuming the ladder is exhaustive.
Expand the phase named by the error or trace. If none is named, start at Validate for a rejected save and work forward for an unexpected value.
Read slots from lowest to highest sequence. Inspect every artifact in a shared slot and every warning badge.
For a value change, identify each writer and find the last successfully executed in-transaction writer. PostCommit work can create later effects, but it cannot rewrite the already committed transaction without starting a separate operation.
Open Recent runs and match the entity, operation and timestamp. Compare observed steps with the plan before changing configuration.
Test the smallest safe change with both a passing and failing record, then restore the intended sequence documentation.

Common questions

A business rule and a script both set the same field—which wins?

There is no safe category-wide answer. Compare their lifecycle phase, effective sequence and slot behavior in the entity's Execution Plan. A later in-transaction writer normally supplies the stored value, unless an earlier step blocks the save or the steps share an engine slot whose own priority rules decide the conflict.

Can I put a script before a business rule?

Yes only when both map to the same lifecycle phase and their runtime paths enforce the configured sequence. Set explicit sequences, then verify the plan shows the intended slots without a sequence not enforced or unordered warning. A sequence cannot cross phase boundaries.

Can After Save fail the save?

Yes. The row may have been written to the database context, but the enclosing transaction can still be open. A propagated After Save or After Delete failure can roll the transaction back. Only PostCommit is definitively too late to block the committed operation.

Does every qualifying record enter approval automatically?

No. Approval requires a configured entry action or feature path. The process definition describes what happens after entry; it does not by itself submit every record that happens to match its entity.