Outputs covers the fixed set of documents Ason generates automatically when a period closes or finalizes (payslip, accounting document, Swissdec declarations). Reports are different: a configurable catalog of report definitions you run on demand, filtered to whichever employees or company data you need, in whichever format you need.
The report catalog
Every payroll has a catalog of available reports, defined by its regulations. List it with clusterSetName to scope to a particular set - the built-in frontend always requests the AvailableReports cluster on its company-level "Reports" page; use a different cluster name if your own integration needs a different subset.
Each entry returned is a ReportSet with a name, displayName, description, parameters, and availableOutputs - the file formats it can be generated in (Pdf, Excel, Word, Csv, Xml). Its id is the reportId you need for the next step.
Running a report
There are two ways to run a report, both taking the same body - a payrollId, a language, plus a parameters map specific to that report:
- Build (
POST .../reports/{reportId}/build) - runs the report and returns the result as structured data, ready to render yourself. The frontend re-runsbuildafter every parameter change, since one parameter's value can change what other parameters look like - e.g. deriving a dropdown's options, or hiding a field. - Generate (
POST .../reports/{reportId}/generate?format=Pdf) - runs the report and returns a ready-made file in the format you choose fromavailableOutputs.
Use build instead of generate when you want to display the numbers in your own UI rather than hand the employee or admin a finished file.
How the frontend surfaces this
Reports show up under Company → Reports as a plain list, one row per report with a "Generate" button. A report only opens a parameter dialog first if it actually has visible parameters (some are deliberately hidden via an input.hidden attribute) or more than one output format - otherwise "Generate" produces the file immediately, using each parameter's default value (date parameters default to today).
Parameter inputs are inferred from a parameter's valueType and attributes: booleans become a checkbox, dates a date picker, an input.listSelection attribute becomes a multi-select, everything else a plain text or number field. The report's content language is always the logged-in user's own language, not something picked per report. The generated file downloads straight to the browser, named <report name>_<date>.<extension> - the date comes from the report's own date parameter if it has one, otherwise today's date.
Ad-hoc queries
For cases where even the report catalog is too rigid, GET /api/tenants/{tenantId}/queries (ExecuteReportQuery) runs a named query method (methodName) with arbitrary key/value parameters and returns a generic DataTable (columns + rows). This is an API-only capability - the built-in frontend doesn't use it. Reach for this only when no existing report or endpoint already returns what you need.
FAQ
Should I use build or generate?
build if you want to render the numbers yourself; generate if you want a ready-made file (Pdf, Excel, Word, Csv, Xml).
How is a Report different from an Output?
Outputs are the fixed set of documents generated automatically on close/finalise. Reports are a configurable catalog you run on demand.
What if no report fits what I need?
Fall back to the ad-hoc query endpoint (GET /tenants/{tenantId}/queries) described above.
What does an individual report actually show me?
Check its description field in the report catalog, and its parameter template (GET .../reports/template) for what it expects as input - the exact content depends on the report definition itself.
Can I get additional reports enabled?
Not as a self-service toggle - the catalog comes from your assigned regulations. Additional or custom reports are handled the same way as extra regulation logic: get in touch.
Can existing reports be customized?
No - treat report definitions are fixed.
API Endpoints
| What | Call |
|---|---|
| List available reports | GET /tenants/{tenantId}/payrolls/{payrollId}/reports |
| Get a report's parameter template | GET /tenants/{tenantId}/payrolls/{payrollId}/reports/template |
| Build a report (structured data) | POST /tenants/{tenantId}/payrolls/{payrollId}/reports/{reportId}/build |
| Generate a report (file) | POST /tenants/{tenantId}/payrolls/{payrollId}/reports/{reportId}/generate |
| Execute an ad-hoc report query | GET /tenants/{tenantId}/queries |