Operating groups & saved views
A group is a named set of records you define — Summer range, Made in Leeds, Metals — and it carries no behaviour at all. A connected assistant can read your groups and, with write access, create them and move records in and out. A saved view remembers how a list is set up. The assistant can inspect it and read a current page of matching record IDs; see the end of this page.
On this page
Section titled “On this page”- What it takes
- The three kinds of group
- Reading groups
- Creating and renaming a group
- Changing who is in a group
- Deleting a group
- Saved views
What it takes
Section titled “What it takes”Reading groups needs nothing beyond a connection. Creating, renaming, deleting a group and changing its membership need write access — an API key created with read & write scope, or a web-chat connection granted read & write when it was linked. No plan gate: groups are available on every plan.
The three kinds of group
Section titled “The three kinds of group”A group has a kind, and it never changes: a group of finished goods, of assembly BOMs, or of materials. A group of one kind can only ever hold records of that kind, so the assistant has to say which kind it means when it creates one. Names are unique within a kind, so the same name can exist once in each.
A record can be in any number of groups at once.
Reading groups
Section titled “Reading groups”“Which groups do I have for materials, and how many materials are in each?”
The assistant lists groups with their member counts, optionally narrowed to one kind or to a name search. Listing gives counts, not members; to get the members it opens the one group, and gets back the ids of everything in it.
Creating and renaming a group
Section titled “Creating and renaming a group”A new group is created empty, with a name and an optional description; members are added afterwards. A name another group of the same kind already uses — in any casing — is refused and the existing group is named, so the right move is to reuse that one rather than retry.
Renaming and re-describing work the same way. What a group holds cannot be changed: there is no converting a group of materials into a group of finished goods. Create the other kind and move the members.
Changing who is in a group
Section titled “Changing who is in a group”Three ways, and the difference matters:
- Replace the membership with exactly the records you name. Anything you leave out is removed. Sending an empty list empties the group. Members that stay keep the date they joined.
- Add records without disturbing the ones already there. Re-adding a current member does nothing, so this is the safe one to repeat.
- Remove records. Also repeatable, and it works even for a record that has since been deleted — so a group can always be tidied up.
Deleting a group
Section titled “Deleting a group”Deleting a group removes the group and its membership rows. The records themselves are untouched — a group is a label, never an owner — and a delete is never blocked.
Saved views
Section titled “Saved views”A saved view remembers columns, filters, search, sorting, page size and, where offered, locations. Ask:
“Find my materials view for discontinued items, explain its filters, then show the first page of matching IDs.”
The assistant can:
- List views for finished goods, assembly BOMs, materials, work orders or tasks. Built-in views appear first, then your saved views. It can read up to 50 summaries at a time, with a total and paging details. Two views with the same name remain separate choices; it uses the returned ID after you identify the right one.
- Inspect one exact view, including its ordered columns and filters, saved search, sorting, page size and locations. Task views support this inspection too. Extra saved options, if present, are returned as text for inspection; they do not change which records the assistant reads.
- Read one page of matching IDs for finished goods, assembly BOMs, materials (including virtual materials) or work orders, in the list’s order. It receives a total, whether another page exists, the chosen view and the effective sorting and locations. This does not include each record’s full details or stock figures.
For scripts, the calls are savedViews.list, savedViews.get and savedViews.members. For example, inside run:
const views = await app.savedViews.list({ viewType: "BOM", limit: 25 });const setup = await app.savedViews.get({ viewType: "BOM", viewId: "canonical-all" });const page = await app.savedViews.members({ viewType: "BOM", page: 1, pageSize: 25 });return { views, setup, page };The type names are BOM (finished goods), ASSEMBLY (assembly BOMs), RAW (materials), WORK_ORDER (work orders) and TODO (tasks). Tasks support list and inspection only; report views are not supported by these calls.
For matching IDs, omitting the view ID chooses the store’s current default, or built-in All when none is set. Giving an ID selects exactly that view: a deleted ID or one from a different kind of list is refused, even if a stale link in the app would open another view. Page numbers start at 1 and can reach 10,000. Page sizes are 10, 25, 50 or 100; omitting the size uses the saved one. These calls do not accept replacement filters, search terms, sorting or locations.
Locations have different effects. On finished goods, assembly BOMs and materials, selected locations affect stock figures and sorting by them, rather than removing records. On work orders, they narrow the matching records and also respect any saved location filter.
It reads the setup the app can load. Older saved settings may already have been simplified when read, and an incompatible saved view may be omitted. Inspection cannot reconstruct the original stored setup. An unfamiliar filter may be inspectable while matching IDs are refused because its meaning is unsupported. Failed reads stay failures; they are not empty matches. Reads never repair a view.
It cannot create, edit, rename, delete or switch your view in the app. Make those changes in the view switcher. These are ordinary reads: they need no write access or write approval, and the connection’s normal access and rate limits still apply.
See also
Section titled “See also”- Groups — creating and using groups in the app.
- Saved views — what a view remembers and where views live.
- What the assistant can read — the rest of the read surface.