Mappings

A mapping says what a value read from a column is: a product number, a quantity, a purchase price or an expiry date.

Core fields

• Label — a name describing the kind of data.
• Type — the kind of data (below).
• Entity and Field — where to look for the value when recognising the product.
• Columns — the columns the value is searched in.
• Priority — the search order; a lower number means earlier. Where several matches are possible, the first one found is used.
• Regular expression and Capture group — the pattern validating the value and the part to be extracted.
• Required — whether the value is needed for a line to count as recognised.

Kinds of mapping

Identifier — a unique product identifier. It needs Entity and Field:

Field	Meaning
Product.productNumber	the internal product number
Product.manufacturerNumber	the manufacturer’s number
Product.ean	the EAN code
Product.translations.name	the product name

Products found by number, manufacturer number or EAN get the status Recognized. Products found by name get Ambiguous, because a name is not unique.

Caution

Searching by name on a large catalogue is expensive. Use it only when the shop runs Elasticsearch; otherwise analysing a document can take a very long time.

Stock — a mandatory mapping reading the quantity off the invoice. It needs a Change type:

• Add — a delivery increases stock,
• Subtract — a return or correction decreases it,
• Overwrite — sets stock to the value read.

Supplier identifier — the supplier’s own identifier. It allows the same product to be bought from several suppliers, each using a different number.

Value — a value that must be recognised for a row to count as complete. It raises the accuracy of recognising line rows.

Ordinal number — item numbering. If the table has it, mapping it is worth the effort: it improves row-boundary detection.

Product name, Purchase price, Batch code, Batch quantity — additional line data.

Expiry date — the expiry date. It lands on the batch created at receipt, so issuing by expiry only works once it is mapped. Recognised formats are Y-m-d, d.m.Y, d-m-Y, d/m/Y and their two-digit year variants.

Page-layout markers

Three types work on the whole row rather than a single column. They use only Label, Regular expression and Priority:

Page marker — flags a page-header row, so the module knows a new page started. It fixes the most common multi-page reading defect: rows from page two being merged into the last item of page one.

Column header marker — flags a row repeating the column headers on every page. The row itself is skipped, but no following rows are.

Item starter — flags a row that starts a new line item even when the ordinal-number pattern did not match. Useful when items are recognisable by structure while the numbering column is unreliable.

The minimum set

A struct needs at least one Identifier or Supplier identifier and a Stock. Without an identifier there is no telling which product it is; without a quantity there is nothing to import.