Skip to main content

Reports

A report joins three things: a datasource, a published query, and a template. Publishing it pushes the definition to your agents, which can then run it on demand or on a schedule.

Creating a report​

Reporting → Reports → New, then:

  1. Name and slug. The slug is how the CLI and API address the report (monthly-sales), so pick something stable.
  2. Datasource and query. Only published queries are selectable.
  3. Template. Start from a report template in the gallery, or design your own.
  4. Output formats. Excel, PDF, or both from the same definition.

Templates for reports​

Reports use the same template engine and visual designer as Render, so anything you can build for an invoice you can build for a report.

The component that matters most here is the grid — a spreadsheet-style surface with real cells, merges, per-cell formats, and borders. It exists because report layouts are usually grid layouts, and describing them as flowing blocks fights the format. In a grid you place a data table so that its columns pin to grid columns and its rows push subsequent content down, which is how a banded report is supposed to behave.

For Excel output, grid cells map to real worksheet cells, so the result is a spreadsheet people can filter and pivot rather than a picture of one.

Mapping data onto the template​

The report builder shows your query's discovered columns on one side and the template's variables and table columns on the other.

  • Scalar variables take a single value — a parameter, an aggregate, or a computed expression.
  • Table columns bind to result set columns and repeat per row.
  • Calculated variables are expressions over other variables, evaluated at render time.

Sample data​

A report keeps a cached sample of its query results so the designer can show a realistic preview without hitting the database on every keystroke. Refresh sample data re-runs the query through the agent and updates it.

Refresh the sample after changing the query, or the designer will keep showing you the old shape.

Test runs​

Test run executes the report end to end against real data and produces a real document — but skips distribution. Use it as the last check before publishing.

Publishing and versions​

Publishing pushes the report to every agent that serves its datasource. Until then, edits are a draft and running agents are unaffected.

  • Versions lists published versions with who published them and when.
  • Revert restores an earlier version as the current draft.

Running a report​

Four ways, all producing the same run record:

  • Run now in the webapp
  • A schedule on the agent — see Schedules and jobs
  • The CLI: rynko-run --report monthly-sales --params '{"region":"APAC"}'
  • The API: POST /api/reporting/reports/:id/run

Access control​

Reports are scoped to a project and environment like everything else in Rynko. Beyond that, grants let you give named users access to run a specific report without giving them the ability to edit it — the right shape for handing a monthly report to the people who consume it.

Run keys for external systems​

When another system needs to trigger a report — a WMS, an ERP job, a shell script on a server that has no Rynko login — mint a run key. A run key is an API key scoped to an explicit list of reports and nothing else.

Reporting → WMS run access manages which reports a given key may run. The key can trigger a run, poll its status, and download the result; it cannot list your other reports, read your queries, or change anything.