Concept

How a rule differs from a constraint

A rule reacts: when X is chosen, do Y. A constraint holds: Z must always be true. Rules shape the configuration; constraints guard it.

, imagine.io ·

A rule reacts to a selection and changes something: hide an option, swap a part, load a product, set a material, show a message. A constraint is a condition that must always hold, such as a maximum count or a fixed position, and is re-checked after every change. Rules shape the configuration; constraints guard it. Most products need both. Both run on the server, inside the imagine.io constraints engine, on every change the shopper makes; the browser never evaluates either. How that round trip works, step by step: server-side constraint and rule evaluation.

A RULE REACTSShopper adds a chaisethe trigger matcheswhen a module is added to an end,remove the arm on that end200 appliedarm hidden, price updatedshapes the configurationA CONSTRAINT HOLDSShopper adds a 7th unitany change at allat most 6 units in totalre-checked after every change422 rejectedprevious state kept, reason shownguards it A RULE REACTSShopper adds a chaisethe trigger matcheswhen a module is added to an end,remove the arm on that end200 appliedarm hidden, price updatedshapes the configurationA CONSTRAINT HOLDSShopper adds a 7th unitany change at allat most 6 units in totalre-checked after every change422 rejectedprevious state kept, reason shownguards it
A rule fires when its trigger matches and changes the result. A constraint is checked after every change and refuses the ones that break it.

A constraints engine, not just rules

Other configurators have a rules engine. The imagine.io engine is a constraints engine: every change is checked on the server against the limits you set, so only valid configurations are ever built. Rules still shape the result, hide, swap, load, price, but they can never produce something that breaks a constraint. The rest of this page shows what each one can do and how the engine answers it.

Side by side

RuleConstraint
RunsWhen its trigger matches: a variant is placed or selected, a component is loaded or selected, an option is chosen, the scene loads, or a custom condition is true.After every change, whatever the change was.
Can doHide, disable or narrow options; swap, hide, show or move parts; load or unload a product; set a material; change a default; show a message; emit an event to your code; run custom actions.Refuse the change with a message; or for the built-in types, act instead: replace the conflicting product, add the missing anchor or partner, shift a product away.
ScopeAttached to one or more systems. The effect applies to the placement that triggered it, or scene-wide.Attached to one or more systems. Checked against a product or a variant, counted across the whole scene.
How the engine answersInside a 200: overrides on the placement, optionVisibility, optionAvailability, messages, events, added or removed placements.A 422 with the code CONSTRAINT_VIOLATION_HARD, the constraint's id and errors[0].message, and the previous state kept.
Per sales channelYesYes

What a rule looks like

In the dashboard a rule is a when dropdown and a then dropdown. When the “No handle” option is selected, then hide the handle component group. When a dishwasher variant is placed, then show a message. When the chaise is placed, then hide the arm on that end. When the dropdowns run out, pick Custom and write the condition or the actions as JSON:

// Trigger Params (Custom trigger): base cabinets wider than 24 inches
{ "mode": "triggered",
  "when": [ { "$me.category": "Base Cabinet" }, { "$me.width": { ">": 24 } } ] }

// Effect Params (Custom effect): what to do on the triggering product
{ "actions": [
  { "hide_component": { "on": "$me", "slot": "handle" } },
  { "set_material":   { "on": "$me", "slot": "cabinet", "material_id": 18 } },
  { "emit_event":     { "name": "wide_cabinet", "payload": { "pid": "$me.id" } } }
] }

$me is the product being looked at, $scene the whole scene, $context.focus what the shopper has clicked. A list of conditions means all must hold; or and not cover the rest.

What a constraint looks like

Eight built-in types cover most limits: Max Count, Mutually Exclusive, Positioned Above, Requires Together, Fixed Position, Adjacency Required, Min Separation, and Custom. Each has a target (a product or variant) and a few value fields. A dishwasher that must sit next to the sink is Adjacency Required with a and b; two appliances that must not touch is Min Separation with the number of cabinets between them. A custom constraint is a condition and what to do when it holds:

// Value (Custom constraint): no more than two tall cabinets in a run
{ "when": [ { "count_of": { "graph_id": 4 }, ">": 2 } ],
  "then": [ { "reject": { "message": "No more than two tall cabinets in a run." } } ] }

// What the shopper's page receives when it fires
HTTP 422
{ "code": "CONSTRAINT_VIOLATION_HARD", "errors": [ { "code": "CONSTRAINT_VIOLATION_HARD", "message": "No more than two tall cabinets in a run." } ] }

A custom constraint answers with reject, warn or emit_info. Three built-in types keep the scene consistent instead of refusing: Fixed Position moves the piece back to its pinned position, Positioned Above keeps a piece moving with the product it sits above, and Requires Together loads the partner. Those come back as a 200 with the moved or added placement. Everything else that changes the configuration belongs in a rule.

Which one to write

  • The shopper chose something and something else should follow: a rule. Fabric picked, piping matches. Chaise added, arm goes. Wider oven, wider housing.
  • Something must never be true, whichever way the shopper got there: a constraint. No more than six units in total. The hood sits above the hob. The dishwasher is next to the sink.

Frequently asked questions

Can a rule refuse a change?

No. A rule shapes the result: it hides, swaps, loads, prices, messages. Only a constraint refuses, with a 422 and a reason.

Can a constraint change the configuration?

Mostly it refuses the change that would break it: Mutually Exclusive blocks the second product, Min Separation refuses a move that would bring two pieces closer than the minimum. A few built-in types keep the scene consistent instead: Fixed Position moves a piece back to its pinned position, Positioned Above keeps a piece moving with the product it sits above, Requires Together loads the partner. A custom constraint can only reject, warn or emit an informational note.

Do I need JSON for most rules?

No. Both rules and constraints are built from dropdowns in the dashboard: seven triggers, seventeen effects, eight constraint types. The Custom choice with a few lines of JSON is for the cases the dropdowns cannot express.

Can a rule or constraint apply to one sales channel only?

Yes. Both can be limited to a channel, so a dealer portal can have a rule or a limit your own store does not.

What is the difference between rules and constraints in a product configurator?

A rule reacts to a selection and changes the configuration, while a constraint is a condition that must always hold and is re-checked after every change. In the imagine.io Configurator Platform both run on the server, and only a constraint can refuse a change.

What is a configuration engine in a product configurator?

A configuration engine is the part of a configurator that applies the product rules and checks the limits every time a shopper changes something. The imagine.io engine is a constraints engine: see A constraints engine, not just rules.

SDK documentation · Admin guide