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. Discovery and queries 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
Section titled “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
Section titled “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
Section titled “Asking for the catalogue first”The assistant starts with reporting.catalog(), which lists every report without reading report data. It then calls reporting.describe({ reportType }) for the selected report’s complete fields and options. Connection rate limits still apply. These are read-only calls. Together they provide:
- The id to run it by, and its category — sales, bills of materials, manufacturing, or inventory.
- A plain-English title, description and grain — what one row of that report actually is (“one material per period and location”, “one completed work order”).
- Which basis it can count on — what left the store (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.
- Whether it takes a period at all. The three On hand reports, in the inventory category, value the stock you hold right now, so an assistant runs them without one.
- The note the report page shows above its table, when it has one. On the On hand reports it says what every value leaves out (tax, units reserved or held as safety stock, work in progress, which is counted separately), and a good assistant passes it on with any value it quotes.
Each catalog or selected detail fits the ordinary response limits when returned on its own. Combining many results can still shorten a response. The older reporting.list() remains available with its existing full-list format, which can be shortened when returned whole.
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
Section titled “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 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
Section titled “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 store’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 can split table rows by day, week or month. “None” covers the whole period. The summary reports and the three On hand reports always stay ungrouped, even if another bucket is sent. The selected detail distinguishes accepted options from effective grouping.
- 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
Section titled “Filters, search and sorting”The selected detail lists each field’s accepted operators and enum values. queryFilterable describes API filter acceptance on the selected basis; the older filterable flag describes what the app’s filter menu offers. An API can also filter some hidden IDs and summary figures. A report can be 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.
Enum filters take a nonempty list of allowed values, ranges take a pair of numbers or calendar days, and boolean filters take true or false. Empty-value checks need no value. The detail also includes the query limits: at most 20 filters, 50 values in a list and 50 location IDs. These limits share a total query budget, so two lists that each fit their own limit may still be too large together.
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
Section titled “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.
Caveats an assistant must pass on
Section titled “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 BOM, 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
Section titled “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
Section titled “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.