Allocation Rules (BETA)

Allocation rules tell the allocation engine which stores (warehouses) it may, may not, or should prefer to ship from - for example "small orders ship from the webshop warehouse", "bulky goods only from stores that can handle them", or "never split a click-and-collect order". Rules are the main way to put your sourcing policy for distributed order management (DOM) into the engine without changing code.

Manage rules in Configuration → Allocation → Rules. Select Add rule to start from a Blank rule, or Start from a template to begin from a common pattern - a template fills in the shape, and you set the values.

Start from a rule template

Omnium has 63 rule templates to help you get started. Each template sets up the stage, the condition, and the effects for a common sourcing policy, and leaves the values specific to your business - such as which stores, categories, or shipping methods - for you to fill in. A rule created from a template starts inactive, so you can test it before you switch it on.

Use Browse templates to see them all with a short description, then adjust the rule like any other - see how a rule is built.

How a rule is built

Read a rule as one sentence: within the scope, when the condition holds, apply the effects.

General: name, stage, and priority

The Stage decides when the rule is evaluated and which effects it can have:

Condition: when the rule applies

The condition decides when the rule acts. Each condition compares an attribute with a value, for example Order subtotal (order.subTotal) is less than 200. Select + Condition to add a condition and + Group to add a nested group.

Each group combines its conditions and sub-groups in one of four ways:

Nest groups to build combinations such as market is Norway and (category is furniture or weight is more than 30 kg).

Attributes are grouped by what they describe. The Available attributes panel beside the editor lists them all with a short description:

The operators you can choose depend on the attribute's type - for example, a number offers is less than and is between, and a list offers contains any of:

Separate several values with commas. Select Compare with an attribute to compare with another attribute instead of a fixed value - for example, a store property that lists the categories the store does not handle, compared with the product's categories.

An attribute with no value only matches is set and is not set. A rule with no conditions applies to everything its scope covers.

Effects: what should happen

The effects decide what happens when the condition holds. Select Add effect to add one; a rule can have several. The list only offers the effects that belong in the rule's stage.

Effects fall into four kinds:

Name stores directly, or switch on Select stores by a fact instead of by name to select them by a condition on the store - for example, every store whose warehouse.roles contains webshop. See all effects for the full list.

Scope: where the rule is used

The scope decides where the rule is used at all. Omnium checks the scope once per run, before any condition: a rule outside its scope does not take part in that run. An empty field means everywhere, so a rule with an empty scope applies to every order.

When you fill in several fields, all of them must match. Within one field, one value is enough.

The trigger says why the engine runs:

Simulations and manual allocations run as the trigger they stand in for, so they use the same rules as the workflow step:

• The simulator runs as the trigger chosen under Triggers in the Allocation flow filters, and as InitialAllocation when none is chosen.
• The Allocation API runs as the trigger in the request, InitialAllocation by default.
• Preview and allocate on a cart or an order, and Recent orders in the simulator, run as InitialAllocation.

To make a rule behave differently in a simulation than in a real run, add a condition on context.mode instead of using the trigger.

Scope or condition?

Both can test facts about the order, so choose by what the fact describes:

• Use the scope for facts that are the same for the whole order and that the scope has a field for - market, order type, customer type, sales store. A rule outside its scope is left out of the run before anything else is evaluated, which keeps the trace short.
• Use the condition for everything else: facts about the line, the product, the store, or the destination, and order values that the scope has no field for, such as the order subtotal.

The example below does both: the scope limits the rule to one order type, and the condition tests the subtotal and the currency.

Example: prefer the webshop warehouse for small orders

This rule makes the engine prefer the webshop warehouse for low-value orders in NOK and SEK, so small orders are not split across or sent from physical stores when the webshop warehouse can ship them.

General

Condition

All of these must hold:

The order subtotal is the sum of the order lines including tax, without shipping and fees.

Effects

Scope

Every other scope field is empty, so the rule applies in every market, for every customer type, and so on - but only to orders of the order type Demo.

What the rule does

For an order of type Demo with a subtotal below 200 in NOK or SEK, every line gets a preference for the WebShop store. Plans that ship lines from WebShop get a better (lower) score on the Rule preferences objective. The rule never rules any store out: if WebShop cannot serve a line, the engine still ships it from another store.

To make the rule a hard requirement instead, replace the effect with Use only these stores. Lines that WebShop cannot serve are then reported as lines that could not be placed, rather than shipped from somewhere else.

The rule as JSON

Edit as JSON in the rule's menu shows the same rule as JSON:

{
  "name": "Send small orders from central warehouse",
  "isActive": true,
  "priority": 50,
  "stage": "Line",
  "scope": {
    "marketIds": [],
    "orderTypes": ["Demo"],
    "customerTypes": [],
    "customerGroupIds": [],
    "salesStoreIds": [],
    "salesStoreGroupIds": [],
    "origins": [],
    "profileKeys": [],
    "triggers": []
  },
  "condition": {
    "operator": "And",
    "negate": false,
    "conditions": [
      { "attribute": "order.subTotal", "operator": "LessThan", "values": ["200"] },
      { "attribute": "order.currencyCode", "operator": "In", "values": ["NOK", "SEK"] }
    ],
    "groups": []
  },
  "effects": [
    { "type": "PreferWarehouses", "values": ["WebShop"], "weight": 1.0 }
  ],
  "message": "Order total below 200 NOK/SEK - shipped from the central warehouse",
  "tags": ["low-value"]
}

Test the rule

Before you activate a rule, check what it does:

• Validate in the rule's menu checks the rule without saving it, for example that every condition has a value and that each effect belongs in the rule's stage.
• Test this rule runs one order through the engine with this rule alone, so the answer is about this rule. Enter an order number and select Run test. The result says The rule matched or The rule did not match, followed by the plan.
• The allocation simulator runs an order with all active rules, and the Allocation flow tab shows where the rule acted. Use Recent orders in the simulator to see how a rule changes the choice of warehouse across many orders.

All effects

Store effects name stores directly, or select stores by a fact with Select stores by a fact instead of by name - for example every store whose warehouse.roles contains a given role.

How effects combine

• Rules run in priority order, lowest first. Exclusions and restrictions are set operations, so priority changes the order of the trace but not the result.
• Every exclusion takes its stores away, and two restrictions leave only what both allow.
• A line left with no store is reported as a line that could not be placed - it is not quietly dropped.
• Preferences add up and only affect the ranking.
• A rejected plan is retried without the stores that caused it.

Related documentation

• Allocation simulator - see how the rules act on a real order
• Allocation API - simulate allocation from a checkout or an integration
• OmniStock - the store rules that decide which stores can supply a product