Loading

Panes, Schedules & the Dataset API

Put a saved query on a record screen, deliver it on a clock, or expose it as a read-only API resource.

Queries on a Record Screen

A query pane shows the results of a saved report on a record's own screen, filtered to that record: a supplier's open orders on the supplier, a tenant's repairs on the tenancy. Panes are set up as rows in a datastore and appear automatically on every record screen of the chosen datastore.

Where to find it

Architect Panel → Data:

  • Datastores — the Query Panes datastore, one row per pane
  • Report Builder — where the report behind a pane is built

Before you start: what a pane needs

Two things are required of the saved report, and the second cannot yet be done in the Report Builder:

  1. It must list records (Show set to Records). A pane showing totals is refused: "A pane can only show a query that lists records."
  2. It must ask for the record: it needs a record parameter, used in a condition, so the pane can fill in the current record. The Report Builder cannot add parameters, and re-saving a report there removes any that were added. Adding one means editing the report's Specification on its BI Saved Queries record, which is a job for a developer or someone comfortable editing that kind of definition.

Without the parameter the pane shows "The saved query behind this pane does not have a 'recordid' parameter for the record to fill in." Plan for that step before promising a pane.

Setting up a pane

  1. Make sure your security group has permissions on the Query Panes datastore; it ships with none, so even an architect is refused until it is granted.
  2. Add a row to Query Panes:
    • Saved Query: the report.
    • Record Screen: the datastore whose record screens show the pane (shown by its system name).
    • Title: blank uses the report's name.
    • Parameter To Bind: the report's record parameter (recordID unless changed).
    • Visible To: security group numbers, comma-separated, to limit who sees it.
    • Pane Order (50 by default) and Rows Per Page (10 by default).
    • Enabled: on.
  3. Open a record of that datastore and check the pane.

There is no separate layout step: an enabled pane appears on every record screen of its datastore for the people it is visible to.

What viewers see

The report's rows for this record, a page at a time, run with the viewer's own permissions. Two people opening the same record may see different rows.

What goes wrong and how to tell

  • "A pane can only show a query that lists records.": switch the report to Records.
  • The 'recordid' parameter message: the report has no record parameter, or it was removed by re-saving in the Report Builder.
  • The Query Panes datastore refuses you: grant your group permissions on it.
  • The pane is missing: Enabled is off, the Record Screen is a different datastore, or Visible To excludes you.

Worked example

A purchasing team wants each supplier's open orders on the supplier screen. An analyst builds "Open orders" as a Records report on Orders, and a developer adds a record parameter matched to the order's Supplier field. The architect adds a Query Panes row with that report, Record Screen set to the suppliers datastore, Title "Open orders", Rows Per Page 10, and Enabled on. Every supplier record now shows its own open orders. The team agrees not to re-save the report in the Report Builder, because that would remove the parameter.

Recommendations

  • Keep pane reports short: a few columns and a sensible sort.
  • Label pane reports clearly so nobody re-saves them in the Report Builder.
  • Use Visible To for panes only some roles need.
  • Grant Query Panes permissions only to architects.

Scheduled Delivery

A saved report can be e-mailed automatically every day, week or month, as a CSV file or a spreadsheet. The people who need the figures get them without opening the platform, and the report always reflects the data at the moment it runs.

Where to find it

Architect Panel → Data:

  • Report Builder — Open… then "Send on a schedule…" on a saved report

Admin Panel → Reporting:

  • Report Builder — the same screen, once granted

Before the first schedule: switch the tasks on

Scheduled delivery is carried out by two scheduled tasks, and both ship switched off. An architect must enable both in Tasks:

  • Scheduled Query Delivery, which decides which schedules are due and queues them.
  • Background Jobs, which runs the queued work and sends the e-mail.

With only the first enabled, schedules are queued but nothing is ever sent. The installation also needs a working outgoing mail account. See E-mail Accounts.

Setting up a schedule

  1. Open the report in the Report Builder. If it is not saved yet, save it: "A schedule needs a saved query."
  2. In the Open… list, choose Send on a schedule…. The dialog "Send this query on a schedule" opens.
  3. Give the schedule a Name.
  4. In Send to, enter the e-mail addresses.
  5. Under When, choose Every day, Every week or Every month; for a weekly schedule choose the day after on; set the time after at (07:00 unless changed); and choose CSV or Spreadsheet after as.
  6. Tick Switched on and save.

Each saved report has one schedule. To send it to different people at different times, save a copy of the report and schedule that.

It runs as you

The dialog says so plainly: the schedule runs with your permissions, not the recipients'. If your access changes, what arrives changes with it, and if your account is disabled or leaves every security group, the schedule fails. Recipients receive whatever you could see, so check the report before sending it outside your own team.

What is sent

The report's data as a file, not a chart. A report saved with a Report period sends the same fixed dates every time; see Report Periods. Delivery is by e-mail only.

What goes wrong and how to tell

Reopen the schedule to see its last run: a failure is shown with its reason.

  • Nothing arrives and there is no last run: one or both tasks are switched off.
  • "A schedule that is switched on needs at least one valid e-mail address."
  • "The person this schedule runs as no longer has an account", or has been disabled, or is in no security groups: the owner's account changed. Recreate the schedule as somebody current.
  • "There is no mail account to send from.": set up an outgoing mail account.
  • "Spreadsheet export is not available on this system.": choose CSV.
  • "The saved query this schedule runs is no longer shared with its owner.": restore the report's visibility.

Worked example

An operations manager saves "Overdue repairs by contractor" and chooses Send on a schedule…. They name it "Monday overdue repairs", send it to the three contract managers, every week on Monday at 07:00 as a spreadsheet, and tick Switched on. The architect enables Scheduled Query Delivery and Background Jobs. The first e-mail arrives the following Monday morning.

Recommendations

  • Enable both tasks and test with a schedule to yourself first.
  • Own schedules from a stable account, not a temporary member of staff.
  • Do not save rolling reports with a fixed period.
  • Send to groups' shared addresses where possible, so leavers are not left on the list.

The Dataset API

A saved report can be published as a read-only API resource, so another system, a spreadsheet or a reporting tool can fetch its results with an API key. Publishing is a deliberate administrative step: saved reports are private working documents until somebody turns this on.

Where to find it

Architect Panel → Data:

  • Report Builder — where the report is built and saved
  • Datastores — the BI Saved Queries datastore, where a saved report is published to the API

How it fits together

  • The report is a saved query from the Report Builder. Each has a key, generated automatically when it is saved, which identifies it to the API.
  • Publishing is a switch on the saved query's record: Published to the API. There is no publish button in the Report Builder itself.
  • The API key must be allowed to read saved queries, with its Saved query access (BI) setting. That is a ceiling, not a grant: every request is still checked against the account the key belongs to, so the key only ever sees rows and fields that account could see.

Publishing a report

  1. Build and save the report in the Report Builder, and check its results.
  2. Open the BI Saved Queries datastore, find the report by name, and turn on Published to the API. The other system will need the report's key, shown as Datasetkey on this record.
  3. On the API key the other system will use, turn on Saved query access (BI). See API.
  4. The other system requests the dataset from the platform's API, naming the dataset scope and the report's key. A request for the list of datasets returns those the key may read.

What the caller gets

The report's results, as data, run at the moment of the request with the key owner's permissions. Charts are not part of the response. A report saved with a Report period returns the same fixed dates every time.

Changing a published report

Editing and re-saving the report in the Report Builder changes what the API returns from the next request, because the key stays the same. If another system depends on the exact columns, treat a change as a change to an interface: build the changed version as a new saved report, publish that, move the caller to its key, then unpublish the old one.

What goes wrong and how to tell

  • "This API key is not allowed to read saved queries.": turn on Saved query access (BI) for the key.
  • "That dataset is not published.": turn on Published to the API for the report.
  • "That dataset is not available to this key.": the key's account cannot see that saved query; check who it is shared with.
  • Fewer rows than in the Report Builder: the key's account has narrower permissions than yours. That is the safeguard working.

Worked example

A finance team wants weekly income by fund in its own spreadsheet. The architect saves "Income by fund" in the Report Builder, turns on Published to the API on its BI Saved Queries record, and creates an API key for a reporting account that can read the income datastore, with Saved query access (BI) on. The spreadsheet's data connection calls the API with that key and the report's key. When the team later asks for an extra column, the architect publishes a new version under a new key and switches the spreadsheet over.

Recommendations

  • Use a dedicated account for API keys, with only the permissions the report needs.
  • Publish only what an external system genuinely needs.
  • Treat published reports as interfaces; change them by publishing a new one.
  • Unpublish reports nobody calls any more.