Skip to main content

Getting Started with Reporting

This walks through a complete first report: register an agent, connect a database, write a query, bind it to a template, and run it.

You will need a database the agent can reach and a machine inside your network to run the agent on.

1. Register an agent​

In the webapp, go to Reporting → Agents → Register Agent. Give the agent a name that identifies where it runs (prod-erp-datacenter, not agent-1).

Rynko issues an API key. Copy it now — it is shown once.

2. Install the agent​

Docker is the quickest route:

docker run -d --name rynko-agent \
  -e RYNKO_API_KEY=your_agent_key \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/data:/app/data \
  ghcr.io/delivstat/rynko-reporting-agent:latest

For hosts without Docker, download the archive, extract it, and run ./start.sh (Linux) or start.bat (Windows). See Agents for both paths in full.

3. Configure a datasource​

Datasources are defined in two places, deliberately: the shape of the connection lives in the webapp, the credentials live only in config/agent.yaml on your machine.

In the webapp, go to Reporting → Datasources → New and create a datasource with the slug production-erp.

Then on the agent host, add the matching entry to config/agent.yaml:

datasources:
  production-erp:
    type: postgres          # oracle | postgres | mysql | mssql | file
    host: 10.0.2.100
    port: 5432
    database: erp
    user: report_reader
    password: ${PG_PASSWORD}
    pool:
      min: 1
      max: 5
      queryTimeout: 120000

The slug is the join between the two. Restart the agent, then click Test connection in the webapp — the agent runs the test locally and reports back pass or fail.

Use a read-only database user

The agent only ever issues SELECT. Give it a user that can do nothing else.

4. Discover the schema​

With the datasource connected, click Discover schema. The agent reads table and column metadata and sends the structure — names and types only, no row data — back to the control plane so the SQL editor can offer autocomplete.

5. Write a query​

Go to Reporting → Queries → New. Write SQL against the datasource:

SELECT
  region,
  product_line,
  SUM(net_amount)  AS revenue,
  COUNT(*)         AS order_count
FROM orders
WHERE order_date >= :date_from
  AND order_date <  :date_to
GROUP BY region, product_line
ORDER BY revenue DESC

Named parameters use :name. Declare each one in the Parameters panel with a type and, optionally, a default or a list of allowed values.

Click Test query to run it against the live datasource through the agent and see real rows. When it looks right, Publish it — only published versions are used by reports.

6. Build the report​

Go to Reporting → Reports → New:

  1. Name the report and pick the datasource and published query
  2. Choose a template — start from the report templates in the gallery, or design one in the template designer
  3. Map query columns onto template variables and table columns
  4. Pick output formats — Excel, PDF, or both

Click Test run to generate a document from real data without distributing it.

7. Publish and run​

Publish the report to push it to the agent. Then either:

  • Click Run now in the webapp
  • Add a schedule under Schedules (see Schedules and jobs)
  • Run it headlessly on the agent host:
rynko-run --report monthly-sales --params '{"date_from":"2026-09-01","date_to":"2026-10-01"}'

Every run appears in Reporting → Run History with its status, duration, row count, and a link to download the document.

Next steps​