Parameters

Many plugin components, including datasets, recipes, macros, and webapps, can be configured through a form. The list of parameters required by a given component must be specified as a JSON array and DSS will generate the corresponding user interface.

Describing parameters

The definition of each parameter has the following fields:

  • type: Type of the parameter. Most common types are STRING, INT, DOUBLE, BOOLEAN, SELECT, DATASET and COLUMN. See below.
  • name: Name of the parameter as accessible by your component’s code. We highly recommend that you_use_slug_like_names
  • label: Name of the parameter as displayed on screen.
  • description: Additional help to describe the parameter. Will appear on the side of the form.
  • defaultValue: Initial value, note that the type must match the parameter type.
  • mandatory: true/false, is this parameter required
  • visibilityCondition: Show/hide this parameter depending on a condition. See below.

Besides, additional fields may be available for specific types of parameters. See below.

Available parameter types

Some components take an array of parameters that describe the allowable parameters of the components. Each parameter is a JSON object with the following fields:

  • name: Name of the parameter in the configuration dict. We highly recommend that you_use_slug_like_names.
  • type: Type of the parameter. The most common types are STRING, INT, DOUBLE, BOOLEAN, PASSWORD, SELECT and DATASET. See below for full documentation of available types.
  • label: The user-visible name that appears in the form.
  • description: User-visible additional help. It appears at the right of the form when a user is filling out the component settings.
  • defaultValue: Pre-filled value of the parameter. Type must match the field type.
  • mandatory (boolean): When true, this parameter must be supplied in order to use the component. When false, the parameter is optional.
  • visibilityCondition: Allows you to show/hide this parameter based on a condition. See Other topics for details.

The following fields can be used for specific types of parameters:

  • canSelectForeign (boolean, default false): Should this parameter show foreign elements? For DATASET(S), MODEL and FOLDER only.
  • columnRole: For COLUMN and COLUMNS only. See below for details.
  • selectChoices: For SELECT only. See below for details.
  • datasetParamName: For DATASET_COLUMN only. Parameter name of the related dataset. See below for details.
  • apiServiceParamName: For API_SERVICE_VERSION only. Parameter name of the related API Service. See below for details.
  • credentialRequestSettings: For CREDENTIAL_REQUEST only. See below for details.

Note

In the Python recipes, the parameters are the result of JSON deserialization. As such, you’ll only get the following data types: string, float, bool (in other words, a INT parameter is received as a float in Python)

String parameters

  • STRING: A simple string
  • TEXTAREA: A string, but the UI shows a multi-line control suitable for entering long text.
  • STRINGS: A list of strings

In the case of STRINGS, you may specify:

  • "allowDuplicates": true: to prevent duplicate strings in the parameter (case sensitive)

Example:

{
  "type": "STRING",
  "name": "favorite_quote",
  "label": "What's your favorite quote from Camus?",
  "defaultValue": "At any street corner the feeling of absurdity can strike any man in the face."
}

Numerical parameters

  • INT: An integer.
  • DOUBLE: A decimal

You can provide minI/maxI (for INT) and minD/maxD (for DOUBLE) to force a value interval.

Example:

{
  "type": "INT",
  "name": "age",
  "label": "Age of the captain",
  "minI": 0,
  "maxI": 122
}

Note

The parameters are obtained by the component’s code after JSON serialization, so an INT parameter is received as a float by the component’s code, and the only difference between INT and DOUBLE is the specific UI.

Boolean parameters

  • BOOLEAN: A boolean, displayed as a checkbox.

Example:

{
  "type": "BOOLEAN",
  "name": "the_other_boolean_g",
  "label": "I accept",
  "defaultValue": false
}

Multi-choice parameters and presets

  • SELECT: Select one value among possible choices.
  • MULTISELECT: Select several values among possible choices.
  • PRESET: Reuse values that have been predefined by DSS instance or project admins.

SELECT and MULTISELECT parameters must have one of the two fields:

  • selectChoices: list of {value, label} if the list is static
  • getChoicesFromPython: true if the plugin contains a python function that can generate dynamically the list of {value, label}. For details see below in the advanced section.

Selects allow you to propose multiple choices, and have the user select one (and only one). Each choice has an identifier and a user-visible long string.

Example of a simple select:

{
  "type": "SELECT",
  "name": "egg_type",
  "label": "Choose your eggs",
  "selectChoices": [
    { "value": "scrambled", "label": "Scrambled"},
    { "value": "sunny_up", "label": "Sunny-side up"}
  ]
}

For the PRESET type, you must first create a Parameter Set in your plugin and reference it using:

  • parameterSetId: parameter set of which we should see the values listed.

Example

{
  "type": "PRESET",
  "name": "aws_account",
  "label": "Choose which account to use",
  "parameterSetId": "aws_accounts"
}

Passwords parameters

  • PASSWORD: A simple string, but the UI hides the typing

Passwords (for example, to access an external API) should typically be plugin parameters, not component parameters, so that they are set only once and visible only to admins. See below for details on plugin parameters.

Credential requests

  • CREDENTIAL_REQUEST: This generates a request for a per-user credential. Once a preset of the parameter set is instantiated, each user will then be able to add their personal credential in Profile > Credentials. This parameter type is only accepted in the params section of a parameter set.

A credentialRequestSettings object must be added to define the credential request. This object contains:

  • type: The type of credential. Must be one of SINGLE_FIELD, BASIC, or OAUTH2

For OAUTH2, the following fields must/may be added to the credentialRequestSettings object:

  • authorizationEndpoint: The authorization endpoint of the OAuth2 authorization server
  • tokenEndpoint: The token endpoint of the OAuth2 authorization server
  • scope: [Optional] Should be a space delimited string
  • resources: [Optional] Rarely used. Must be a list of strings

Additionally for OAUTH2, once a preset of this parameter set is instantiated, you must enter in the Client ID and Client Secret (if applicable) that is configured for your registered application on the OAuth2 server. See OAuth2 credentials for more information.

These credentials will then be available for use by plugin code (see Read settings of a plugin). For example, for a BASIC credential, the username and password will be available in the settings, while for an OAUTH2 credential, a valid OAuth2 access token will be in the settings.

Examples:

{
  "type": "CREDENTIAL_REQUEST",
  "name": "basic_credentials",
  "label": "Basic credentials",
  "credentialRequestSettings": {
    "type": "BASIC"
  }
},
{
  "type": "CREDENTIAL_REQUEST",
  "name": "oauth_credentials",
  "label": "OAuth2 credentials",
  "credentialRequestSettings": {
    "type": "OAUTH2",
    "authorizationEndpoint": "https://authserver.com/oauth2/authorize",
    "tokenEndpoint": "https://authserver.com/oauth2/token",
    "scope": "scope1 user.scope2"
  }
}

Date parameters

  • DATE: A simple date, that you will be able to pick from a calendar.

Example:

{
  "type": "DATE",
  "name": "release_date",
  "label": "Release Date"
}

DSS object parameters

  • PROJECT: A Dataiku DSS project
  • DATASET: Select exactly one dataset.
  • DATASETS: One or more datasets.
  • DATASET_COLUMN: A column from a specified dataset. This type requires a datasetParamName to point to another parameter that has the type. See example below. (Note that this is probably not what you want for recipes, see the COLUMN type below)
  • DATASET_COLUMNS: One or more columns from a specified dataset.
  • MANAGED_FOLDER: A DSS managed folder (appear in the flow).
  • SAVED_MODEL: A DSS saved model (deployed version of a model that appears on the flow)
  • API_SERVICE: A DSS API service.
  • API_SERVICE_VERSION: A version package among a specified API service. This type requires an apiServiceParamName to point to another parameter that has the type API_SERVICE. See example below.
  • BUNDLE: An automation bundle.
  • VISUAL_ANALYSIS: A visual analysis.
  • CONNECTIONS: One or more connections.
  • SCENARIO: A DSS scenario.
  • CODE_ENV: A DSS code environment.
  • PLUGIN: A DSS plugin.
  • CLUSTER: A DSS cluster.

Specific fields:

  • datasetParamName: For DATASET_COLUMN only. Parameter name of the related dataset.
  • apiServiceParamName: For API_SERVICE_VERSION only. Parameter name of the related API Service.
  • canSelectForeign (boolean, default false): For DATASET(S), MODEL and FOLDER only. Should this parameter show elements from other projects?

Example

{
  "type": "DATASET",
  "name": "mydataset",
  "label": "Dataset to analyse"
},
{
  "type": "DATASET_COLUMN",
  "name": "mycolumn",
  "datasetParamName": "mydataset"
  "label": "Column in the dataset to analyse"
}

Selecting columns in plugin recipes

In recipes, it’s common to want to select one or several columns from one of the input datasets. This is done using parameter types:

  • COLUMN: Select exactly one column
  • COLUMNS: select one or more columns

You will need to give the name of the role from which you want to select a column using columnRole field. Note that if the given role is multi-dataset, only the columns from the first dataset will be displayed.

Example:

{
  "name": "incol",
  "label": "Input column",
  "type": "COLUMN",
  "columnRole": "input_role_1"
}

Structured parameters

  • MAP: A (key -> value) mapping
  • KEY_VALUE_LIST: A list of (key -> value). Similar to MAP but with an order

Separators

Finally, there is a special parameter type called SEPARATOR, used just for display purposes to separate the form into sections.

Conditional parameters

Using visibilityCondition

Using visibilityCondition with a Boolean type

For example, the following JSON definition of the parameters :

"params": [
  {
    "name": "sep1",
    "label": "Authentication",
    "type": "SEPARATOR"
  },
  {
    "name": "useToken",
    "label" : "Authenticate with token",
    "type": "BOOLEAN"
  },
  {
    "name": "username",
    "label" : "Login",
    "type": "STRING",
    "visibilityCondition" : "!model.useToken"
  },
  {
    "name": "password",
    "label" : "Password",
    "type": "PASSWORD",
    "visibilityCondition" : "!model.useToken"
  },
  {
    "name": "token",
    "label" : "Token",
    "type": "STRING",
    "visibilityCondition" : "model.useToken"
  },
  {
    "name": "sep3",
    "label": "Reads",
    "type": "SEPARATOR"
  },
  {
    "name": "fetchSize",
    "label" : "Fetch size",
    "type": "INT"
  }
]

produces the following form where the fields Token and Login/Password are shown/hidden depending on the state of the Authenticate with token checkbox:

../../_images/advanced_form_lp.png ../../_images/advanced_form_token.png

Using visibilityCondition with a SELECT type

For example, the following JSON definition of the parameters :

"params": [
  {
      "name": "prediction_type",
      "label": "Regression or Classification",
      "type": "SELECT",
      "selectChoices" : [
          { "value" : "regression", "label" : "Regression"},
          { "value" : "classification", "label" : "Classification"}
      ],
      "mandatory": true
  },
  {
      "name": "target_actual_col",
      "label": "Target Column",
      "type": "COLUMN",
      "columnRole":"input_dataset"
  },
  {
      "name": "prediction_probability_col",
      "label": "Prediction Probabilities Column",
      "type": "COLUMN",
      "columnRole":"input_dataset",
      "visibilityCondition" : "model.prediction_type == 'classification'"
  },
  {
      "name": "probability_threshold",
      "label": "Probability Threshold",
      "type": "DOUBLE",
      "defaultValue" : .5,
      "visibilityCondition" : "model.prediction_type == 'classification'"
  },
  {
      "name": "prediction_col",
      "label": "Predictions Column Name",
      "type": "COLUMN",
      "columnRole":"input_dataset",
      "visibilityCondition" : "model.prediction_type == 'regression'"
  }

],

produces the following form where the fields Prediction Probabilities Column and Probability Threshold are shown if Classification is selected as the prediction type, and Predictions Column Name is shown if Regression is selected:

../../_images/advanced-form-classification.png ../../_images/advanced-form-regression.png

Dynamic select using python

To populate the choices of a select using a python script, you need to:

  • specify a SELECT param with getChoicesFromPython: true
  • create a python file under the resource folder of the plugin (ex: “computechoices.py”) and create a do() function in it that returns a dict with a key “choices”
  • point to the python file form the component json file by specifying paramsPythonSetup: "computechoices.py" (replace with the proper filename)

Example:

webapp.json file:

...
"paramsPythonSetup": "compute_available_time_slots.py"
"params": [
  {
    "type": "SELECT",
    "name": "time_slot",
    "getChoicesFromPython": true
  }
],
...

resource/compute_available_time_slots.py

def do(payload, config, plugin_config, inputs):
  choices = [
    { "value" : "val1", "label" : "Value 1"},
    { "value" : "val2", "label" : "Value 2"}
  ]
  return {"choices": choices}

Fully custom UI

You can specify fully custom HTML/JavaScript, see Other topics

Plugin-level configuration

Just like each dataset and recipe can accept params, so can a plugin. Plugin-level configuration allows you to have a centralized configuration that is shared by all datasets and all recipes instances of this plugin.

Another characteristic of plugin-level config is that it’s only readable and writable by the Administrator. As such, it can be the right place to store API keys, credentials, connection strings, …

Add settings to a plugin

To add settings to a plugin, edit the plugin.json file and add a "params" array in the JSON top-level object. The structure of this params array is similar to the one of datasets and recipes.

Read settings of a plugin

  • Datasets receive the plugin config (as a Python dict) in the constructor of their connector class. See the documentation of the Connector class or the automatically generated sample for more information.
  • Python recipes can read the plugin config (as a Python dict) by calling the dataiku.customrecipe.get_plugin_config() function
  • R recipes can read the plugin config by calling the dataiku::dkuPluginConfig() function