Generate and download a report (API)

Turn a template and the data in your data sources into a report file, and download the file when it is ready.

Participants

Your institution. Your system that calls the Reporter API.
Reporter. Checks the template and the request, generates the report and serves the file.

You have a bearer token that Access Manager issues for Reporter.
You connected each data source that your template reads. See Connect a data source.

#	From	To	Message	Lerian API	What happens
1	Your institution	Reporter	Lerian API	`POST /v1/templates`	Upload the template as a multipart form with the `template` file, `outputFormat`, `description` and `category`.
2	Reporter	Reporter	Internal step		Reporter checks each data source, table and field that the template reads against the schema of the data source.
3	Reporter	Your institution	Response		Reporter returns the template with its `id`.
4	Your institution	Reporter	Lerian API	`POST /v1/reports`	Send `templateId` and `filters`. Add `parameters` when the template declares them, and an `X-Idempotency` key.
5	Reporter	Reporter	Internal step		Reporter checks the filters and the parameters, records the report and starts the generation.
6	Reporter	Your institution	Response		Reporter returns the report with its `id` and the status `Processing`.
7	Reporter	Reporter	Internal step		Reporter extracts the data from each data source. The report ends as `Finished`, `Partial` or `Error`. For `Finished` and `Partial`, Reporter renders the template and stores the file.
8	Your institution	Reporter	Lerian API	`GET /v1/reports/{id}`	Read the report.
9	Reporter	Your institution	Response		Reporter returns the report with its `status`.
10	Your institution	Reporter	Lerian API	`GET /v1/reports/{id}/download`	Download the file of a `Finished` report.
11	Reporter	Your institution	Response		Reporter returns the file with the content type of its format and the `X-Report-Status` header.

The outputFormat is html, pdf, csv, xml or txt. Write a pdf template in HTML. The description and the category are required.
Reporter refuses a template that reads a data source, table or field that does not exist. When Reporter cannot reach a data source, it creates the template and returns a warning.
A filter can only name a table that the template reads.
Reporter refuses a request without a required parameter that has no default value.
When you registered more than one institution in Reporter, send institution with an institution ID or with all.
For 30 seconds, a repeat with the same X-Idempotency key returns the first report, with the header X-Idempotency-Replayed: true.
Reporter refuses the download while the report is Processing, and when it is Partial or Error.

The report shows Finished, and the download returns the file with X-Report-Status: Finished.

Situation	What you see	What to do
The template reads a data source that does not exist	`400` with `RPT-0031`	Connect the data source, or correct its name in the template.
A filter names a table that the template does not read	`400` with `RPT-0076`	Filter one of the tables that the message lists.
The same request is still in progress	`409` with `RPT-0039`	List the reports of the template before you send the request again.
The request times out	No answer	The report can exist. List the reports of the template with `template_id` before you send the request again.
You download before the report is `Finished`	`422` with `RPT-0029`	Read the status, and download when it shows `Finished`.
The report ends as `Partial` or `Error`	`metadata` describes what failed	Read the cause, then request a new report.