Skip to main content

​
Overview

A configuration is a saved walk through one Configuration Template for one real-world order, quote, or build slot. It’s the output of a Configurator run: the selections, material assignments, and resolved parts list that turn the template’s possibility space into a concrete bill of materials for that order. Configurations live on the Configurator page, grouped under the template they were walked from.

​
Configuration vs. Revisions

A configuration is a two-level artifact:
  • The configuration itself carries identity only — a name and description. Its purpose is to group all the revisions for one order under one identifier you recognize (“Heavy-Duty Quote”, “Job 12345”).
  • Every state-bearing fact — selections, material assignments, resolved parts list, per-revision notes — lives on a child revision keyed by revision_number.
The configuration’s active state is the revision with the highest revision_number. Older revisions stay in place unchanged; the revision chain is the audit trail.

​
What a Revision Carries

​
Selections

Each entry carries option_class_id, chosen_option_ids[], and free notes. Cardinality is enforced by the class’s selection_type: select_one must land exactly one option, select_at_least_one at least one, select_many zero or more.

​
Material assignments

Each entry carries:
  • material_id — the stable key from the template tree
  • attribute_values[] — the pinned values, expressed as VariantCondition entries (the same typed union BOM variant conditions use: boolean, discrete_text, discrete_number, range). Prefer fully-pinned conditions — a range on a revision usually means a decision is unresolved.
  • source — where the value came from: an ERP part reference, “customer order PDF line 3”, a mapping-file row
  • notes — why the decision was made: justification and edge cases
source, notes, and revision_notes carry three different kinds of provenance — where the value came from, why the decision was made, and what changed in this revision. An empty source is not a schema error — the state script won’t block on it — but it is an audit-trail gap: treat it like an unverified assumption, since an assignment no one can trace can’t be evaluated at reconfiguration time.

​
Resolved parts list

The Configurator computes a flat parts list from the current selections and material assignments — every material reachable given the option choices, with its pinned attribute values. This is the concrete parts list the configuration produces for the order.

​
Phase

A revision moves through four phases as it’s walked: pending → selecting_options → assigning_materials → completed. The phase is derived from the revision’s current state — it is not a field you set by hand. See Configurator for the full phase model.

​
Creating a Configuration

Configurations are created by running the Configurator against a template:
  1. Open the template.
  2. Create a new configuration under it, named for the order or customer.
  3. Gather the order source — order PDF, ERP export, pasted text — to ground selections against. These are cited on each assignment’s source field rather than attached to the configuration itself.
  4. Dexter walks the option tree one confirmed decision at a time, then pins material attributes, source-batched against your grounded inputs.
  5. On completion, the resolved parts list is final for this revision.

​
Reading a Completed Configuration

Open the configuration and view its highest-numbered revision:
  • The selections made per option class
  • The material assignments with their source, notes, and pinned attribute values
  • The resolved parts list — every material in scope with its concrete attribute values
  • The revision notes — what changed vs. the prior revision
Earlier revisions remain available; open any one to see the state at that point in time.

​
Reconfiguring

When a completed configuration needs to change — the customer revised the order, a sourced value turned out wrong, a template edit cascaded into the selection set — the Configurator forks a new revision:
  1. Read the latest revision.
  2. Create a new revision with a descriptive slug (rev-3-hardtop-swap), revision_number + 1, and a revision_notes line naming the delta.
  3. Carry forward every selection and assignment that isn’t changing.
  4. Remove the entries that are changing; they become the open frontier the Configurator walks.
  5. Resolve any new stale entries or errors, then walk to completed.
Existing revisions are never edited. revision_number is immutable, and the version chain is implicit in the numbering — there is no parent pointer.
This is advisory, not a product rule: forking is always valid regardless of how much changes. But as a rule of thumb, if a reconfiguration would remove most of the entries, a fresh configuration under the same template is often a cleaner walk than carrying a nearly-empty revision forward.

​
Downstream Use

A completed revision’s resolved parts list is the handoff point to whatever comes next:
  • Quotes and customer-facing documents — export the resolved parts list as the confirmed bill for the order.
  • Planning demand — configurations do not auto-create demand orders. Feeding a revision into a planning run is a distinct step: either manual (add the demand order against the SKU) or pipeline-mediated (a pipeline that reads the resolved materials and writes the demand).
  • Simulation — simulation models reference entities through model nodes, not revisions. If a configuration’s material set needs to drive a simulation input, wire it through a pipeline.

​
Limits and Caveats

  • Configurations are per-template. A configuration can’t move between templates; reconfiguring against a different template means a fresh configuration under that template.
  • revision_number is immutable once set. To change a completed revision, create a new revision — there is no in-place edit.
  • Name revision slugs for what changed. Slugs like rev-1, rev-2 add no information; revision_number handles ordering on its own.
  • Mid-run template edits are global. They’re gated by ask-confirm and appended to the template’s revision_log, but every other configuration against the same template sees the update on its next state-script call.
  • Stale entries are dropped deterministically; errors with exactly one valid repair are applied directly, and anything ambiguous becomes a user decision through the ask-confirm loop.
  • Nothing downstream is automatic. Completing a revision hands you a parts list; it does not commit demand, allocate supply, or schedule production.