Operating reports

A connected assistant can read your reports: it can list every report Assemblified can answer, and run one over a period you name. Both are read operations — no write access, no Enhanced plan, nothing to switch on.

This is the same engine the report pages in the app use, so a number an assistant quotes is the number the page would show for the same period.

On this page

• What it takes
• Asking for the catalogue first
• Running a report
• Periods, buckets and location scope
• Filters, search and sorting
• What comes back
• Caveats an assistant must pass on
• What it cannot do

What it takes

Nothing beyond a working connection. Reports are read-only, so a read-scope key or a read-only web-chat connection is enough. See API keys.

Asking for the catalogue first

The catalogue is the cheap call — it reads none of your data, it just lists what exists. For each report it names:

• The id to run it by, and its category — sales, bills of materials, or manufacturing.
• A plain-English title, description and grain — what one row of that report actually is (“one raw material per period and location”, “one completed work order”).
• Which basis it can count on — what left the shop (sold) or what was used up (consumed). A report that offers both accepts a choice; a report that offers one ignores it.
• Whether it has a location dimension at all — on a report that has none, naming locations changes nothing, and the catalogue says so up front.
• Its columns, which of them can be sorted or filtered, and the figures it reports beside the rows.
• How far back its history goes, and the maximum length of a period it will answer.

A capable assistant reads this before it runs anything, because it is how it picks the right report and knows which options that report accepts. If your assistant guesses a report name, it gets a clear “no such report” rather than an empty table.

Running a report

Running one takes the report id and a period, and returns a page of rows plus the figures across the top:

“Run the raw material demand report for August and tell me the ten biggest movers.”

“Which finished goods sold last quarter that I have no bill of materials for?”

“How much did each completed work order cost me in September?”

Periods, buckets and location scope

• The period is a pair of calendar days, start and end, both included, read in your store’s time zone. The assistant does not get to send a time zone — the shop’s own is used, so a period cannot be quietly shifted by an offset.
• A period longer than 366 days is refused, as is one that ends before it starts.
• Buckets split each row by time: none, day, week or month. “None” is one row per item for the whole period.
• Locations narrow the rows. Leaving them out means every location. For a report with no location dimension, naming locations changes nothing — which the catalogue tells the assistant in advance.

Filters, search and sorting

A report can be filtered on its own filterable columns, searched with its own free-text search, and sorted by any sortable column. Paging is by page number, 25, 50 or 100 rows at a time.

One behaviour worth knowing: a filter or sort naming a column the report no longer has is dropped and reported, not refused. The page still comes back, with a note saying which conditions were ignored — so if an assistant reuses an old query after a report changed, you get the data and the warning rather than an error.

What comes back

• Rows — one object per row, keyed by column.
• The totals — the same figures the report page shows in its strip across the top.
• Paging information, so the assistant can walk a long report.
• Notes, when there are any: which filters were dropped, how far back the data actually goes, and whether any figure in the answer is an estimate.

Note

A figure of “nothing” is not the same as zero. When a figure cannot be answered over the rows you asked for — an average over an empty period, say — it comes back as unanswerable rather than as 0. An assistant that reports “your average was zero” in that case is reading it wrong.

Caveats an assistant must pass on

Two are important enough that a good assistant repeats them to you rather than quietly rounding them off:

• Some answers are estimates. A period boundary that splits an order, or a historical row replayed against today’s recipe, makes a figure approximate. The answer says so; it should be reported as an estimate, not as an exact number.
• History has a floor. Each report’s data starts on a date. A period reaching further back is empty for a reason, and the answer carries that date. For the sales reports the floor is the copy of your Shopify orders — if that looks short, see Operating the reporting sync.

What it cannot do

• It cannot export a file. Export exists so a person gets a spreadsheet; an assistant pages through the rows instead.
• It cannot save a report view. Saved views are created in the app.
• It cannot change a report. The report catalogue is fixed; nothing here writes anything.

See also

• Reporting overview — what each data source is truthful about.
• The reports — every report, column by column.
• Operating the reporting sync — checking and refreshing the order history the sales reports read.