Input Controls REST API

These endpoints power dynamic parameter forms in the ReportShell frontend viewer or any custom web viewer by exposing JasperReports parameter metadata parsed from the JRXML.

Get Input Controls

GET /v1/reports/{reportKey}/controls
GET /v1/controls/{*reportKey}

Returns the list of input controls for the specified report.

Response

Array<ControlMetadata>

If report does not have any input controls, an empty array is returned.

ControlMetadata

Property	Type	Description
parameter	String	The unique identifier for the parameter.
label	String?	User-friendly display label for the control.
dataType	String	Data type of the parameter (e.g., String, Integer, Date).
dependsOn	Array<String>	List of parent parameters that this control depends on. Empty array if for no dependencies.
hidden	Boolean	Indicates if the control should be hidden in the UI.
required	Boolean	Indicates if a value is mandatory.
multi	Boolean	Indicates if multiple values can be selected.
choice	Boolean	Indicates if the control presents a set of choices (dropdown/list).
choiceWidget	String?	Specifies the UI widget type for choice parameters (e.g., SELECT, RADIO).

Example Response

[
  {
    "parameter": "createdAfter",
    "label": "Created After",
    "dataType": "Date",
    "dependsOn": [],
    "hidden": false,
    "required": false,
    "multi": false,
    "choice": false
  },
  {
    "parameter": "city",
    "label": "City",
    "dataType": "Integer",
    "dependsOn": [],
    "hidden": false,
    "required": false,
    "multi": true,
    "choice": true,
    "choiceWidget": "SELECT"
  },
  ...
]

Error Response

404 Not Found: If the report does not exist

Get Input Control States

GET /v1/reports/{reportKey}/control-states
GET /v1/control-states/{*reportKey}

Returns the values and data sets for input controls of the specified report. On first load (without rs.onchange parameter), it evaluates default values and loads data sets of parent controls which don’t depend on any other controls or child controls whose parent controls have a provided or default value.

When called with a rs.onchange parameter, it loads the child controls of the changed controls and re-evaluates the currently selected values of those child controls, removing any invalid values based on the parent’s current value.

Request Parameters

The endpoint takes report parameters for input controls as described in the REST API Overview and an optional rs.onchange parameter as described above.

Example Initial Request

GET /v1/reports/{reportKey}/control-states?param1=foo&param2=bar&rs.null=param3

This initial request sets values for param1, param2 and param3. For any other control, if the parameter specifies a default value expression it is evaluated. Then, data sets for controls that specify a query or list of values are loaded. For child controls, if the parent control has a specified value (including null), the child control’s data set is loaded. Any invalid values based on loaded data sets are removed for controls that have a data set.

Example Request with Changed Control

GET /v1/reports/{reportKey}/control-states?param1=foo&param2=bar&rs.null=param3&rs.onchange=param1

This request is similar to the initial request, but only child controls that depend on param1 are loaded and re-evaluated. Any invalid values based on loaded data sets are removed for the child controls.

Response

Array<ControlState>

If report does not have any input controls, an empty array is returned.

ControlState

Property	Type	Description
parameter	String	The name of the associated control parameter.
value	String? | Array<String>? | null	Current value of the control.
options	Array<Option>	The options for the control.
error	ControlLoadError?	Any validation errors for the control.

Caution

value property does not return for controls that don’t have a value. Frontend should not try to update the control’s value if this property is missing. An explicit null value for choice controls should be treated as “Select All”. See Input Controls for more information.

Option

Property	Type	Description
value	String	The value of the option.
columns	Array<String>	The columns to be used as the display label of the option.

ControlLoadError

Property	Type	Description
message	String	The error message.