Docs · Connecting to data

Business Locations

The estate — every place the business operates, how they nest, what is known about each — kept by hand, imported, or read from the system that owns it.

Business Locations is the estate as Mosaic knows it:

The places this business operates, how they nest, and which system does each job for each of them. Store codes in a check resolve against this — so a difference can be counted by region rather than only by shop.

There is one per workspace. Viewers read it; changing it is an administrator's. It has four parts, listed in its sidebar: Organization Hierarchy, Locations, Import and Sync.

#What uses it

Once the estate is here, the rest of Mosaic reads it rather than keeping its own lists:

• Checks: store codes in a result resolve against it, so a difference can be counted by region.
• Systems: a system says which places it runs at.
• Collections: a data source's hosts can be a property of the places, read again at every run.
• Pick lists: a parameter offers places as a tree, or chooses them by a query.
• Monitors and the Places from Business Locations workflow node: which stores to check, and their servers' addresses.

#Organization Hierarchy

Levels are the org chart, top down: Area, then Country, then Store, named as your business names them. Each has a prefix it is written with, so a place's path in a file reads AREA:EU>COUNTRY:FR>STORE:S014. A level can be marked as the one systems are assigned at, and can also be a type.

Store types are what kind of place each one is: flagship, outlet, franchise. They are kept apart from the hierarchy, because a franchise can sit in any region.

Properties are anything else the estate keeps about a place: the opening date, the fascia, the tax region, the hostname of its server. Each has a key, a label, and a type (text, a number, a date, yes or no), so it is a value rather than a string, and a file can carry a column for it.

#Locations

The places themselves, as a tree. Each has a Code (the join key: what a query returns and a check matches on, unique across the estate), a Name, what it sits under, its level, its type, its properties, and whether it is open or closed.

A place that closes is switched off rather than deleted, so last quarter still reads. Closed places are not offered when choosing where to look tonight. Show closed puts them back in the tree.

Systems here sets which system does each job, its role, for the place: the POS, the ERP, the webshop. A place inherits what is set above it unless it sets its own, and None stops what is above from reaching it.

#Import

A spreadsheet or CSV, read into a preview before anything changes. Templates and exports offers a template built from your hierarchy (one example place per rung, a column per property and per role), a worked example for an invented retailer, and an export of what is already here, in Excel or CSV.

An import either merges with the estate or replaces it. Replacing makes the estate exactly what the file lists, and places the file leaves out are removed. Either way, the preview says what would be added and updated, lists the lines that could not be read, and names any problem the estate would then have. Nothing is kept until you save.

#Sync

The estate can be read from the system that already owns it instead of kept by hand. Under Where it comes from, choose Read from a data source, any source Mosaic can already connect to (a query, an API, a file), and the Sync part opens on what to read from it.

A refresh replaces every location. Your levels, types and properties are kept — they are your model of the business, not the source's.

#Which column is which

The place: which columns hold its Code, Name, Parent code, Level name, Type name, and whether it is Open or closed: open or closed, active or inactive, yes or no, or a closing date. Match columns fills them in from the column names, for you to check.

Levels: a flat list of stores, one row each with its country and region beside it, builds its own ladder. Tick the columns that are levels, top first, and each of their values becomes a place, with every row going inside the innermost one. A parent code, where a row has one, wins. Levels and types the rows name are added; none is ever taken away.

Properties: tick the columns to keep on each place. Each becomes a property, read on every refresh.

Systems: a column naming the system each place runs, matched to your systems by name.

#Linked sources

More about each place can come from another source, joined to the main one by one value both hold, most often a store code. Link a source asks for the source, the value on the places, and the same value in this source, suggests the pair, and says which columns the link brings and which it leaves because the places already have them.

What a link does:

• Every place is kept, whether it finds a partner or not. The ones that match gain the source's columns, to map as you map the main source's.
• Values are compared as text, ignoring case and spaces at either end.
• A column a place already has is never overwritten. Rename it in the linked source's query to read it too.
• A value held twice in the linked source is read from its first row.
• A link may join on a column an earlier link brought.

After a refresh, each link says how many places it matched, with an amber note when it matched only some. Each has a switch: off, the link and its mapping are kept, but a refresh does not read it, so a source that is down cannot hold the refresh up.

A source that fails keeps the estate as it was, and the error names it.

#Refresh automatically

Refresh from source reads it now. Refresh automatically does it on its own: every hour, every 4 or 12 hours, or every day at an hour of your choosing, in the workspace's time zone. It says when it will refresh next.

A refresh that fails keeps the locations as they were, says why on the Sync part, and still books the next one.

#Choosing places by what they are

A place can be chosen by name: Italy, these four stores. Some questions are not a branch of the tree, though. Every outlet in France is a property of the stores, and picked by hand it is forty ticks that are out of date the day a forty-first outlet opens.

So wherever places are chosen (a pick list's places, a value of a parameter bound to Business Locations, a Live Hosts monitor, the Places workflow node) they can be written as a place query instead:

$Fascia = Outlet AND $Country = France

The query is kept as a query, and each run reads the estate as it is that day.

AND is read before OR, as in SQL, and there are no brackets. A query that needs them is better written as two values of the list, which is an OR anyway. Values are compared ignoring case; put one in quotes when it holds a word like and.

A query can name a declared property by its key or its label, a rung of the hierarchy, a role, the store type, and each place's own level, name and code. A declared property wins where a name is both.

!= keeps to the levels that carry the field. Not an outlet read over every place would match every country and region too, since none of them carries a fascia, and a country chosen means all of its stores, outlets included: the opposite of what was asked. So $Fascia != Outlet means the stores whose fascia is something else, blanks among them.

The box suggests names and values as you type, draws =, !=, AND and OR apart from what you typed, counts the stores a query keeps, and says why when it keeps none. A run names an unknown property or level, in whichever condition it is.