# Fill each line's roles: direct, lookup or rule

Fill the receiving product's published roles from the shop's data, see why a line misses one, and fix it.

Source: https://help.smartfact.ai/manuals/configsheets/mapping-roles

Review edition: 18 November 2026

Roles: author, reviewer, supervisor, operator

Each product that SmartFACT Data feeds publishes the record it accepts: a list of roles, each with a name, a type and words for people, some required and some optional. A shop connection's mapping release fills that record for every order, from the shop's own data. Data reads the roles from the product's published record, so when a product publishes a new version, its roles appear here as soon as Data accepts that version.

## The roles of a shop order

A shop connection feeds StoresFlow's **Shop order**, one record for the whole order, sent again whenever the order changes. Data fills most of it itself: the order number, the shop's status and when it changed, the sales channel, whether a despatch is booked, the release that filled it and, for each line, the shop's own key, product name and quantity ordered, how much of the item the line takes, and the line's evidence. A release fills these roles of each line:

- **Item** (required): StoresFlow's own code for the stock item.
- **Expected drawer** (optional): the drawer the line should be picked from.
- **Item barcode** (optional): a code a picker may scan to prove the item, beside the item's own codes in StoresFlow.

The release's SKU table always fills the item: the line's key, its native SKU or an additional data key, is matched against the table's shop SKU, and the matched row gives the item code and the quantity of one unit, from which Data works out how much the line takes. **Draft a mapping release** shows every role, its words, and how it is filled. An optional role you leave unfilled is sent empty.

## Choose how a role is filled

For each other role, choose one of three forms under **Filled by**:

- **One input of the line** (direct): the native SKU, the product ID, the variation ID, or one additional data key the shop plugin sends, such as `drawer`. The value is taken exactly as it is.
- **Looking an input up in a saved table** (lookup): choose the line input, a saved version of a large reference table, the column to match the input against and the column to take the value from. Exactly one row must match, as exact text: nothing is trimmed, case is kept and leading zeroes count. The release pins that table version; a later version is used only by a new release.
- **Reviewed rules with examples** (rule): name the line inputs the rules read, then write rules that are tried in order, each with a condition and a result: a fixed code, or one input's value. The first rule that matches gives the value. Add worked examples, each with the inputs and the value or reason you expect: every example must pass before the release can be activated. Rules are written as JSON, for example `{"inputs": {"code": {"source": "additional_data", "key": "product_sku"}}, "rules": [{"when": {"op": "eq", "field": "code", "value": "SYN-1"}, "result": {"value": "SYN-K-21"}}], "examples": [{"name": "SYN-1 is in SYN-K-21", "facts": {"code": "SYN-1"}, "expected": {"value": "SYN-K-21"}}]}`.

Nothing falls back from one input to another. A dot is part of an additional data key's name: `product.sku` is one key.

## When a form cannot fill a line

Every form names why, the same way: the line has no such input, the input is empty, the input is not a valid value for the role, nothing matches, more than one row matches, the matching row's cell is empty, or the result is not a valid value for the role.

What happens next is the receiving product's choice, published with its record, and a line is never left out. For the expected drawer and the item barcode, the line is sent as usual with that role empty, and the reason travels in the line's evidence, so StoresFlow shows the line on the ticket with no location and it is found by hand. The line is listed under **Lines to fix** on the connection's page with its order, line, shop key, form and reason, so a missing drawer is seen. Correct the table, the shop's data or the release, then read the order again.

When the item cannot be filled, because the key is not in the SKU table, the table marks it not stocked, or the line has no usable key, the line is still sent, **unlisted**: with the shop's key and product name, the quantity ordered and the reason, marked "not in StoresFlow". It is on the ticket, picked by hand, and moves no stock. It is listed under **Lines to fix** too. Map the key in a new release so the next order's line is listed.

Only what the receiving product says holds an order holds it. A line whose quantity Data cannot work out, such as a quantity that is not a whole number, never holds the order: it is sent unlisted with the shop's quantity, picked by hand, and listed under **Lines to fix** until the shop corrects it. A line StoresFlow has already taken keeps the quantity it was taken with.

## When StoresFlow has not yet accepted the record

StoresFlow says which version of the record it accepts. Data sends an order only when StoresFlow accepts exactly the version Data fills; until then the order waits, and the connection's page says **Waiting for StoresFlow to accept shop orders version 1** with how many are waiting. Nothing waiting is lost: once StoresFlow accepts the version, the waiting orders are sent. Data asks StoresFlow again every five minutes while orders wait.

## Review and activate

A different person reviews the release. They may not have written the release, its SKU table or any table version a lookup reads, unless they are an Owner approving it alone with a written reason (see "Draft and independently activate a shop mapping"). The review shows each role and how it is filled, how many retained lines each role fills and, for each reason, how many it misses, and for each changed order line the value and its evidence: the form, the input, the table version and row or the rule that matched. A rule's examples are listed with the other examples, and a failing one stops activation.

A release fills one version of the receiving product's record. If the product publishes another version, an older release cannot be activated: draft and review a new one.

## What each line keeps

Each line keeps the evidence of every role beside its item and quantity: the release, one snapshot of the inputs read, and each role's form, table version, row and value or reason. Its evidence reference travels with the line and StoresFlow keeps it on the ticket. Once StoresFlow accepts the line, these are fixed. A later table version or release never changes a line already accepted, including a line accepted with its drawer empty or accepted unlisted: the correction applies to the next lines. The connection's **Propose StoresFlow home bins** uses the same forms to propose each item's drawer to StoresFlow (see "Propose StoresFlow home bins from a release").
