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.
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
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
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
Parameter constraints
Select options
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.typescriptCopied1export default airplane.task(2{3slug: "select-options",4name: "Select Options",5parameters: {6environment: {7type: "shorttext",8name: "Environment",9options: ["production", "development"],1011// With Labels12options: [13{ label: "production", value: "prod" },14{ label: "development", value: "dev" },15],16},17},18}),
pythonCopied1from typing import Annotated2import airplane345@airplane.task(6slug="python_param_options",7name="python-param-options",8)9def python_param_options(10environment: Annotated[11str, airplane.ParamConfig(options=["production", "development"])12],1314# With Labels15environment: Annotated[16str,17airplane.ParamConfig(18options=[19airplane.LabeledOption("production", "prod"),20airplane.LabeledOption("development", "dev"),21]22),23],24):
yamlCopied1slug: select_options2name: Select Options34parameters:5- name: Environment6slug: environment7type: shorttext8options: ["production", "development"]910# With labels11options:12- label: development13value: dev14- label: production15value: prod
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
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:
typescriptCopied1export default airplane.task(2{3slug: "select-options",4name: "Select Options",5parameters: {6bucket: {7type: "shorttext",8name: "Bucket",9options: {10slug: "list_s3_buckets",11params: {12region: "us-east-1",13},14},15},16},17}),
pythonCopied1from typing import Annotated2import airplane345@airplane.task(6slug="python_param_options",7name="python-param-options",8)9def python_param_options(10bucket: Annotated[11str,12airplane.ParamConfig(13options=airplane.TaskOption(14slug="list_s3_buckets",15params={"region": "us-east-1"},16),17),18],19):
yamlCopied1slug: select_options2name: Select Options34parameters:5- name: Bucket6slug: bucket7type: shorttext8options:9slug: list_s3_buckets10params:11region: us-east-1
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
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
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:
typescriptCopied1export default airplane.task(2{3slug: "select-options",4name: "Select Options",5parameters: {6environment: {7type: "shorttext",8name: "Environment",9options: ["production", "development"],10},11release_name: {12type: "shorttext",13name: "Release name",14validate: `15params.environment === "production" && !params.release_name.startsWith("prod-")16? "Production release names must start with prod-"17: null;18`,19},20},21}),
pythonCopied1from typing import Annotated2import airplane34@airplane.task(5slug="python_param_options",6name="python-param-options",7)8def python_param_options(9environment: Annotated[10str,11airplane.ParamConfig(12options=["production", "development"],13validate="params.environment === 'production' && !params.release_name.startsWith('prod-') ? 'Production release names must start with prod-' : null"14)15],16):
yamlCopied1slug: select_options2name: Select Options34parameters:5- name: Environment6slug: environment7type: shorttext8options: ["production", "development"]9- name: Release name10slug: release_name11type: shorttext12validate: |13params.environment === "production" && !params.release_name.startsWith("prod-")14? "Production release names must start with prod-"15: null;
Multi parameters
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.
typescriptCopied1export default airplane.task(2{3slug: "multi_example"4parameters: {5multi_param: {6type: "shorttext",7multi: true,8},9},10},11async (params) => {12console.log(params.multi_param); // string[]13}14);
pythonCopied1from typing import List23import airplane45@airplane.task()6def multi_example(multi_param: List[str]):7print(multi_param)
For all other tasks (Shell, SQL, REST), add parameters to your task definition file. For example:
yamlCopied1parameters:2- name: Multi param3slug: multi_param4type: shorttext5multi: true
Input UI
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 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:
Multi | Options | Input type |
---|---|---|
✅ | ✅ | Multi-select dropdown |
✅ | ❌ | Free-form multi input |
❌ | ✅ | Single-select dropdown |
❌ | ❌ | Free-form single input |
Constraints
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
Values passed to tasks
Multi parameters will be converted to a native data type or a string, depending on the task kind:
Task kind | JSON parameter type |
---|---|
JavaScript | Array |
Python | List |
Shell | string (JSON serialized array, e.g. '["foo", "bar"]') |
Docker | string (JSON serialized array, e.g. '["foo", "bar"]') |
SQL | string (JSON serialized array, e.g. ["foo", "bar"]) |
REST | URL: string (JSON serialized array, e.g. ["foo", "bar"]) Headers: One header per element Query param: string (e.g. [foo+bar]) |
GraphQL | Operation: 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:
bashCopied1echo {{params.multi_param.join(",")}}
Hidden
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
:typescriptCopied1export default airplane.task(2{3slug: "hidden",4name: "Hidden",5parameters: {6country: {7type: "shorttext",8name: "Country",9options: ["US", "CA"],10},11state: {12type: "shorttext",13name: "State",14hidden: 'params.country !== "US"',15},16},17}),
pythonCopied1from typing import Annotated2import airplane34@airplane.task(5slug="hidden",6name="Hidden",7)8def python_param_options(9country: Annotated[10str, airplane.ParamConfig(options=["US", "CA"])11],12state: Annotated[13str, airplane.ParamConfig(14hidden='params.country !== "US"'15)16],17):
yamlCopied1slug: hidden2name: Hidden34parameters:5- name: Country6slug: country7type: shorttext8options: ["US", "CA"]9- name: State10slug: state11type: shorttext12hidden: "params.country !== 'US'"
Parameter types
Parameter types
Parameters come in various types. Currently, the following types are supported:
Short text
Short text
This is your commonly used "string" input:
Long text
Long text
This is a string, but with a larger input box for users:
SQL
SQL
SQL inputs are similar to Long Text inputs but offer SQL syntax highlighting:
Boolean
Boolean
Booleans are presented as on/off toggles:
Integer
Integer
Float
Float
Floats allow both whole numbers and decimals:
File
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}
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
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
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
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}
JSON
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 kind | JSON parameter type |
---|---|
JavaScript | number | string | []JSONValue | { [x: string]: JSONValue } | boolean | null |
Python | Union[int, float, str, List[Any], Dict[str, Any], bool, None] |
Shell | string |
Docker | string |
SQL | string |
REST | number | string | []JSONValue | { [x: string]: JSONValue } | boolean | null |
GraphQL | number | string | []JSONValue | { [x: string]: JSONValue } | boolean | null |