Plugin author reference guide

This reference guide supposes that you have already skimmed through the Writing your own plugin and the howtos referenced from here.

Dataset and recipe params

Both datasets and recipes 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. Allowed types are:

    • STRING: A simple string
    • INT: An integer.
    • DOUBLE: A decimal
    • BOOLEAN: A boolean
    • PASSWORD: A simple string, but the UI hides the typing
    • SELECT: Select a value among possible choices. See below.
    • COLUMN: For recipes only, select one column among the columns of an input dataset. See below.
    • COLUMNS: For recipes only, seleect multiple columns among the columns of an input dataset. See below.
    • MAP: A key -> value mapping
    • TEXTAREA: A string, but the UI shows a multi-line “textarea” control. Good for entering long and multi-line values.
  • label: The user-visible name that appears in the form.

  • description: user-visible additional help, appears at the right of the form

  • defaultValue: prefill value of the parameter. Type must match the field type.

  • mandatory (boolean): Is this parameter required ?

  • columnRole: For COLUMN and COLUMNS only. See below

  • selectChoices: For SELECT only. See below.

Important notes:

  • 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)

Selects

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.

For example:

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

Selecting input columns (for recipes only)

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

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

You declare it like that:

{
        "name" : "incol",
        "label" : "Input column",
        "type" : "COLUMN",
        "columnRole" : "in_role_1"
}
  • If you use COLUMN, you get the answer as a string
  • If you use COLUMNS, you get the answer as a list.

Recipe roles

Each role has the following structure:

  • name: Name of the role, how it’s referenced
  • arity: UNARY or NARY (can accept one or multiple values?)
  • required (boolean, default false): Does this role need to be filled?
  • acceptsDataset (boolean, default true)
  • acceptsManagedFolder (boolean, default false)

Plugin 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

Managing dependencies

Packages

Python and R dependencies (packages) are not managed by DSS: the user must ensure that the DSS Python or R environment has the necessary packages.

DSS can however inform the user about dependencies: to do so, add a requirements.json file at the root of the plugin (besides the plugin.json file). This file is simply a declaration of the required packages, which is presented to the administrator as soon as he installs the plugin.

A requirements.json file looks like this:

{
    "python" : [
        {"name":"pandas", "version":">=0.16.2"},
        {"name":"sqlalchemy", "version":">=0.1"}
    ],
    "R" : [
        {"name":"dplyr", "version":"1.0.0"}
    ]
}

Shared code

requirements.json work for “standard” packages that are available in repositories. However, you also often want to share some code between multiple datasets and recipes of the same plugin.

For these files, you can create a python-lib/ folder at the root of the plugin. This folder is automatically added to the PYTHONPATH of all custom recipes and datasets of this plugin.

For an example of that, you can have a look at the code of our Pipedrive connector .

Resource files

You may also create a resource folder at the root of your plugin (besides the plugin.json file) to hold resource files of your plugin (for example, data files).

to hold resources useful fo your plugin, e.g. data files.

This resource folder is meant to be read-only. To get the path of the resource folder: