Skip to content

Mestra Topos

Mappings

A mapping turns the rows of a keyed table into items in your organisation’s model. Your model is the set of things Mestra knows about: places, screens and the items that belong to them. A decision can read the items that belong to a screen’s place, so a mapping is how your table data reaches a decision. See The decision language.

What a mapping says

A mapping is a small document that reads one keyed table.

Field Meaning
dataset The table it reads. It must keep the latest state of each row, so it must be a keyed table.
type The type of item it makes, such as menu_item. 1 to 64 lower-case letters and underscores. A type that another Mestra system fills can’t be used.
name_column The column that gives each item its name.
attrs Which columns become which attributes, as {"price_minor": "price"}. An attribute name uses lower-case letters, digits and underscores.
links How an item links to another. Each link has rel (the relation, such as at), to_type (the type to link to), match_attr (the attribute to look at on that type) and column (the column holding the value to look for).

Mestra saves a mapping whole or not at all, and lists every problem with a path such as attrs.price_minor or links[0].rel.

How rows become items

  • Each live row becomes one item. The item’s name comes from the name_column. Its attributes come from attrs.
  • When a row changes, its item changes. When a row goes (a Replace everything run left it out), its item is archived. If the row comes back, so does the item.
  • A link looks up the value of its column among the active items of to_type, by their match_attr. Exactly one match makes the link. None, or more than one, makes no link. Mestra never guesses between two.
  • Deleting a mapping forgets it. The items it made stay in your model, with their links, and stop updating.
  • Mapping happens as data lands. If it fails because of the data, the payload is kept with a routing_failed error that names the mapping, and nothing is written to the table.

The Point of sale mapping

Adding the Point of sale connector adds a mapping called Menu items.

Reads Menu items
Makes menu_item items, named by name
Attributes item_id, location, price_minor (from price), currency, category, available, stock
Link at the place whose code equals the item’s location

So an item at queen-st is linked to the place whose code is queen-st. A screen at that place can read it. Money stays whole cents: the attribute is price_minor, and money(price_minor, currency) in a decision writes it as $4.50.

See what is downstream

A connector’s page shows Downstream: its tables, the mappings that read them, the model types those fill, and the decisions that read them. Use it to see what changes when a connector changes.

Make and change a mapping

Mappings have their own page, Mappings, in the Topos menu (the Data page links to it too). Everyone in the organisation can see the mappings; an owner makes and changes them.

  1. Select New mapping.
  2. Give it a Mapping name. The key fills in from the name.
  3. Choose the Table it reads (only keyed tables are offered), the Item type, and the Name column.
  4. Under Attributes, select Add an attribute for each one: the attribute’s name and the column that fills it.
  5. Under Links, select Add a link for each one: the relation, the type it links to, the attribute to match on that type, and the column holding the value to look for.
  6. Select Save mapping. If something is wrong, the message shows beside the field.

Once a mapping is saved, its table and item type are fixed. To read another table or make another type, make a new mapping.

From a mapping’s menu, or its page:

  • Rebuild maps every live row of the table again, and says how many rows it mapped.
  • Delete forgets the mapping. The items it made stay in your model, with their links, and stop updating.

The Point of sale connector adds its own mapping, which you can open and change like any other.