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

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. Rather than allowing users to enter any value, the parameter will appear as a dropdown with only those two 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
}),
Select options are supported for parameters of type: short text, long text, sql, integer, number, date, date & time, config variable, json.
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).

Task-backed select options

Select options can also be backed by a task. This is useful if you want to dynamically generate the options from the output of a task.
For example, if you have a task that lists all available AWS S3 buckets you can use that task to populate the options for a parameter:
typescript
Copied
1
export default airplane.task(
2
{
3
slug: "select-options",
4
name: "Select Options",
5
parameters: {
6
bucket: {
7
type: "shorttext",
8
name: "Bucket",
9
options: {
10
slug: "list_s3_buckets",
11
params: {
12
region: "us-east-1",
13
},
14
},
15
},
16
},
17
}),
The task parameters can be evaluated as a JS template and can refer to other parameters by using the params keyword. e.g. region: {{params.region}}.
The task must return a list of items or a list of objects with value and label fields.

Regular expressions

Regular expressions allow you to 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).
Regular expressions are supported for parameters of type: short text, long text, sql, config variable.

Validate functions

For more control of the logic and error message than regular expressions, you can also specify a custom validate function. A validate function is an expression that returns a string, representing the error, if the value is invalid, or null if the value is valid. The expression is evaluated as a JS template and can refer to other parameters by using the params keyword.
For example, the following validate function ensures that a release name is well formatted based on the environment:
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
release_name: {
12
type: "shorttext",
13
name: "Release name",
14
validate: `
15
params.environment === "production" && !params.release_name.startsWith("prod-")
16
? "Production release names must start with prod-"
17
: null;
18
`,
19
},
20
},
21
}),

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, regex and validate function 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(",")}}

Hidden

Parameters can be conditionally hidden from the user by using the hidden field. This is useful if A parameter only makes sense based on the selection of another parameter. Hidden is evaluated as a JS template and can refer to other parameters by using the params keyword. If hidden evaluates to a truthy value, the parameter will be hidden from the user.
The following example hides the state parameter if the country parameter is not set to US:
typescript
Copied
1
export default airplane.task(
2
{
3
slug: "hidden",
4
name: "Hidden",
5
parameters: {
6
country: {
7
type: "shorttext",
8
name: "Country",
9
options: ["US", "CA"],
10
},
11
state: {
12
type: "shorttext",
13
name: "State",
14
hidden: 'params.country !== "US"',
15
},
16
},
17
}),

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