The inputControls Service¶

The reportExecutions service includes only a simple mechanism for setting input control (parameters) values in reports. The inputControls service provides a complete set of operations for reading and reordering input controls, and for updating input control values. 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

• adhocDataView

  Note

  rest_v2/inputControls is mainly a read-only API (for example, for reading the list of available input controls in a report, getting values of that input control, or selecting certain values from the list of available input controls). Use rest_v2/resources for mapping or updating input controls.

  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, 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 dropdown 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 later.

The inputControls service uses either XML or JSON data structures. If no Accept header is included, the response is XML by default.

The body of the response contains an object defining the structure and optionally the state of the input controls. The following examples show the same input control in both the XML and JSON formats, including values in the state objects:

<inputControls>
    <inputControl>
        <description>Country multi select</description>
        <id>Country_multi_select</id>
        <label>Country multi select</label>
        <mandatory>true</mandatory>
        <masterDependencies/>
        <readOnly>false</readOnly>
     <readOnlyExpression>Product>5</readOnlyExpression>
     <visible>true|false</visible>
     <visibilityExpression>Birthdate==DATERANGE('DAY')</visibilityExpression>
        <slaveDependencies>
            <controlId>Cascading_name_single_select</controlId>
            <controlId>Cascading_state_multi_select</controlId>
        </slaveDependencies>
        <state>
            <id>Country_multi_select</id>
            <options>
                <option>
                    <label>Canada</label>
                    <selected>false</selected>
                    <value>Canada</value>
                </option>
                <option>
                    <label>Mexico</label>
                    <selected>false</selected>
                    <value>Mexico</value>
                </option>
                <option>
                    <label>USA</label>
                    <selected>true</selected>
                    <value>USA</value>
                </option>
            </options>
            <uri>/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select</uri>
        </state>
        <type>multiSelect</type>
        <uri>repo:/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select</uri>
        <validationRules>
            <mandatoryValidationRule>
                <errorMessage>This field is mandatory so you must enter data.</errorMessage>
            </mandatoryValidationRule>
        </validationRules>
        <visible>true</visible>
    </inputControl>
    ...
    <caseSensitive>true</caseSensitive>
</inputControls>
{
    "inputControl": [
        {
            "id": "Country_multi_select",
            "description": "Country multi select",
            "type": "multiSelect",
            "uri": "repo:/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select",
            "label": "Country multi select",
            "mandatory": true,
            "readOnly": false,
            "readOnlyExpression":"Product>5",
            "visible": true,
            "visibilityExpression":"Birthdate==DATERANGE('DAY')",
            "masterDependencies": [],
            "slaveDependencies": [
                "Cascading_name_single_select",
                "Cascading_state_multi_select"
            ],
            "validationRules": [
                {
                    "mandatoryValidationRule": {
                        "errorMessage": "This field is mandatory so you must enter data."
                    }
                }
            ],
            "state": {
                "uri": "/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select",
                "id": "Country_multi_select",
                "options": [
                    {
                        "selected": false,
                        "label": "Canada",
                        "value": "Canada"
                    },
                    {
                        "selected": false,
                        "label": "Mexico",
                        "value": "Mexico"
                    },
                    {
                        "selected": true,
                        "label": "USA",
                        "value": "USA"
                    }
                ]
            }
        },
        ...
    ],
    "caseSensitive": true
}

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. Independently 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.

{
    "inputControl": [
        {
            "id": "store_id_1",
            "type": "singleValueNumber",
            "uri": "repo:/public/reports/StoreReport_files/store_id_1",
            "label": "Store ID is less than or equal to",
            "mandatory": false,
            "readOnly": false,
        "readOnlyExpression": "Product>5",
            "visible": true,
            "visibilityExpression":"Birthdate==DATERANGE('DAY')",
            "masterDependencies": [],
            "slaveDependencies": [],
            "state": {
                "uri": "/public/reports/StoreReport_files/store_id_1",
                "id": "store_id_1",
                "value": "22"
            },
            "dataType": {
                "type": "number",
                "maxValue": "50",
                "strictMax": false,
                "minValue": "1",
                "strictMin": false
            }
        },
        {
            "id": "first_opened_date_1",
            "type": "singleValueDatetime",
            "uri": "repo:/public/reports/StoreReport_files/first_opened_date_1",
            "label": "Date opened is greater than",
            "mandatory": false,
            "readOnly": false,
        "readOnlyExpression":"Product>5",
            "visible": true,
        "visibilityExpression":"Birthdate==DATERANGE('DAY')",
            "masterDependencies": [],
            "slaveDependencies": [],
        "caseSensitive": false,
            "validationRules": [
                {
                    "dateTimeFormatValidationRule": {
                        "errorMessage": "Specify a valid date/time value.",
                        "format": "yyyy-MM-dd'T'HH:mm:ss"
                    }
                }
            ],
            "state": {
                "uri": "/public/reports/StoreReport_files/first_opened_date_1",
                "id": "first_opened_date_1",
                "value": "1982-01-08T00:00:00"
            },
            "dataType": {
                "type": "datetime",
                "strictMax": false,
                "strictMin": false
            }
        }
    ],
    "caseSensitive": true
}

The inputControl.handler.values.caseSensitive property defines the case-sensitive behavior for input controls. This is defined in the .../WEB-INF/js.config.properties configuration file, with a default value True.

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 dropdown list. The type is one of the following values:

  bool (checkbox)	singleValue
  singleSelect (dropdown)	singleValueText
  singleSelectRadio	singleValueNumber
  multiSelectCheckbox	singleValueDate
  multiSelect (list box)	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 that the user enters a value.

      "mandatoryValidationRule" : {
          "errorMessage" : "This field is mandatory so you must enter data."
      }
  

• dateTimeFormatValidationRule - This input is a date or time value and your client should ensure that the user enters a valid date or time.

      "dateTimeFormatValidationRule" : {
          "errorMessage" : "Specify a valid date value.",
          "format" : "yyyy-MM-dd"
      }
  

  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 on. 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 on this input control. If this input control is modified (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 control, 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, adhocDataView).

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 on 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 show the same state objects in both the XML and JSON formats:

<inputControlStateList>
    <inputControlState>
        <id>Country_multi_select</id>
        <options>
            <option>
                <label>Canada</label>
                <selected>false</selected>
                <value>Canada</value>
            </option>
            <option>
                <label>Mexico</label>
                <selected>false</selected>
                <value>Mexico</value>
            </option>
            <option>
                <label>USA</label>
                <selected>true</selected>
                <value>USA</value>
            </option>
        </options>
        <uri>/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select</uri>
    </inputControlState>
    ...
</inputControlStateList>
{
    "inputControlState": [
        {
            "uri": "/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select",
            "id": "Country_multi_select",
            "options": [
                {
                    "selected": false,
                    "label": "Canada",
                    "value": "Canada"
                },
                {
                    "selected": false,
                    "label": "Mexico",
                    "value": "Mexico"
                },
                {
                    "selected": true,
                    "label": "USA",
                    "value": "USA"
                }
            ]
        },
        ...
    ]
}

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.

{
    "inputControlState": [
        {
            "uri": "/public/reports/StoreReport_files/store_id_1",
            "id": "store_id_1",
            "value": "22"
        },
        {
            "uri": "/public/reports/StoreReport_files/first_opened_date_1",
            "id": "first_opened_date_1",
            "value": "1982-01-08T00:00:00"
        }
    ]
}

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 structure 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¶

You cannot use the inputControls service 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 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 invalidates your current order in memory. You need to update your list of stored input controls, or use IDs or URIs to match structures and states.

Setting Input Control Values¶

After your app has fetched all structures and values and created a UI, you 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 the following 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 responds 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.

<reportParameters>
    <reportParameter name="Country_multi_select">
        <value>Mexico</value>
    </reportParameter>
     <reportParameter name="Cascading_state_multi_select">
        <value>Guerrero</value>
        <value>Sinaloa</value>
    </reportParameter>
</reportParameters>

{
    "Country_multi_select":["Mexico"],
    "Cascading_state_multi_select":["Guerrero", "Sinaloa"]
}

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:

{
    "inputControl": [
        {
            "id": "Country_multi_select",
            "description": "Country multi select",
            "type": "multiSelect",
            "uri": "repo:/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select",
            "label": "Country multi select",
            "mandatory": true,
            "readOnly": false,
           "readOnlyExpression":"Product>5",
            "visible": true,
              "visibilityExpression":"Birthdate==DATERANGE('DAY')",
            "masterDependencies": [],
            "slaveDependencies": [
                "Cascading_name_single_select",
                "Cascading_state_multi_select"
            ],
            "validationRules": [
                {
                    "mandatoryValidationRule": {
                        "errorMessage": "This field is mandatory so you must enter data."
                    }
                }
            ],
            "state": {
                "uri": "/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select",
                "id": "Country_multi_select",
                "options": [
                    {
                        "selected": false,
                        "label": "Canada",
                        "value": "Canada"
                    },
                    {
                        "selected": true,
                        "label": "Mexico",
                        "value": "Mexico"
                    },
                    {
                        "selected": false,
                        "label": "USA",
                        "value": "USA"
                    }
                ]
            }
        },
        ...
    ]
}

In the second form, you send the same content in the request, but the URL includes the IDs of the modified input controls and your requested values.

<reportParameters>
    <reportParameter name="Country_multi_select">
        <value>Mexico</value>
    </reportParameter>
     <reportParameter name="Cascading_state_multi_select">
        <value>Guerrero</value>
        <value>Sinaloa</value>
    </reportParameter>
</reportParameters>

{
    "Country_multi_select":["Mexico"],
    "Cascading_state_multi_select":["Guerrero", "Sinaloa"]
}

When sending the values shown in the table above, the JSON response is a list of state objects that begins with the following element:

{
    "inputControlState": [
        {
            "uri": "/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select",
            "id": "Country_multi_select",
            "options": [
                {
                    "selected": false,
                    "label": "Canada",
                    "value": "Canada"
                },
                {
                    "selected": true,
                    "label": "Mexico",
                    "value": "Mexico"
                },
                {
                    "selected": false,
                    "label": "USA",
                    "value": "USA"
                }
            ]
        },
        ...
    ]
}

Getting Total Available Values¶

This method is used to get the total available values and limit the count of the total available values retrieved when input controls are paginated.

Provide inputs for the following fields in the request body:

• Offset - Specify the values to be returned for each input control.

• Limit - Specify the total number of values to be returned for each input control.

• Criteria - Specify the texts or words to be returned for each input control. If specified, then it searches not only for the complete text, but also for the values provided in the texts for the specified criteria. For example, specifying "ry" in the criteria field returns all the values containing "ry" texts.

• Select - This field is newly added. Specify either "selectedValues" or "allValues" in this field.

  • If "selectedValues" is chosen, then the returned available values have the default-selected values.
  • If "allValues" is chosen, then the returned available values have all the values selected.
  • If any other value other than "selectedValues" or "allValues" is provided, then this field is ignored.

Pass the following arguments to get the total available values of the input control based on selected offset, limit, criteria, and select fields.

<reportParameters>
  <reportParameter name="Country_multi_select">
    <limit>2</limit>
    <offset>1</offset>
    <select>selectedValues</select>
  </reportParameter>
  <reportParameter name="Cascading_name_single_select">
    <criteria>Adams Construction</criteria>
    <select>allValues</select>
  </reportParameter>
  <reportParameter name="Cascading_state_multi_select">
    <value>CA</value>
    </reportParameter>
</reportParameters>

{
 "reportParameter": [
   {
     "name": "Country_multi_select",
     "limit": 2,
     "offset": 1,
     "select": "selectedValues"
    },
   {
     "name": "Cascading_name_single_select",
     "criteria": "Adams Construction",
     "select": "allValues"
    },
   {
     "name": "Cascading_state_multi_select",
     "value": [
     "CA"
    ]
   }
 ]
}

When sending the values shown in the table above, the JSON response has the total available values but the number of values are limited based on the offset, limit, and search criteria.

{
  "inputControlState": [
    {
      "uri": "/organizations/organization_1/adhoc/topics/Cascading_multi_select_topic_files/Country_multi_select",
      "id": "Country_multi_select",
      "totalCount": "4",
      "options": [
       {
         "selected": false,
         "label": "Mexico",
         "value": "Mexico"
       },
       {
         "selected": true,
         "label": "USA",
         "value": "USA"
       }
      ]
    },
    {
       "uri": "/organizations/organization_1/adhoc/topics/Cascading_multi_select_topic_files/Cascading_state_multi_select",
       "id": "Cascading_state_multi_select",
       "totalCount": "3",
       "options": [
         {
           "selected": true,
           "label": "USA | CA",
           "value": "CA"
         },
         {
           "selected": false,
           "label": "USA | OR",
           "value": "OR"
         },
         {
          "selected": false,
          "label": "USA | WA",
          "value": "WA"
         }
       ]
     },
     {
       "uri": "/organizations/organization_1/adhoc/topics/Cascading_multi_select_topic_files/Cascading_name_single_select",
       "id": "Cascading_name_single_select",
       "totalCount": "2",
       "options": [
          {
            "selected": true,
            "label": "Steelman-Adams Construction Partners",
            "value": "Steelman-Adams Construction Partners"
          },
          {
            "selected": true,
            "label": "Winter-Adams Construction Associates",
            "value": "Winter-Adams Construction Associates"
          }
        ]
      }
   ]
}

Getting Default Selected Values¶

This method is used to get the default selected values when the input controls are paginated. For example, when a Report, Scheduler, or Dashboard is initially loaded, the input controls API excludes only the values defined in the "state" to avoid the values to be included in the response.

Pass the following arguments to get only the default-selected values of the input control field in the response.

The following example shows a simple use of the select field in JSON:

{

    "selectedValue": [

        {
            "id": "Country_multi_select",

            "options": [
                {
                    "label": "USA",

                    "value": "USA"
                }
            ]
        },

        {
            "id": "Cascading_state_multi_select",

            "options": [

               {
                    "label": "USA | CA",

                    "value": "CA"
                }
            ]
        },

        {
            "id": "Cascading_name_single_select",

            "options": [
                {
                    "label": "A & U Stalker Telecommunications, Inc",
                    "value": "A & U Stalker Telecommunications, Inc"
                }
            ]
        }
    ]
}

The following example shows a simple use of the select field in XML:

<selectedValues>

    <selectedValue id="Country_multi_select">
        <options>
            <label>USA</label>

            <value>USA</value>

        </options>
    </selectedValue>

    <selectedValue id="Cascading_state_multi_select">
        <options>
            <label>USA | CA</label>
            <value>CA</value>
        </options>

    </selectedValue>

    <selectedValue id="Cascading_name_single_select">

        <options>
            <label>A & U Stalker Telecommunications, Inc</label>
            <value>A & U Stalker Telecommunications, Inc</value>

        </options>
    </selectedValue>
</selectedValues>