REST task configuration
Configure a task's metadata as code
Task configuration defines the core metadata of an Airplane task in a .task.yaml
or .task.json
task definition file; this includes all information like the task name and parameters aside from the
actual code that is executed when the task is run.
While tasks can be configured in the cloud using
Studio with cloud workspaces, 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.
If you do edit the task in a cloud workspace, you can rerun
airplane tasks init --from YOUR_TASK_SLUG path/to/defn.task.yaml
to sync changes back to your task
definition file.
The following is a complete reference of fields supported in .task.yaml
or .task.json
task
definition file.
The fields below apply to all task definitions, regardless of the type of task.
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
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:
5
description: The user's name.
6
default: Alfred Pennyworth
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.
User-facing name for the parameter.
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 |
User-facing description of the parameter.
Whether the parameter is required.
Whether the parameter is a list parameter or not. See
Multi parameters for more information.
The default value of the parameter. The type depends on the type of the parameter.
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:
Allows you to more dynamically control what values are permitted.
For more information, see
Regular expressions.
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.
If true, a request can be approved by the requestor.
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.
Limits how long a task can run before it is automatically cancelled.
Maximum of 43200
(12 hours)
If set, runs with identical inputs within the configured age (in seconds) may get cached results.
Restricts this task to run only on agents with matching labels.
Example:
Mapping of unique identifiers to schedules that should be deployed with the task.
Example:
4
name: My First Schedule
5
description: This is my first daily midnight UTC schedule!
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.
Cron string of the schedule. To see acceptable formats, see
Cron syntax.
Description of the schedule.
Map of param slugs and values to pass to the task on each run.
Mapping of resource aliases to resource slugs. Slugs for your resource can be found in the
resource settings.
Example:
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:
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.
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.
Example:
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.
11
- support@airplane.dev
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.
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.
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.
Possible Values |
CodeCode is a syntax-highlighted code block. Indicates that the output should be displayed as a code block. Language to use for syntax highlighting. List of actions to show above the output. Actions become buttons with the corresponding label , linking to an entity according to the method specified by as or opening a link from the href . as defaults to "side_peek". A maximum of 3 actions are shown. Any of the configuration fields can take in a JST that can reference the output of the task. |
Description listDescription list is a list of term and description pairs (aka key and value pairs). Indicates that the output should be displayed as a description list. 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. List of actions to show above the output. Actions become buttons with the corresponding label , linking to an entity according to the method specified by as or opening a link from the href . as defaults to "side_peek". A maximum of 3 actions are shown. Any of the configuration fields can take in a JST that can reference the output of the task. |
FileFile is a file preview. File requires the output to be an Airplane file. Indicates that the output should be displayed as a file preview. List of actions to show above the output. Actions become buttons with the corresponding label , linking to an entity according to the method specified by as or opening a link from the href . as defaults to "side_peek". A maximum of 3 actions are shown. Any of the configuration fields can take in a JST that can reference the output of the task. |
Show more |
Marks the task as a REST task.
Examples:
POST
4
path: "/users/{{params.user_id}}/update"
7
name: "{{params.user_name}}"
GET
4
path: "/users/{{params.user_id}}"
The slug of a REST API resource. If you don't have an existing resource, visit
the
Resources settings page
to add a new resource.
Possible Values |
GET |
POST |
PATCH |
PUT |
DELETE |
The HTTP method to use.
The path to request. Your REST resource may specify a path prefix as part
of its base URL, in which case this path is joined to it. Airplane
recommends that this start with a leading slash.
A key value map from param name to value.
Example:
2
name: "{{params.user_name}}"
A key value map from header name to value.
Example:
1
My-Custom-Header: "{{params.header_value}}"
Possible Values |
json |
raw |
form-data |
x-www-form-urlencoded |
The type of body that this request should send.
The body of the request for a request of method POST
, PUT
or PATCH
.
This field is required when bodytype
is json
or raw
.
Example:
4
email: "{{params.user_email}}"
The form data of the request for a request of method POST
, PUT
or PATCH
.
This field is required when bodytype
is form-data
or x-www-form-urlencoded
.
Example:
4
email: "{{params.user_email}}"
If true, the request will be retried if the server returns a 500, 502, 503, or 504 error code. Requests will always be retried on 408 and 429 error codes. This field supports JS templates.
The configs attached to this task. See
Config variables for more details on how to use config variables in your task.
Example: