Form blocks

Form blocks accept user input as parameters that can be referenced in later blocks.

You will typical set the block to Manual rather than Auto mode (see Manual Blocks). This allows the session to pause and wait for users to input data and/or confirm before proceeding.

When the runbook is executed, manual form blocks will pause and allow users to enter additional data.
When the runbook is executed, manual form blocks will pause and allow users to enter additional data.

A form block's output matches its parameters. For example, a parameter of user_email on block prompt_block can be accessed in a later block as {{prompt_block.output.user_email}}.

Form blocks are especially useful for a few scenarios:

  • If some data needs to be manually retrieved by the user, form blocks are a handy way of asking for that information in the middle of a session.
  • A form block with no parameters can be used to ask a user to confirm before proceeding.
  • You can use templating to pre-populate the values in a form block. This is useful for suggesting values and having a user confirm them.

Templated options

The parameters that form blocks use to accept user input are similar to parameters that we define for tasks and runbooks, except we can also template the options for a form block. This means that we can utilize Javascript templates to utilize the output from a previous block to dynamically render the options for the form block.

To use templated options, next to the Select options section of the parameter configuration screen, select Template from the dropdown. As an example, suppose that we have a SQL block that returns a list of users, and we'd like to select one user ID out of the results to pass onto another block. We could create a form block with a parameter that references the output of the SQL block, like so:

When we execute the runbook, the form options will be dynamically generated:

The JavaScript expression provided in a Select options template must evaluate to an array of objects with field "value".

Labels

Templated options also support labels, similar to options we might manually define. This is useful in cases where we want to pass a computer-generated value like a UUID to the next block, but want to display a more human-readable set of option to the person executing the runbook. To do so, the Javscript expression can be augmented to evaluate to an array of objects that also have a "label" field in addition to the "value" field.

handlebars
Copied
1
{{ sql.output.Q1.map(user => ({"label": user.name, "value": user.id})) }}

Then, during runbook execution, the options will show the label instead of the underlying value:

Because Javascript templates can execute arbitrary Javascript code, you can do transformations like sorting the list of options:

handlebars
Copied
1
{{ sql.output.Q1.sort((user1, user2) => user1.name < user2.name).map(user => ({"label": user.name, "value": user.id})) }}

The list of options will then be displayed as:

PrivacyTerms