Parameters

Parameters allow you to prompt users for input before triggering your task or runbook.
Before a runbook or task is executed, you can request input from your users in the form of parameters. Parameters can be defined when creating and editing your runbook or task.
Add parameters to your task definition file (only supported for task parameters, not runbooks).
yaml
Copied
1
# your_task.task.yaml
2
parameters:
3
- name: User email
4
slug: user_email
5
type: shorttext
6
description: 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 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 Node.js receive the parameters as a JSON object keyed by task slug, e.g. {"name": "some name"}.

Interpolation

Generally, Airplane performs an "interpolation" step via JavaScript templates when running a task or runbook 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

Number

Numbers are essentially floats, allowing 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:
javascript
Copied
1
export default async function (params) {
2
// Extract the "url" field from the file parameter:
3
const url = params.example_file.url;
4
console.log(`File URL: ${url}`);
5
6
// Download the file and print to stdout:
7
const resp = await fetch(url);
8
const body = await resp.text();
9
console.log(body);
10
}

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 Node 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
}