Prompts

Wait for a response from an operator before continuing
Airplane Prompts are currently in beta, and minor details may change. We'd love to hear any feedback or requests at hello@airplane.dev.
Tasks can easily gather input from operators using prompts. Each prompt contains a parameter form, similar to what you see when executing a task or runbook. When a prompt is created, a run will wait for a response before continuing. Prompts allow you to specify reviewers with with Approvals to build dynamic approval flows.

Example: dry runs
A common use case for prompts is to perform dry-runs. Let's look at an example:
typescript
Copied
1
import airplane from "airplane";
2


3
export default airplane.task(
4
  {
5
    slug: "task_dryrun",
6
  },
7
  async () => {
8
    // Perform a dry-run and show the output to the operator with a display.
9
    const dryRun = await airplane.execute("my_task_slug", {
10
      dry_run: true,
11
    });
12
    await airplane.display.json(dryRun.output);
13


14
    // Ask the operator if we should continue.
15
    await airplane.prompt.confirm({
16
      description: `Review the dry-run output above. If it looks correct, click OK to apply the changes.`,
17
    });
18


19
    // If confirmed, we can re-run:
20
    const run = await airplane.execute("my_task_slug", {
21
      dry_run: false,
22
    });
23


24
    return run.output;
25
  }
26
);
If you've done UNIX scripting before, you have likely seen this pattern using the read command -- e.g.
bash
Copied
1
# perform a dry-run...
2


3
read -p "Continue? [yN] " -n 1 -r
4
echo
5
if [[ $REPLY =~ ^[Yy]$ ]]
6
then
7
    # apply!
8
fi
Compared to the classic shell script, prompts offer a few compelling advantages:
  • Notifications: Users are automatically notified when prompted.
  • Parameters: Prompts can ask for arbitrary parameters with validation.
  • Slack: Prompts can be responded to directly from Slack.

Parameters
Prompt parameters support the same configuration options as task parameters e.g. default values, descriptions, constraints, and more! See Parameters for more information about Airplane parameters.

Short text
Creates a prompt for a short text input.
typescript
Copied
1
const { email } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { email: "shorttext" }
4
);
5
// or
6
const { email } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  email: {
9
    type: "shorttext",
10
    name: "Email address",
11
    // ...
12
  },
13
});
API

Long text
Creates a prompt for a long text input that renders as a multi-line text area.
typescript
Copied
1
const { reason } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { reason: "longtext" }
4
);
5
// or
6
const { reason } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  reason: {
9
    type: "longtext",
10
    name: "Refund reason",
11
    // ...
12
  },
13
});
API

SQL
Creates a prompt for a SQL input that renders within a code editor with SQL syntax highlighting.
typescript
Copied
1
const { query } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { query: "sql" }
4
);
5
// or
6
const { query } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  query: {
9
    type: "sql",
10
    name: "SQL query",
11
    // ...
12
  },
13
});
API

Number
Creates a prompt for a floating point number input.
typescript
Copied
1
const { cost } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { cost: "float" }
4
);
5
// or
6
const { cost } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  cost: {
9
    type: "float",
10
    name: "Amount to charge",
11
    // ...
12
  },
13
});
API

Integer
Creates a prompt for an integer input.
typescript
Copied
1
const { count } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { count: "integer" }
4
);
5
// or
6
const { count } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  count: {
9
    type: "integer",
10
    name: "Record count",
11
    // ...
12
  },
13
});
API

Boolean
Creates a prompt for a boolean input.
typescript
Copied
1
const { ok } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { ok: "boolean" }
4
);
5
// or
6
const { ok } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  ok: {
9
    type: "boolean",
10
    name: "Countinue",
11
    // ...
12
  },
13
});
API

Date
Creates a prompt for a date input. Dates identify a day of the year and do not include a time component. If you need that, see Datetime.
typescript
Copied
1
const { date } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { date: "date" }
4
);
5
// or
6
const { date } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  date: {
9
    type: "date",
10
    name: "Start date",
11
    // ...
12
  },
13
});
API

Datetime
Creates a prompt for a datetime input. If you only need a date, see Date.
typescript
Copied
1
const { timestamp } = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { timestamp: "datetime" }
4
);
5
// or
6
const { timestamp } = await airplane.prompt({
7
  // Mapping of slug -> parameter definition
8
  timestamp: {
9
    type: "datetime",
10
    name: "Incident start",
11
    // ...
12
  },
13
});
API

File
Support for prompts with file parameters is coming soon.

Config variables
Support for prompts with Config variables parameters is coming soon.

Examples

Multi-parameter forms
Create a multi-parameter form by specifying more than one parameter.
typescript
Copied
1
const {amount, reason} = await airplane.prompt(
2
  // Mapping of slug -> parameter definition
3
  { reason: "shorttext" }
4
  { amount: "number" }
5
);
6
// or
7
const {amount, reason} = await airplane.prompt({
8
  // Mapping of slug -> parameter definition
9
  reason: {
10
    type: "shorttext",
11
    name: "Refund reason",
12
    // ...
13
  },
14
  amount: {
15
    type: "float",
16
    name: "Refund amount",
17
    // ...
18
  },
19
});
API

Confirmation
Create a prompt that has no parameters to ask users for confirmation.
typescript
Copied
1
// Convenience helper for prompts with no parameters
2
await airplane.prompt.confirm({ description: "## Please review run before continuing." });
3


4
// Equivalent to
5
await airplane.prompt({}, { description: "## Please review run before continuing." });
API

Select options
Create a prompt for selecting a value from a list of options. Accepts values numbers, strings, booleans, and objects.
typescript
Copied
1
const users = [
2
  { name: "Colin", id: "usr1" },
3
  { name: "Lee", id: "usr2" },
4
];
5
const user = await airplane.prompt.select("User", users, {
6
  optionToLabel: (user) => user.name,
7
});
API

Background prompts
Prompts can be created in the background via prompt.background. When used in combination with the Submit Prompt API endpoint, you are able to able to programatically submit prompts from outside of Airplane's runtime.
typescript
Copied
1
// Create a prompt in the background to get an ID.
2
const myPrompt = await airplane.prompt.background({ deploy_succeeded: "boolean" });
3


4
// Start a downstream processes and pass a reference to the prompt via its ID.
5
await airplane.rest.request("deploy_resource", "POST", "/startDeploy", {
6
  body: { promptID: myPrompt.promptID },
7
});
8


9
// In this case, the request from the downstream processes would look like
10
// curl https://api.airplane.dev/v0/prompts/submit \
11
//  -X POST \
12
//  -H "X-Airplane-API-Key: $AIRPLANE_API_KEY" \
13
//  -d '{
14
//    "id": "pmt20221122zyydx3rho2t",
15
//    "values": {
16
//        "deploy_succeeded": "true",
17
//    }
18
//}'
19


20
// Wait on the downstream process to submit the prompt via the Airplane API.
21
const { deploy_succeeded } = await myPrompt.wait();
API
PrivacyTermsSupport