Parameters

Parameters allow you to prompt users for input before triggering your runbook.
Before a runbook is executed, you can request input from your users in the form of parameters. Parameters can be defined when creating and editing your runbook.

Parameter slugs
A slug is a human-friendly identifier for your parameter, which you can reference later. For example:
  • Tasks and builtin blocks in your runbook can accept parameter values via JS templates, e.g. {{ params.value }}.
  • Start conditions can use parameter values to dynamically choose whether to skip a block, e.g. {{ params.name.length > 0 }}.
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 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

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.

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:

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

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. For more information, refer to the form blocks page.

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.
PrivacyTermsSupport