Docs · Concepts

Investigations

A runbook filed against a Check — the steps somebody would take at 07:00, written down once.

A Check tells you that Store 014 is short by 312. An investigation is what somebody does next, written down so they do not have to remember it.

It is the investigation that starts where a reconciliation stops: a runbook filed against a Check, with steps that query the systems, ask questions of the answers, and end on a conclusion.

#Seven kinds of step

Each step is named for the question this step asks, not for the table it reads. What the tills closed with is a step name. SELECT FROM POS_CLOSE is not.

#How a step knows which row it is about

Three mechanisms, and you will use all of them.

Row tokens. Once a row is chosen, its values are available as tokens — one per key, and one per carried column. Paste one into any field of the query a step runs: a WHERE clause, a URL, a header, a bind value. Mosaic puts the row's value there before the query goes out, quoted and typed for the engine.

Until a row is chosen, every step runs unfiltered.

Fill this query's own names. To use a query written for another system without rewriting it: name what the query already asks for on the left, and the row value that fills it on the right. There is an Automap button, and it only takes exact matches once case and punctuation are ignored — a near miss would bind the wrong column, which is worse than not binding it.

Only when. A step can be guarded so it runs on one side of an earlier question. Left on Always, it runs every time.

#Saying what a good answer looks like

A step can declare what a pass looks like: how many rows, or a value, read as text, a number, a date or yes/no — then one of two dozen operators, worded the way a person would say them: is there, is not there, is empty, contains, is greater than, is on or after, and so on.

And then the sentence that turns a result into a conclusion, under What the answer means:

"No rows here means it never reached the staging table."

That is the line that makes it a runbook rather than a saved query.

#Asking an agent

An Ask an agent step hands the row to an agent you defined under Agents — see Agents. Fill its inputs from the row the same way you fill a query's names; it is also told the whole row, so it knows what the comparison saw.

Its answer is a finding: a verdict (Explained, Not explained, Inconclusive), the cause in a few words, and a short summary, with every query it ran listed underneath. The cause is the step's value, so a question or a switch after it can route on it, and it is what lands in the results column.

An agent is a model reading your systems for as long as it needs, so it does not run everywhere a query would:

• When somebody runs the investigation in Mosaic, it runs.
• In the automatic pass after a check run, it is left for a person — unless the step has Also run after each check run switched on. On, it runs once for every row the pass visits.
• From a published page, it never runs. A reader with a link would otherwise be spending your model on your systems.

A step that was left says so: Left for a person.

#Conclusions

A conclusion step ends the investigation with one of three outcomes:

• Answered — this is the cause
• Ruled out — look elsewhere
• Inconclusive — cannot tell from here

plus What to take away.

#Running one

Press Investigate. Steps run in order, guards decide which ones apply, and you end on a conclusion or run out of steps.

A step can run a whole Check — any Check in this workspace, including this one. It runs with the row's values available as tokens, and its own investigations are not run, so there is no recursion to worry about. A sub-check's answer opens as its own tab, capped, and says so: "A step brings back at most 200 rows. Every disagreement is among them, so the rows left out all agreed."

Executions are recorded — when they started, how many steps passed and failed, and how long they took. A single step run on its own is not recorded: its answer lives only as long as the tab showing it.

#Running automatically

An investigation can be set to Run on every disagreeing row. It then runs as part of the Check, for the rows that disagree, and writes what it ended on into a column at the end of the table.

Read the cost before turning it on: every disagreeing row costs one pass of this runbook against the systems its steps name, and it also happens on a schedule. There is a cap — 50 rows per run by default — and a Check can set its own limits on rows and seconds.

Real disagreements are investigated first, then rows a system could not be read for.

#Letting published readers investigate

Two independent switches, and it is worth being clear about the second.

Publishing a Check lets its figures be read. Readers may investigate is a different thing, and it is off until you say otherwise:

Anybody with the link can run these investigations against the systems their steps name, and read the figures of any check a step runs — including checks that are not themselves published.

That is why it is an admin's decision. It lets a reader with no account cause queries to run against a production system.

A Drilldown is a different thing: one query that shows more about any row, matching or not, when somebody presses its button. It asks what is this row?, where an investigation asks why does it disagree? See Drilldowns. The column an investigation adds to the results, when a step runs a whole check for each row, is also headed Drilldown: it opens that check's rows for the row. Opened full size, those rows download to Excel as they are on screen, under their filters, search and sort, with figures as numbers.