Forms

A form is a Manager-built UI that collects parameter values from a user before running a report. It's the workflow piece that wraps a report so a non-technical end user can produce one without ever opening the report editor.

If your report takes parameters like customerId and dateRange, a form is what asks the user "which customer?" and "between which dates?" - and what hands those values to the export engine.

When to build a form

A form is the right choice when:

• The report has more than one or two parameters.
• The caller is a human (not another system).
• Parameter values benefit from pickers, validation, or defaults that aren't in the URL.

If the report is always run programmatically (by a backend or a scheduled job), skip the form and pass parameter values directly via the export API.

What a form is, structurally

A form has:

• A title and an optional description.
• A list of fields, each bound to a parameter of one or more reports.
• A list of target reports - the reports it runs when submitted.
• Output options - what happens after submission (download a PDF, email a link, render an embed view).

Each field declares a type (string, number, date, date range, lookup, boolean, multi-select, ...), a label, optional help text, default value, and validation rules (required, min/max, regex).

A form can target multiple reports as long as their parameter names align. This is how you batch related exports - one submission generates an invoice PDF, a packing list, and a shipping label in one click.

Building a form

1. Go to Manager → Forms → New.
2. Pick the target report(s). The form builder reads each report's parameter declarations and auto-suggests fields for them.
3. Customize each field - label it in plain language, set a default, add help text. The default field type is inferred from the parameter type (Date parameter → date picker, etc.).
4. Configure output. The most common setting is "download PDF on submit", but you can also display the report inline as an embed, or send a download link to the submitter's email.
5. Publish.

A published form has its own URL. Share that URL with the people who'll use it; submission requires authentication (a workspace member, an invited user, or a signed link, depending on how you've shared the form).

Field types

The builder offers:

The Lookup field is the powerful one: it queries a data context to populate options. So if a form asks "Which customer?" it shows a typeahead over the actual list of customers, not a free-text input where users could mistype an ID.

Pre-filling and deep links

A form URL accepts query string parameters that pre-fill its fields. So you can produce a URL like:

https://app.goldenreports.dev/forms/invoice-export?customerId=cust_42

and the customer ID field is filled in for the user. Pre-filling is useful when an upstream system already knows part of the answer and wants to ask the user only for the rest.

Validation and submit

Submission runs the target report(s) with the field values mapped to parameters. The Manager:

1. Validates the form (required fields, type checks, custom rules).
2. Authorizes - the submitter must have run access to every target report, including all data sources behind them.
3. Calls the export API for each report in sequence.
4. Renders the configured output (single PDF download, ZIP of multiple PDFs, inline embed view, email confirmation).

If any check fails, the form re-renders with structured errors next to the offending fields.

Where forms live in the platform

Forms are workspace-scoped, versioned (publishing creates a new version while previous versions stay usable), and audited like reports. You manage them from Workspace → Forms in the Manager.

Best practices

• Don't recreate the report's parameter UI. The editor's preview already collects parameters - that's for authoring, not end users. Build a form when an end user needs a polished entry surface.
• Use Lookup fields aggressively. Free-text inputs that should be IDs are a recipe for "no rows returned" surprises. Bind to a data context and show the user real options.
• Group fields logically. The builder supports section headings. A form with 15 fields organized into "Customer", "Dates", and "Options" reads much better than a flat list.
• Set defaults. "Date range = last 30 days" with the option to override is friendlier than an empty date range.

Next

• Understand the parameter contract: Parameters, variables & queries.
• Set up the report the form drives: Quick start.
• Restrict who can submit: Sharing & permissions.