Overridable config parameters

Overridable config parameters provide the option to let report editors modify default values in a data source. Defining config parameters as overridable makes a data source more flexible, and gives users a way to create user-configurable report templates.

For example, a connector providing weather data could include a location parameter that lets report viewers request a weather report from a locale different than the default.

This document describes how overridable parameters are defined, enabled for modification, and how parameter values can be modified by report users. To learn more about how parameters are used in Data Studio see Data source parameters.

Roles

The user roles referenced throughout the document:

Role Definition
Connector developer A user that has built a community connector.
Data source owner A user that created and owns a data source.
Report editor A user with edit mode access to a report.
Report viewer A user with view mode access to a report.

Defining overridable parameters

The connector developer defines config parameters in the getConfig() function of a community connector. To define a config parameter as overridable the connector calls setAllowOverride(true).

The following example defines 2 overridable parameters: zipcode and units and 1 parameter that is not overridable: days-to-forcecast.

Screenshot of 2 overridable parameters

function getConfig(request) {
  var config = cc.getConfig();

  // A
  config
      .newTextInput()
      .setId("zipcode")
      .setName("ZIP Code")
      .setAllowOverride(true);

  // B
  config
    .newSelectSingle()
    .setId("units")
    .setName("Units")
    .addOption(
        config
          .newOptionBuilder()
          .setLabel("Metric")
          .setValue("metric")
    )
    .addOption(
      config
        .newOptionBuilder()
        .setLabel("Imperial")
        .setValue("imperial")
    )
    .setAllowOverride(true);

  // C
  config
    .newTextInput()
    .setId("days-to-forecast")
    .setName("Days to forecast")
      .setAllowOverride(false);


  return config.build();
}

When to avoid defining a parameter as overridable

It is recommended to learn how Connectors, Data Sources, and Reports work in relation to each other by reviewing How Data Studio connects to your data.

Avoid defining a parameter as overridable in the following cases:

  1. When the value of a parameter affects the schema.
    • If a user changes a parameter value and the schema of the new data returned is different than defined in the data source, any report dependent on the data source could break because of missing fields.
  2. If a parameter value controls sensitive data. E.g. Account selection.
    • Do not define a parameter as overridable if you want to prevent unintentional viewing or sharing of sensitive data.

Enabling parameters for report users

Data source owners control which overridable parameters are allowed to be modified by report editors. Similarly, report editors control which parameters can be modified by report viewers.

Allow report editors to modify parameters values

The data source owner controls which parameters are allowed to be modified in reports. This is configured during creation or editing of a data source and is applicable only to parameters that have been defined as overridable by the Connector developer. If enabled then report editors will be able to Modify parameters in a report.

In the following example, a connector has 2 parameters defined as overridable: zipcode and units. The data source owner has only allowed zipcode to be modified in reports. In the report, the report editor has the option to modify the zipcode parameter value.

Enabling override option

Allow report viewers to modify parameters values

Report editors control which parameters can be modified by report viewers. The parameter values can then be modified through the report URL by any viewer of the report.

For example, consider a connector that has 2 parameters defined as overridable: zipcode and units. If the data source owner has allowed zipcode to be modified in reports then report editors will only be capable of allowing zipcode to be modified by report viewers. The report editor will not have access or visibility to allow the units parameter to be modified by report viewers.

Allow url parameters

URL parameters

To allow report viewers to edit parameter values through the report URL:

  1. Edit the report.
  2. Select Resource -> Manage URL parameters.
  3. Use the Allow to be modified in the report URL checkboxes to allow or disallow modification of parameter values in the report URL. Changes are automatically saved.
  4. Click Close in the upper right.

Modifying parameter values

Report editors can modify parameter values using the report properties panel while report viewers can modify parameter values through the report URL.

Report properties panel

To learn how a report editor can set parameter values, see Modify parameters in a report.

Report URL parameters

For parameters that are allowed to be modified in the report URL, values can be set through a URL-encoded configuration appended to the report URL in view mode.

To create a URL config:

  1. Gather data source and parameter ID information

    1. Edit the report.
    2. Select Resource -> Manage URL parameters.
    3. Select the DATA SOURCES tab.
    4. Note the data source ID and parameter IDs of the parameters you intend to set through the report URL.

    For example, in the figure below the MyWeather data source ID is ds0 and the Zip Code parameter ID is zipcode.

    Enabling url parameters

  2. Write the configuration

    The configuration is a JSON object. The root properties represent data sources where the key is the data source ID and the value is an object containing the parameters to set.

    {
      dataSourceId: {
          parameterId: parameterValue
      }
    }
    

    Parameter value types can include STRING, NUMBER, and BOOLEAN. For parameters that accept multiple values (i.e. Multi-select dropdowns) a comma-separated list of values can be used.

    For example, if the MyWeather data source ID is ds0 and the Zip Code parameter ID is zipcode, to set ZIP Code to 94094, the JSON configuration is as follows:

    {
      "ds0": {
        "zipcode": "94094"
      }
    }
    
  3. Encode the URL

    After you have the config JSON, URL encode it. You can use the encodeURIComponent() JavaScript function.

    var jsonConfig = {
      "ds0": {
        "zipcode": "94094"
      }
    };
    var encoded = encodeURIComponent(JSON.stringify(jsonConfig))
    

    This results in the following encoded string:

    "%7B%22ds0%22%3A%7B%22zipcode%22%3A%2294094%22%7D%7D"
    
  4. Build the report URL

    Once you have the encoded URL encoded configuration, you can append it to the report view URL using the config query parameter.

    https://datastudio.google.com/reporting/<REPORT_ID>/page/<PAGE_ID>?config=%7B%22ds0%22%3A%7B%22zipcode%22%3A%2294094%22%7D%7D

  5. Use the URL

    The report URL you created in will override the parameters values as defined in the JSON config based on Parameter inheritance.

JSON Configuration example

The following JSON configuration example shows how to set multiple parameters for multiple data sources. It also illustrates setting parameter values for the various input types.

The includeToday parameter is a checkbox input, units is a single select input, countries is a mutli-select input and labelName is a text input.

  {
    "ds2": {
      "includeToday": true,
      "units": "Metric"
    },
    "ds5": {
      "countries": ["Canada","Mexico"],
      "labelName": "Population"
    }
  }

Parameter inheritance

The value used for a parameter follows an order of precedence based on where the parameter is set. Parameters set at higher precedence locations override parameters set at lower precedence locations. The order of precedence (from lowest to highest) is:

  1. Data source (default)
  2. Report URL
  3. Report properties panel, following the data source parameter inheritance rules.