The reportExecutions service includes only a simple mechanism for setting input controls (parameters) in reports. The inputControls service provides a complete set of operations for reading and setting input controls. Even though the inputControls service is accessed through a URL that includes rest_v2/reports/<resourceURI> /inputControls, the <resourceURI> can be any of the following resource types that support input controls:
| • | reportUnit |
| • | reportOption |
| • | dashboard |
| • | adhocDataView |
This chapter includes the following sections:
| • | Listing Input Controls |
| • | Input Control Structure |
| • | Listing Input Control Values |
| • | Changing the Order of Input Controls |
| • | Setting Input Control Values |
Listing Input Controls
The following method returns a description of the structure of the input controls for a given resource. The <resourceURI> can be any of the resource types that support input controls (reportUnit, reportOption, dashboard, adhocDataView).
By default, the inputControls operation returns both the structure and the state of the input controls. The structure of an input control is its name, type, and display characteristics (such as a label). The state of an input control includes both the current value and the list of possible values, if applicable to that type. You can use the structure of each input control to create a UI for your users to enter values. The state of each input control gives you the values to display, such as the values in a drop-down selector.
Some states are small because the input control type is a single text or numeric input, and only the current value is stored. Some states may be quite large if they are a select type (select single or select multiple items) based on a list generated dynamically from your data. For example, a list of customers to select from may contain hundreds or thousands of items. The inputControls operation can take much longer to return on such large input controls that require a query on your datasource. In this case, you can specify the exclude=state argument to list only input control structures first. You can request the input control states separately at a later time.
The inputControls service uses either XML or JSON data structures. If no Accept header is included, the response is XML by default.
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/reports/<resourceURI> | ||
| Argument | Type/Value | Description | |
| exclude | state | When specifed as exclude=state, the input control objects in the response contain only the structure elements and none of the state elements. Use this argument if your input controls have large lists of values and may affect performance. You can fetch these values in a separate call, usually after displaying the empty input control UI. See Listing Input Control Values. | |
| Options | |||
| accept: application/xml (default) | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content is a list of XML or JSON objects that describe the structure of all input controls. See examples below. 204 NO CONTENT – The specified <resourceURI> does not have any input controls defined. | 404 Not Found – When the specified <resourceURI> is not found in the repository. | ||
The body of the response contains an object defining the structure and optionally the state of the input controls. The following examples shows the same input control in both the XML and JSON formats, including values in the state objects:
The following example shows two more JSON objects for single value number and date types of input controls. The number data type has limits, in this example 1 ≤ number ≤ 50, that your application should enforce when users input a value. Indpendently of the input limits, the values of these input controls are used as limits for a comparison filter, for example "store ID that is less than or equal to" or "Opening date after". Note that the type of filter is not reflected in the input control structure other than through a judiciously named label. Your app usually needs to know the structure of a report and the use of its input controls to properly render a UI that reflects the actual filters.
Input Control Structure
The input control objects shown in the examples above contain the information needed by your application to display the input controls to your users and allow them to make a selection. The main elements are:
| • | ID and URI to define which input control it is. |
| • | Mandatory, visible, and read-only flags to determine whether users should interact with this input control. |
| • | Display characteristics such as a label and description. |
| • | The type of input control, which also determines how it is displayed and how users interact with it, for example text box, checkboxes, radio buttons, or drop-down list. The type is one of the following values: |
| bool (checkbox) singleSelect (drop-down) singleSelectRadio multiSelectCheckbox multiSelect (list box) | singleValue singleValueText singleValueNumber singleValueDate singleValueDatetime singleValueTime |
For all of the single-value types in the right-hand column, the structure includes an additional dataType object that defines limits on the data type such as maxValue or strictMax. Your app should interpret these limits and enforce them on the values that users may enter.
The input control structure also includes certain validation rules that depend on the type of input control. The presence of these rules indicates that your client should verify or validate the values it receives from your users. The rules provide messages to display when validation fails. Messages are localized if you have language bundles defined on the server and the authenticated user specifies a locale. In the current release, the following validations are possible:
| • | mandatoryValidationRule – This input is required (as indicated by "mandatory": true), and your client should ensure the user enters a value. |
| • | dateTimeFormatValidationRule – This input is a date or time value and your client should ensure the user enters a valid date or time. |
The input control structure also defines cascading dependencies, if any, between the input controls. The cascading dependencies determine whether a change of values in one input control may change the possible values in another.
| • | masterDependencies – A list of input control IDs that this input control depends upon. If one of these dependencies is modified, your application should fetch the new state of this input control. |
| • | slaveDependencies – A list of input control IDs that depend upon this input control. If this input control is modifided (given a new value by your user), your application should fetch new state values for these dependencies. |
The state object of an input control contains the current and possible values for this input control. The state objects are explained in the next section.
Listing Input Control Values
The following method returns only the state objects that define the current values of a resource's input controls. The state object includes the possible values of each input controls, and among these values, the one that is currently selected. Your app can use these values to generate input and selection widgets in the UI for each input control.
Use this method if you have already fetched all the input control structures using the inputControls method. The <resourceURI> can be any of the resource types that support input controls (reportUnit, reportOption, dashboard, adhocDataView).
| Method | URL | ||
| GET | http://<host>:<port>/jasperserver[-pro]/rest_v2/reports/<resourceURI> | ||
| Argument | Type/Value | Description | |
| freshData | true|false | When freshData=true is specified, the list of values for any selection input contols is refreshed with a database query. When this argument is omitted, its default value is false, and cached values for input controls are returned. Querying the database for thousands of input control list values may impact performance, which is why the server manages a cache of these values. | |
| Options | |||
| accept: application/xml (default) | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content is a list of XML or JSON objects that describe the values of all input controls. See examples below. 204 NO CONTENT – The specified <resourceURI> does not have any input controls defined. | 404 Not Found – When the specified <resourceURI> is not found in the repository. | ||
The body of the response contains a list of state objects for all input controls in the given resource. The contents of each state object depend upon the type of the input control. Single value types will only have a value that is the current value of the input control. Selection types have a list of options, each with a value and indicator of whether it is currently selected or not.
The following examples shows the same state objects in both the XML and JSON formats:
| | If a selection-type input control has a null value, it is given as ~NULL~. If no selection is made, its value is given as ~NOTHING~. |
The internal structure of the inputControlState object in an inputControls/Values response is the same as that of a state object in an inputControls response.
The following example shows two more JSON inputControlState objects for single value number and date types of input controls.
Note that the state objects do not contain the input control type, therefore your app must determine how to read each state object based on the input control structure that it has previously fetched and stored in memory. There are two ways you can match the list of input control values to their previously fetched structure:
| • | Each state object has the ID and URI of its corresponding input control. The URI of an input control is equivalent to <resourceURI>_files/<inputControlID>. Use the ID or URI of each state object to match the ID or URI of each input control stucture in your app. |
| • | Input controls are positional: the order of input controls is determined when creating the resource and saved in the resource. All responses from the inputControls methods, both structure and values, contain the complete list of input controls in the same order. |
Changing the Order of Input Controls
The inputControls service does not allow you to modify any input control structures, such as types, labels, visibility, or dependencies, because doing so would break the reports that rely on them. Also, input controls definitions may simply be referenced in a resource and their structure defined in other repository folders. However, you may use the following method to change the order of the input controls.
Changing the order of the input controls is persistent in the parent resource as stored in the repository, but it does not affect the running of a report or dashboard or their display in a viewer.
Note that if you manage your list of input control structures and states based on the unchanging order of input controls, this operation will invalidate your current order in memory. You will need to update your list of stored input controls, or use IDs or URIs to match structures and states.
| Method | URL | ||
| PUT | http://<host>:<port>/jasperserver[-pro]/rest_v2/reports/<resourceURI>/inputControls/ | ||
| Content-Type | Content | ||
| application/xml | An XML or JSON object that lists the full structure, including the state object, of all input controls in the new order. You cannot modify any fields in the input control strucutres, they must be sent exactly as received from the inputControls service, except for the order of objects in the list. | ||
| Options | |||
| accept: application/xml (default) | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content is an XML or JSON object that lists all input control structures, including their state objects. This should be identical to the content that was sent. | 403 Forbidden – If any input control structure in the request list does not match its current structure. 404 Not Found – When the specified <resourceURI> is not found in the repository. | ||
Setting Input Control Values
After your app has fetched all structures and values and created a UI, your users can interact with the input controls and set new values. Use the following methods to send the new values and selections to the server. The server performs validation and returns an error if certain conditions are not satisfied. Before sending new values your application should validate user input in several ways:
| • | It must prevent certain input, such as accepting values for a read-only input control or making multiple selections in a single-select input control. |
| • | It should enforce constraints, such as ensuring that a mandatory input control is not null or has at least one selection. |
| • | It should also validate values against any input control limits, such as minimum and maximum values. |
After sending new values, use the response to update any changes in selection list values. For example, if you change an input control with cascading dependencies, the server will respond with the new selection lists for the dependent input controls. After all new values have been set, you can call the reportExecutions service to run the report again.
There are two forms of this operation, one that returns the full input control structures, and the other that returns only the state values.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/reports/<resourceURI> | ||
| Argument | Type/Value | Description | |
| freshData | true|false | When freshData=true is specified, the list of values for any selection input contols is refreshed with a database query. When this argument is omitted, its default value is false, and cached values for input controls are returned. Querying the database for thousands of input control list values may impact performance, which is why the server manages a cache of these values. | |
| Content-Type | Content | ||
| application/xml | An XML object that lists the new value for just those input controls that are modified, for example: | ||
| application/json | A JSON object that lists the new value for just those input controls that are modified. In JSON, the value of every input control is given as an array of string values, even for numbers, single-select controls, or multi-select controls with a single value. This example is equivalent to the XML example above: | ||
| Options | |||
| accept: application/xml (default) | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content is a list of XML or JSON structure objects that describes all input controls and their values, including the newly sent values and any new list values arising from cascading dependencies. | 403 Forbidden – If any input control value in the request list is invalid as determined by its type or limit validation. 404 Not Found – When the specified <resourceURI> is not found in the repository. | ||
When sending the values shown in the table above, the JSON response is a list of input control structures that begins with the following element:
In the second form, you send the same content in the request, but the URL includes the IDs of the modified input controls and you request values.
| Method | URL | ||
| POST | http://<host>:<port>/jasperserver[-pro]/rest_v2/reports/<resourceURI> | ||
| Argument | Type/Value | Description | |
| freshData | true|false | When freshData=true is specified, the list of values for any selection input contols is refreshed with a database query. When this argument is omitted, its default value is false, and cached values for input controls are returned. Querying the database for thousands of input control list values may impact performance, which is why the server manages a cache of these values. | |
| Content-Type | Content | ||
| application/xml | An XML object that lists the new value for just those input controls that are modified, for example: | ||
| application/json | A JSON object that lists the new value for just those input controls that are modified. In JSON, the value of every input control is given as an array of string values, even for numbers, single-select controls, or multi-select controls with a single value. This example is equivalent to the XML example above: | ||
| Options | |||
| accept: application/xml (default) | |||
| Return Value on Success | Typical Return Values on Failure | ||
| 200 OK – The content is a list of XML or JSON state objects of all input control values, including the newly sent values and any new list values arising from cascading dependencies. | 403 Forbidden – If any input control value in the request list is invalid as determined by its type or limit validation. 404 Not Found – When the specified <resourceURI> is not found in the repository. | ||
When sending the values shown in the table above, the JSON response is a list of state objects that begins with the following element:
Recommended Comments
There are no comments to display.