JavaScript task configuration

Configure a task's metadata as code
Task configuration defines the core metadata of an Airplane task; this includes all information like the task name and parameters aside from the actual code that is executed when the task is run.
Defining tasks as code is advantageous because it allows you to reap the benefits of version control; you can view the current state of a task and its history, subject tasks to the same code review and deploy mechanisms as the rest of your codebase, or roll back a task to a previous commit.
Task configuration was previously accomplished using a yaml-based task definition. This new, inline task configuration allows tasks to be configured and developed in the same JavaScript file.
To migrate from a task definition to a single-file task configuration, run airplane tasks init --from=my_slug and then copy/paste the code body into the newly created .airplane.ts file.

Writing tasks

To define a task, the JavaScript SDK provides a function airplane.task(...), which takes two parameters: the task configuration and the task implementation.
typescript
Copied
1
// my_task.airplane.ts
2
import airplane from "airplane";
3
4
export default airplane.task(
5
// Task configuration
6
{
7
slug: "my_task",
8
name: "My Task",
9
description: "This is my task defined entirely in TypeScript!",
10
},
11
// Task implementation
12
async () => {
13
console.log("Hello World!");
14
},
15
);
Deploying this task creates an Airplane task that prints Hello World! when you run it.
All exported calls to airplane.task(...) will be discovered as tasks. You can even define multiple tasks in the same file by using either the default or named exports for each of your tasks.
Airplane will only discover tasks that are exported from files ending in .airplane.js, .airplane.ts, .airplane.jsx, or .airplane.tsx.
typescript
Copied
1
// my_tasks.airplane.ts
2
import airplane from "airplane";
3
4
// Discoverable by Airplane
5
export default airplane.task(
6
{...},
7
async (params) => {...}
8
);
9
10
// Discoverable by Airplane
11
export const mySecondTask = airplane.task(
12
{...},
13
async (params) => {...}
14
);
15
16
// NOT discoverable by Airplane because it isn't exported.
17
const mySecondTask = airplane.task(
18
{...},
19
async (params) => {...}
20
);
When you run airplane deploy, Airplane imports your task files to discover tasks. If you have any code outside of the task implementation function (including code that is imported), this code will also be executed. This allows you to define helper functions, constants, or other code that is shared across tasks, but may also cause unexpected behavior if the code has side effects.
typescript
Copied
1
// my_tasks.airplane.ts
2
import airplane from "airplane";
3
4
// You can share code between tasks by defining it outside of the task implementation function.
5
const getAirplaneTaskName = (slug) => `Airplane task ${slug}`;
6
7
// But be careful! This code will be executed when you run `airplane deploy`.
8
makeApiCall();
9
10
export default airplane.task(
11
{ slug: "my_task", name: getAirplaneTaskName("my_task") },
12
// Task implementation
13
async () => {
14
console.log("Hello World!");
15
},
16
);

Parameters

Parameters are specified in the task configuration as objects, where the key is the parameter slug and the value is the parameter configuration.
typescript
Copied
1
parameters: {
2
id: {
3
type: "shorttext",
4
name: "The team's ID",
5
},
6
}
You can also shorthand parameter configuration by setting the value to the parameter type. This defines a required parameter with slug and name equal to the key.
typescript
Copied
1
parameters: {
2
// The slug and name of the parater are "id".
3
id: "shorttext",
4
}
When you add parameters, you must change your implementation function to accept a params object. If you are using TypeScript, The params object is automatically typed based on your configuration!
The following is a full example of an inline task with parameters:
typescript
Copied
1
// my_task.airplane.ts
2
import airplane from "airplane";
3
4
export default airplane.task(
5
// Task configuration
6
{
7
slug: "my_task",
8
name: "My Task",
9
description: "This is my task defined entirely in JavaScript!",
10
parameters: {
11
// Required integer param with slug "my_int_param" and name "my_int_param"
12
my_int_param: "integer",
13
// Optional shorttext param with slug "my_optional_text_param" that defaults to "Hello!"
14
my_optional_text_param: {
15
type: "shorttext",
16
name: "My optional text param",
17
required: false,
18
default: "Hello!",
19
options: ["Hello!", "Good morning!"],
20
},
21
},
22
},
23
// The function takes a single argument, `params`, which is an object with the two params.
24
// e.g. { my_int_param: 3, my_optional_text_param: "Hello!" }
25
async (params) => {
26
console.log(`${params.my_optional_text_param}, ${params.my_int_param}`);
27
},
28
);

Examples

Attach a resource to a task and create a schedule

typescript
Copied
1
import airplane from "airplane";
2
3
export default airplane.task(
4
{
5
slug: "my_task",
6
parameters: {
7
text: "shorttext"
8
},
9
resources: {
10
// Attach the resource with slug "backend_db" under the alias "db"
11
db: "backend_db"
12
},
13
schedules: {
14
// Create a schedule for this task that runs at midnight each day
15
midnight_daily: {
16
cron: "0 0 * * *",
17
name: "Midnight daily",
18
description: "Runs at midnight each day",
19
paramValues: {
20
text: "text param value"
21
}
22
}
23
}
24
},
25
async (params) => {...}
26
);

Manage granular task permissions in code

typescript
Copied
1
import airplane from "airplane";
2
3
export default airplane.task(
4
{
5
slug: "my_task",
6
permissions: {
7
viewers: { groups: ["support"] },
8
executers: { users: ["jordan@airplane.dev"] },
9
},
10
},
11
async (params) => {...}
12
);
For more details, see Permissions in code.

Pass environment variables to a task and set label constraints for self-hosted agents

typescript
Copied
1
import airplane from "airplane";
2
3
export default airplane.task(
4
{
5
slug: "my_task",
6
envVars: {
7
// Pass an env var with a value
8
MY_ENV_VAR: "MY_ENV_VAR_VALUE",
9
// Pass an env var from a defined config var
10
MY_CONFIG_ENV_VAR: {config: "MY_CONFIG_ENV_VAR_VALUE"}
11
},
12
// Run only on agents with label "region:us-west-2"
13
constraints: {
14
region: "us-west-2"
15
}
16
},
17
async () => {...}
18
);

Require requests for task execution and set a custom timeout

typescript
Copied
1
import airplane from "airplane";
2
3
export default airplane.task(
4
{
5
slug: "my_task",
6
// Set a timeout of 200 seconds
7
timeout: 200,
8
// Require requests to execute
9
requireRequests: true,
10
allowSelfApprovals: false
11
},
12
async () => {...}
13
);

Reference

Task configuration

airplane.task(config, func)
config.slug
REQUIRED
string
A unique identifier that ties this configuration to a task in Airplane. This cannot be changed (a different slug will end up creating a new task). Slugs must:
  • Be fewer than 50 characters long.
  • Use only lowercase letters, numbers and underscores.
  • Start with a lowercase later.
config.name
optional
Default
same value as slug
string

A user-facing name for the task. This can be changed.

config.description
optional
string

A user-facing description for the task. Supports markdown.

config.parameters
optional
Record<string, InputParam>
Tasks can be configured with parameters that will be requested from users before they execute the task. Parameters are expressed as a mapping of slug to parameter. The values will be passed to your function as an object that maps the parameter slug to the corresponding value. For more information, see Parameter configuration.
config.requireRequests
optional
Default
false
boolean

If true, a task must be requested before it can start executing. This disables direct execution, including schedules.

config.allowSelfApprovals
optional
Default
true
boolean

If true, a request can be approved by the requestor.

config.restrictCallers
optional
("task" | "view")[]

The restrict callers execute rule disables direct execution of a task in the web UI and hides the task in the library. This rule can be configured to allow the task to be called from other tasks/runbooks and views.

config.timeout
optional
Default
3600 (1 hour)
number
Limits how long a task can run before it is automatically cancelled. Value is in seconds. For more information, see timeouts.
config.allowCachedMaxAge
optional
number
If set, runs with identical inputs within the configured age (in seconds) may get cached results. For more information, see server-side task caching.
config.constraints
optional
Record<string, string>
Restricts this task to run only on agents with matching labels. For more information, see Run constraints.
config.schedules
optional
Record<string, Schedule>
A map from schedule slug to a schedule that automatically runs the task on a recurring cadence. For more information, see Schedule configuration.
config.resources
optional
string[] | Record<string, string>
A list of resources to attach to this task. Once attached, a resource can be used to call Built-ins. The resource's fields can also be accessed via the AIRPLANE_RESOURCES environment variable. For more information, see resource attachments.
config.webhooks
optional
string[] | Record<string, {requireAirplaneToken: boolean}>
A list of webhooks that can be used to trigger this task.
config.runtime
optional
Default
standard
"standard" | "workflow"
The runtime that the task is executed with. The workflow runtime is currently only supported by JavaScript tasks. For more information, see Runtimes.
config.envVars
optional
Record<string, string> | Record<string, {config: string}> | Record<string, {value: string}>
Environment variables that will be passed into the task. For secrets or values that are shared across multiple tasks, environment variables can load their value from config variables.
config.permissions
optional
"team_access" | ExplicitPermissions
Configure who has access to the task. Permissions can either be omitted to manage permissions in the UI, set to "team_access" to allow full access to everyone on the team, or defined with explicit granular permissions. For more information, see Permissions.
config.defaultRunPermissions
optional
"task-viewers" | "task-participants"
Manage who can view new runs of this task. For more information, see Run and session permissions.
config.outputDisplay
optional
CodeOutputDisplay | DescriptionListOutputDisplay | JSONOutputDisplay | FileOutputDisplay | JSONOutputDisplay | StatisticOutputDisplay | TableOutputDisplay | TextOutputDisplay
Configure how the task run's output is displayed. For more information, see Output display configuration.
func
REQUIRED
(params: ParamValues) => Promise<TOutput>

The implementation of the task.

Parameter configuration

type ParameterInput
type
REQUIRED
shorttext | longtext | sql | boolean | integer | float | date | datetime
Parameter type
name
optional
Default
parameter slug
string

A human-readable name that identifies this parameter.

description
optional
string

A description that renders underneath the parameter.

required
optional
Default
true
boolean

Whether a non-empty value must be provided.

multi
optional
Default
false
boolean
Whether the parameter is a list parameter or not. See Multi parameters for more information.
default
optional
string

If a value is not provided for this parameter, the default value will be used instead.

regex
optional
string
A regular expression to validate the provided string value. Only valid for shorttext and longtext parameters.
validate
optional
string

A validation function that returns a string if the value is invalid, or null if the value is valid. The function is evaluated as a JS template and can refer to other parameters by using the params keyword.

options
optional
string[] | {label: string, value: string}[] | {slug: string, params?: Record<string, any>}[]
If included, only values from the provided list will be accepted. An optional label can be provided for each option to override how these options are rendered in forms. Only valid for shorttext, longtext, sql, integer, float, date, and datetime parameters. The values can either be hardcoded, or can be dynamically generated by a task by providing a slug and optional params. For more information, See Task-backed select options for more information.
hidden
optional
string

An expression that hides the param if it evaluates to a truthy value. The expression is evaluated as a JS template and can refer to other parameters by using the params keyword.

Schedule configuration

type Schedule
cron
REQUIRED
string
Cron string of the schedule. To see acceptable formats, see Cron syntax.
name
optional
Default
schedule slug
string

Name of the schedule.

description
optional
string

Description of the schedule.

paramValues
optional
Record<string, InputParamValues>

Map of param slug to value to pass to the task on each run.

Permissions configuration

Configure who has access to the task. Permissions can either be omitted to manage permissions in the UI, set to "team_access" to allow full access to everyone on the team, or defined with explicit granular permissions.
You can assign granular viewer, requester, executer, and/or admin access to groups or users. Groups are referenced by slug, and users are referenced by email. For more information, see the reference below.
type ExplicitPermissions
viewers
optional
{ users?: string[], groups?: string[] }

Groups and users who can see task information, but can't request or execute tasks.

requesters
optional
{ users?: string[], groups?: string[] }

Groups and users who have all the permission of viewers, and can also request tasks.

executers
optional
{ users?: string[], groups?: string[] }

Groups and users who have all the permissions of requesters, and can also execute tasks and other's requests.

admins
optional
{ users?: string[], groups?: string[] }

Groups and users who have full access to the task, and can change task configurations and permissions.

Output display configuration

Configure a task's output display to change how the task run's output is displayed. By default, a task run's output is displayed as a table. You can change this to one of many display types: code, description list, file, JSON, statistic, table, or text.
For more information on output displays, also see the output display docs.

Code

Code is a syntax-highlighted code block.

type CodeOutputDisplay
type
REQUIRED
"code"

Indicates that the output should be displayed as a code block.

language
optional
Default
plaintext
string

Language to use for syntax highlighting.

Description list

Description list is a list of term and description pairs (aka key and value pairs).

type DescriptionListOutputDisplay
type
REQUIRED
"descriptionList"

Indicates that the output should be displayed as a description list.

value
optional
string

Value of the display.

The value should be a JST that evaluates to the expected format of a description list, which is a list of objects with term anddescription fields. The JST can reference the output of the task.

File

File is a file preview. File requires the output to be an Airplane file.

type FileOutputDisplay
type
REQUIRED
"file"

Indicates that the output should be displayed as a file preview.

JSON

JSON is a syntax-highlighted JSON block.

type JSONOutputDisplay
type
REQUIRED
"json"

Indicates that the output should be displayed as a JSON block.

Statistic

Statistic is a simple display designed to prominently display quantifiable metrics so that users can easily discern key information at a glance.

type StatisticOutputDisplay
type
REQUIRED
"statistic"

Indicates that the output should be displayed as a statistic block.

value
optional
string

Value of the display.

The value can be a JST that can reference the output of the task. If not set, the value will be the output of the task.

label
optional
string

Label of the display.

The label can be a JST that can reference the output of the task.

sublabel
optional
string

Sublabel of the display.

The sublabel can be a JST that can reference the output of the task.

Table

Table is a rich, interactive table.

type TableOutputDisplay
type
REQUIRED
"table"

Indicates that the output should be displayed as a table.

value
optional
string

Value of the display.

The value should be a JST that evaluates to the expected format of a table, which is a list of objects with fields corresponding to the columns. The JST can reference the output of the task. If not set, the value will be the output of the task.

columns
optional
{ label: string; accessor: string }[]

Columns of the table.

label is what's displayed as the column header. accessor indicates which field of the table value should be used for this column. If not set, the columns will be inferred from the output of the task.

Text

Text is component that displays plain text. Text also supports Markdown formatting.

type TextOutputDisplay
type
REQUIRED
"text"

Indicates that the output should be displayed as text.

value
optional
string

Value of the display.

The value can be a JST that can reference the output of the task. If not set, the value will be the output of the task.

YAML reference (deprecated)

Task configuration was previously accomplished using a yaml-based task definition. We recommend migrating to the new, inline task configuration allows tasks to be configured and developed in the same JavaScript file.
To migrate from a task definition to a single-file task configuration, run airplane tasks init --from=my_slug and then copy/paste the code body into the newly created .airplane.ts file.

Standard fields

The fields below apply to all task definitions, regardless of the type of task.
slug
string
REQUIRED
A unique identifier that ties this definition file to a task in Airplane. This cannot be changed (a different slug will end up creating a new task).
Slugs must:
  • Be fewer than 50 characters long
  • Use only lowercase letters, numbers, and underscores
  • Start with a lowercase letter
name
string
REQUIRED
User-facing name for the task. This can be changed.
User-facing description for the task. This can be changed.
A list of parameters. Each parameter is a user-facing field to input data into the task.
Example:
yaml
Copied
1
parameters:
2
- slug: name
3
name: Name
4
type: shorttext
5
description: The user's name.
6
default: Alfred Pennyworth
7
required: false
8
options:
9
- Alfred Pennyworth
10
- Bruce Wayne
11
regex: "^[a-zA-Z ]+$"
parameters.slug
string
REQUIRED
Unique identifier for the parameter. This is the identifier you'll use to interpolate parameters into arguments, pass them when calling from the CLI, etc.
parameters.name
string
REQUIRED
User-facing name for the parameter.
parameters.type
enum
REQUIRED
Possible Values
shorttextYour commonly used string input
longtextA string, but with a larger input box for users
sqlSimilar to Long Text inputs but offer SQL syntax highlighting
booleanPresented as on/off toggles
uploadAllows users to upload a file
Show more
The type of the parameter. See Parameter types for more information.
User-facing description of the parameter.
parameters.required
boolean
Default
true
Whether the parameter is required.
parameters.multi
boolean
Default
false
Whether the parameter is a list parameter or not. See Multi parameters for more information.
parameters.default
string/number/boolean
The default value of the parameter. The type depends on the type of the parameter.
parameters.options
list of string/number/boolean/object
Constrains the value of parameter to a list of options.
The type depends on the type of the parameter.
You can optionally add a label to each option. Labels are shown to the user instead of the value. To add a label, the option should be an object with fields label and value.
Example:
yaml
Copied
1
options:
2
- Alfred Pennyworth
3
- Bruce Wayne
4
- label: BW
5
value: Bruce Wayne
For more information, see Select options.
Allows you to more dynamically control what values are permitted. For more information, see Regular expressions.
requireRequests
boolean
Default
false
If true, a task must be requested before it can start executing. This disables direct execution, including schedules.
Requiring requests will disable schedules. Any existing schedules will be paused on the next attempted execution.
allowSelfApprovals
boolean
Default
true
If true, a request can be approved by the requestor.
restrictCallers
list of strings ("task" or "view")
Default
[]
The restrict callers execute rule disables direct execution of a task in the web UI and hides the task in the library. This rule can be configured to allow the task to be called from other tasks/runbooks and views.
timeout
number (in seconds)
Default
3600 (1 hour)
Limits how long a task can run before it is automatically cancelled.
Maximum of 43200 (12 hours)
For more information, see timeouts.
allowCachedMaxAge
number (in seconds)
If set, runs with identical inputs within the configured age (in seconds) may get cached results.
For more information, see server-side task caching.
Restricts this task to run only on agents with matching labels.
Example:
yaml
Copied
1
constraints:
2
aws-region: us-west-2
For more information, see Run constraints.
schedules
object
Mapping of unique identifiers to schedules that should be deployed with the task.
For more information, see Schedules.
Example:
yaml
Copied
1
schedules:
2
my_first_schedule:
3
cron: 0 0 * * *
4
name: My First Schedule
5
description: This is my first daily midnight UTC schedule!
6
paramValues:
7
my_first_param: my_first_param_value
The unique identifier is used to add, update and remove schedules as changes are made to the task definition file. Adding a new entry will create a new schedule, modifying an entry will update the schedule and removing an entry will pause the schedule.
The unique identifier must adhere to the slug format.
schedules.cron
string
REQUIRED
Cron string of the schedule. To see acceptable formats, see Cron syntax.
Name of the schedule.
Description of the schedule.
Map of param slugs and values to pass to the task on each run.
resources
object
Mapping of resource aliases to resource slugs. Slugs for your resource can be found in the resource settings.
For more information on resource attachments, see resource attachments.
Example:
yaml
Copied
1
resources:
2
db: prod_postgres_db
If you would like to use the resource slug as the alias for all resources passed into this task, you can also use a list shorthand:
yaml
Copied
1
resources:
2
- prod_postgres_db
3
- prod_rest_api
webhooks
`list of strings` or `object`
An object whose keys are webhook slugs and values are webhook settings. As a shorthand, you can also use a list of webhook slugs. Each slug is a unique identifier that must adhere to the slug format.
Possible Values
standard
workflow
The runtime that the task will execute within. Defaults to standard.
The workflow runtime is currently only supported by JavaScript tasks. For more information, see Runtimes.
permissions
object or "team_access"
Configure who has access to the task. Permissions can either be omitted to manage permissions in the UI, set to "team_access" to allow full access to everyone on the team, or defined with explicit granular permissions.
For more information, see Permissions.
Example:
yaml
Copied
1
permissions: "team_access"
If you want to define granular permissions, you can assign viewer, requester, executer, and/or admin access to groups by slug or to users by email.
yaml
Copied
1
permissions:
2
viewers:
3
groups:
4
- customer_success
5
users:
6
- success@airplane.dev
7
requesters:
8
groups:
9
- support
10
users:
11
- support@airplane.dev
12
executers:
13
groups:
14
- devs
15
admins:
16
groups:
17
- team_admins
Once permissions are defined in code for a task, they will no longer be editable in the UI until the task is deployed again without the permissions field.
Groups and users who can see task information, but can't request or execute tasks.
Groups and users who have all the permission of viewers, and can also request tasks.
Groups and users who have all the permissions of requesters, and can also execute tasks and approve others' requests.
Groups and users who have full access to the task, and can change task configurations and permissions.
defaultRunPermissions
enum
Default
task-viewers
Possible Values
task-viewersAnyone who can view the task can also view the run.
task-participantsCan only be viewed by those who execute, request, or approve the run.
Manage who can view new runs of this task.

JavaScript

node
object
Marks the task as a JavaScript task.
Example:
yaml
Copied
1
node:
2
entrypoint: my_task.ts
3
nodeVersion: "18"
node.entrypoint
string
REQUIRED
The path to the .ts or .js file containing the logic for this task. This can be absolute or relative to the location of the definition file.
Examples:
yaml
Copied
1
entrypoint: my_folder/my_task.ts
node.nodeVersion
enum
REQUIRED
Possible Values
14
16
18
20
The version of Node.js that the task should be executed with.
This field has no effect on tasks that use the workflow runtime. For more information, see Runtimes.
Environment variables that will be passed into the task.
Environment variables can be entered directly ("from value"), or you can reference Config variables ("from config variable"). Use config variables for secrets and/or values you want to share across multiple tasks.
Example:
yaml
Copied
1
envVars:
2
# From value
3
NODE_ENV:
4
value: production
5
# From config variable
6
MY_SECRET:
7
config: MY_SECRET_CONFIG_VAR