Prompt

Gather user input during a task's execution.

Airplane's Prompt SDK makes it easy to request additional information from a user while a task is executing. See the Prompts documentation to learn more.

Prompt

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
    const { ok } = await airplane.prompt(
16
      { ok: "boolean" },
17
      {
18
        description: `Review the dry-run output above. If it looks correct, select OK to apply the changes.`,
19
      },
20
    );
21
    if (!ok) {
22
      await airplane.display.text("Exiting due to bad dryrun");
23
      return;
24
    }
25

26
    // If confirmed, we can re-run:
27
    const run = await airplane.execute("my_task_slug", {
28
      dry_run: false,
29
    });
30

31
    return run.output;
32
  },
33
);

airplane.prompt(params, opts)

params

PromptInputParams

Defines the parameter form as a mapping of slug to parameter. The values will be returned as an object that maps the parameter slug to the corresponding value. To learn more about parameters, see the Parameter documentation.

opts.reviewers

{groups: string[], users: string[], allowSelfApprovals: boolean}

Reviewers that are allowed to approve the prompt. If no reviewers are provided, anyone that can see the active run is allowed to approved.

opts.confirmText

string

Text of the confirmation button on the prompt dialog.

opts.cancelText

string

Text of the cancellation button on the prompt dialog.

opts.description

string

Prompt description to display. Supports markdown.

Returns

Promise<PromptOutputParams>

Promise of a mapping from parameter slugs to the values returned in the prompt response.

python
Copied
1
import airplane
2

3

4
@airplane.task()
5
def task_dryrun():
6
    # Perform a dry-run and show the output to the operator with a display.
7
    dry_run = airplane.execute(
8
        "my_task_slug",
9
        {
10
            "dry_run": True,
11
        },
12
    )
13
    airplane.display.json(dry_run.output)
14
    # Ask the operator if we should continue.
15
    airplane.prompt(
16
        description=(
17
          "Review the dry-run output above. If it looks correct, "
18
          "click OK to apply the changes."
19
        ),
20
        reviewers=airplane.PromptReviewers(
21
          groups=["eng-managers"],
22
          # Also accepts a list of users:
23
          users=["jill@company.com", "jack@company.com"],
24
        ),
25
    )
26
    # If confirmed, we can re-run:
27
    run = airplane.execute(
28
        "my_task_slug",
29
        {
30
            "dry_run": False,
31
        },
32
    )

airplane.prompt(params, reviewers, confirm_text, cancel_text, description, background)

params

Dict[str, PromptParamTypes]

reviews

Default

None

airplane.PromptReviewers

Reviewers that are allowed to approve the prompt. If no reviewers are provided, anyone that can see the active run is allowed to approved.

confirm_text

Default

None

str

Text of the confirmation button on the prompt dialog.

cancel_text

Default

None

str

Text of the cancellation button on the prompt dialog.

description

Default

None

str

Prompt description to display. Supports markdown.

background

Default

False

bool

If true, the prompt will be created in the background and a Prompt object will be returned. To wait for the prompt to be submitted, call prompt.wait().

Returns

Dict[str, Any]

Mapping of parameter slugs to the values submitted in the prompt.

Raises

HTTPError

If the prompt cannot be created properly.

requests.exceptions.Timeout

If the request times out.

requests.exceptions.ConnectionError

If a network error occurs.

Background prompt

Background prompts are prompts that are generated without immediately waiting for the response. See the Background prompts documentation to learn more.

typescript
Copied
1
// Create a prompt in the background
2
const myPrompt = await airplane.prompt.background({ deploy_succeeded: "boolean" });
3

4
// Wait for the prompt to be submitted
5
const { deploy_succeeded } = await myPrompt.wait();
6

7
// Get the prompt submitter
8
const { name, email } = await myPrompt.submitter();

airplane.prompt.background(params, opts)

params

PromptInputParams

opts.reviewers

{groups: string[], users: string[], allowSelfApprovals: boolean}

Reviewers that are allowed to approve the prompt. If no reviewers are provided, anyone that can see the active run is allowed to approved.

opts.confirmText

string

Text of the confirmation button on the prompt dialog.

opts.cancelText

string

Text of the cancellation button on the prompt dialog.

opts.description

string

Prompt description to display. Supports markdown.

Returns

Promise<PromptOutputParams>

Promise of Prompt object. See below for details on the methods exposed by the latter.

Prompt object

wait()

method

Returns a Promise<PromptOutputParams> containing a mapping of each parameter slug to the submitted value.

submitter()

method

Returns a Promise<{name: string, email: string, userID: string}> containing details on the user who submitted the prompt.