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.
typescriptCopied1// my_task.airplane.ts2export default airplane.task(3{4slug: "my_task"5parameters: {6user_email: {7type: "shorttext",8name: "User email",9description: "The email address of the user",10},11},12},13async (params) => {14console.log(`Email ${params.user_email}`);15}16);
See Parameter configuration for a full reference on
available parameters.
javascriptCopied1// my_task.airplane.js2export default airplane.task(3{4slug: "my_task"5parameters: {6user_email: {7type: "shorttext",8name: "User email",9description: "The email address of the user",10},11},12},13async (params) => {14console.log(`Email ${params.user_email}`);15}16);
See Parameter configuration for a full reference on
available parameters.
pythonCopied1# my_task_airplane.py2import airplane34@airplane.task()5def my_task(user_email: str):6"""Deletes a user by email.78Args:9user_email: The email address of the user10"""11print(f"Email {user_email}")
See Parameter configuration for a full reference on
available parameters.
For all other tasks (Shell, SQL, REST), add parameters to your task definition file. For example:
yamlCopied1# my_task.task.yaml2parameters:3- name: User email4slug: user_email5type: shorttext6description: The email address of the user
See the task definition reference for full documentation on
configuring parameters in a task definition file.
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
whereid
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 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:
jsonCopied1{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:
typescriptCopied1import { AirplaneFile } from "airplane";23export default async function (params) {4const file = new AirplaneFile(params.example_file);56// Download the file and print to stdout:7const body = await file.text();8console.log(body);9}
javascriptCopied1import { AirplaneFile } from "airplane";23export default async function (params) {4const file = new AirplaneFile(params.example_file);56// Download the file and print to stdout:7const body = await file.text();8console.log(body);9}
pythonCopied1import requests23import airplane45@airplane.task()6def my_task(example_file: airplane.File):7# Extract the "url" field from the file parameter:8file_url = example_file.url9print(f"File URL: {file_url}")1011# Download the file and print to stdout:12response = requests.get(file_url)13print(response.text)
bashCopied1# Given a file parameter with slug "example_file", you can extract the2# signed URL from a Shell task like so:3FILE_URL=$(echo $PARAM_EXAMPLE_FILE | jq -r .url)4echo "File URL: ${FILE_URL}"56# Use curl to download the file and print to stdout:7FILE=$(curl -s ${FILE_URL})8echo ${FILE}
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.jsonCopied1{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:
javascriptCopied1export default async function (params) {2console.log("config var name:", params.my_config_var.name);3console.log("config var value:", params.my_config_var.value);4}
Parameter constraints
Select options
Supported types:
short text
, long text
, sql
, integer
, number
, date
, date & time
,
config variable
.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.