Parameters

Parameters allow you to prompt users for input before triggering your task.
Before a task is executed, you can request input from your users in the form of parameters. Parameters can be defined when creating and editing your task.
typescript
Copied
1
// my_task.airplane.ts
2
export default airplane.task(
3
  {
4
    slug: "my_task"
5
    parameters: {
6
      user_email: {
7
        type: "shorttext",
8
        name: "User email",
9
        description: "The email address of the user",
10
      },
11
    },
12
  },
13
  async (params) => {
14
    console.log(`Email ${params.user_email}`);
15
  }
16
);
See Parameter configuration for a full reference on available parameters.

Parameter slugs
A slug is a human-friendly identifier for your parameter, which you can reference later. For example:
  • SQL tasks can pass in parameters using query args, e.g. SELECT name FROM users WHERE id = :id where id is a query arg tied to a parameter.
  • Docker Image tasks can interpolate parameters into the Docker command, e.g. echo {{params.name}}.
  • REST tasks can interpolate parameters into the URL, query parameters, headers, and more.
  • Custom code tasks like JavaScript receive the parameters as a JSON object keyed by task slug, e.g. {"name": "some name"}.
Slugs must:
  • Be fewer than 50 characters long
  • Use only lowercase letters, numbers, and underscores
  • Start with a lowercase letter

Interpolation
Generally, Airplane performs an "interpolation" step via JS templates when running a task with parameters, where the values a user has entered are translated and fed into the task code. This interpolation logic will differ depending on the parameter type (see below) and the task type (see the various type-specific docs for details).

Parameter constraints

Select options

 
typescript
Copied
1
export default airplane.task(
2
  {
3
    slug: "select-options",
4
    name: "Select Options",
5
    parameters: {
6
      environment: {
7
        type: "shorttext",
8
        name: "Environment",
9
        options: ["production", "development"],
10


11
        // With Labels
12
        options: [
13
          { label: "production", value: "prod" },
14
          { label: "development", value: "dev" },
15
        ],
16
      },
17
    },
18
  }),
Supported types: short text, long text, sql, integer, number, date, date & time, config variable, json.
Select options (aka "dropdowns" or "enums") allow you to specify exactly which values are allowed for a given parameter.
For example, you can specify a short text "Environment" parameter with production or development as two options.
You can optionally add a label to each option. Labels are shown to the user instead of the value. This is helpful if you want to show the user one thing (e.g. a customer name) but pass a different value to your task (e.g. a customer ID).

Templated options
If you are creating parameters for a form block, you can also dynamically generate a list of options from a previous block's output by using a JS template.

Regular expressions
Supported types: short text, long text, sql, config variable.
Regular expressions allow you to more dynamically control what values are permitted. For most string values, regular expressions will match against the value itself. For config variables, regular expressions will match against the name of the config variable (not the value).
Expressions must match the entire value. For example, an expression of plan.* will match plane but not airplane.
Example constraint settings for a parameter.
Example constraint settings for a parameter.

Multi parameters
Multi parameters allow passing in multiple values of the same type for a single parameter. This functionality is supported for all parameter types.
typescript
Copied
1
export default airplane.task(
2
  {
3
    slug: "multi_example"
4
    parameters: {
5
      multi_param: {
6
        type: "shorttext",
7
        multi: true,
8
      },
9
    },
10
  },
11
  async (params) => {
12
    console.log(params.multi_param); // string[]
13
  }
14
);

Input UI
Multi parameters support free-form list input or multi-select functionality when used in conjuction with select options:
Example multi parameter without select options.
Example multi parameter without select options.
Example multi parameter with select options.
Example multi parameter with select options.
To summarize, depending on whether the parameter is a multi parameter and/or select options are enabled, the input form will render in a different format:
MultiOptionsInput type
✅✅Multi-select dropdown
✅❌Free-form multi input
❌✅Single-select dropdown
❌❌Free-form single input

Constraints
Parameter constraints are applied to each individual value that is passed in. This means that each value must pass select option and/or regex validation, if applicable.

Values passed to tasks
Multi parameters will be converted to a native data type or a string, depending on the task kind:
Task kindJSON parameter type
JavaScriptArray
PythonList
Shellstring (JSON serialized array, e.g. '["foo", "bar"]')
Dockerstring (JSON serialized array, e.g. '["foo", "bar"]')
SQLstring (JSON serialized array, e.g. ["foo", "bar"])
RESTURL: string (JSON serialized array, e.g. ["foo", "bar"])
Headers: One header per element
Query param: string (e.g. [foo+bar])
GraphQLOperation: string (JSON serialized array), e.g. ["foo", "bar"]
Headers: One header per element
Query param: string (e.g. [foo+bar])
Variables: Array
Note that when using multi parameters in a JS template, you can control how the values are passed in. For example, to pass in a comma separated list of values into a Docker task, you can use the following:
bash
Copied
1
echo {{params.multi_param.join(",")}}

Parameter types
Parameters come in various types. Currently, the following types are supported:

Short text
This is your commonly used "string" input:

Long text
This is a string, but with a larger input box for users:

SQL
SQL inputs are similar to Long Text inputs but offer SQL syntax highlighting:

Boolean
Booleans are presented as on/off toggles:

Integer

Float
Floats allow both whole numbers and decimals:

File
The file type allows users to upload files from the web interface:
Uploads are a great way to allow users to upload CSVs and other files as inputs to scripts from the web UI. At the moment, uploads are limited to the web UI and aren't supported in Slack or CLI.
File uploads are serialized as an object when passed to tasks:
json
Copied
1
{
2
  "__airplaneType": "upload",
3
  "id": "upl20220609zlqsu3b4a1g",
4
  "url": "https://storage.googleapis.com/airplane-external-f4aeab0/file-params/upl20220609zlqsu3b4a1g/atc.jpeg?<...credentials...>"
5
}
This object includes a signed URL that can be used to access the uploaded file. An HTTP GET to this URL will respond with the uploaded file encoded as a byte stream in the response's body.
For example, this file can be accessed from a task like so:
typescript
Copied
1
import { AirplaneFile } from "airplane";
2


3
export default async function (params) {
4
  const file = new AirplaneFile(params.example_file);
5


6
  // Download the file and print to stdout:
7
  const body = await file.text();
8
  console.log(body);
9
}

Date
Dates allow users to pick a value from a datepicker. Dates are serialized as strings, with the following format: 2020-03-20.

Date + Time
Date + Time allows users to pick a value from a date and time picker. Date + Time inputs are serialized as ISO8601 timestamps in UTC, such as 2021-03-20T06:02:00.000Z.

Config variable
Config variable parameters allow users to pass in config variables as values into a task. This is especially useful if your task needs to use different configs between runs.
Note that config variables must have select options or regular expressions specified (see parameter constraints). Airplane will not allow unconstrained config variables, as it may potentially allow users unintentional access to team config variables.
When using the config variable in a JS template, note that the config variable is an object with a .name and .value property. Use .value to access the value itself.
json
Copied
1
{
2
  "name": "my_config_var",
3
  "value": "config_var_value"
4
}
For example, you can use config variable parameters in REST tasks:
You can also use them like normal values in JavaScript and Python tasks:
javascript
Copied
1
export default async function (params) {
2
  console.log("config var name:", params.my_config_var.name);
3
  console.log("config var value:", params.my_config_var.value);
4
}

JSON
JSON parameters allow users to pass in any valid JSON value into a task. This is useful for passing in complex data types.
JSON parameters will be converted to a native data type or a string, depending on the task kind.
Task kindJSON parameter type
JavaScriptnumber | string | []JSONValue | { [x: string]: JSONValue } | boolean | null
PythonUnion[int, float, str, List[Any], Dict[str, Any], bool, None]
Shellstring
Dockerstring
SQLstring
RESTnumber | string | []JSONValue | { [x: string]: JSONValue } | boolean | null
GraphQLnumber | string | []JSONValue | { [x: string]: JSONValue } | boolean | null
PrivacyTermsSupport