# Runbook Forms

Collect several typed answers from a requester in one runbook step: build a reusable form, attach it to a runbook, and Risotto posts it as a Slack form or Teams card, or asks for the fields in conversation

A **form** is a reusable, typed set of fields that a runbook asks the requester to fill out at one step. Instead of writing a chain of clarifying questions ("What model? When do you need it? Who approved it?"), you attach a form and the agent collects every field at once.

The product also calls forms **structured input** or **structured-input forms**. A form belongs to your organization, not to one runbook, so several runbooks can use the same form, and one runbook can use several forms.

> **Note:** Runbook forms are different from the [Send Slack
> Form](https://www.tryrisotto.com/docs/integrations/tools/slack/send_form) tool and from [Campaign
> forms](https://www.tryrisotto.com/docs/dashboard/campaigns#form-campaigns). See [How this
> compares](#how-this-compares-to-other-forms) below.

## How it works

1. **You build a form** from the **Forms** card of a runbook, or ask the [Assistant](https://www.tryrisotto.com/docs/dashboard/assistant) to build one. A form has a name, an optional description, and an ordered list of fields.

2. **You attach it to a runbook.** The form appears as a chip in the runbook's **Agent instructions**, and you place it in the step where the details are needed.

3. **The agent collects it.** When a ticket matches the runbook and the agent reaches that step, it presents the form in the ticket's conversation:

   - **Slack:** an interactive form in the ticket thread.
   - **Microsoft Teams:** an interactive card in the conversation.
   - **Everywhere else** (email, Jira, web, API-created tickets): the agent asks for the fields one at a time.

   The form is posted in the ticket's own conversation, so it goes to the ticket's requester. You can't send it to someone else. To collect a form from another person, such as a hiring manager, use an [automation](https://www.tryrisotto.com/docs/dashboard/automations#tickets-an-automation-creates) that creates a ticket for that person.

4. **The answers come back to the agent.** When the requester submits, the form locks and the answers are added to the ticket conversation as a message from the requester. The agent continues the runbook with those answers.

> **Tip:** Use a form when a step needs **several** structured values up front: a new
> hire's name, start date, and laptop; the details of an equipment order; the
> fields your ticketing system needs. A single missing fact is still best
> handled as a plain clarifying question in the instructions.

## Creating a form

You build forms from a runbook. Open the runbook at [dashboard.tryrisotto.com/runbooks](https://dashboard.tryrisotto.com/runbooks) and click **Edit**. The **Forms** card is under the **Agent instructions**. Creating a form needs the Org Admin or Manager role; see [Permissions](#permissions).

1. **Open the form builder**

   In the **Forms** card, click **Add form**.

   *Product example: A runbook's editor in the Risotto dashboard, with its agent instructions and an empty Forms card, and Add form.*

2. **Name the form**

   Enter a **Name**. The requester sees it as the form's title, so make it requester-friendly, for example *New hire equipment request*.

   Optionally, enter a **Description**. Risotto shows it to the requester above the fields when the form is posted in Slack or Teams, for example *A few details so we can have the right equipment ready on day one.* Write it for the requester, not for your team.

   *Product example: The Add form dialog in the Risotto dashboard, with the form's name and description entered and Add your first field.*

3. **Add the fields**

   Click **Add your first field**, then **Add field** for each one after that. For each field, set:

   - **Field label:** the question the requester sees, for example *Laptop model*.
   - **Type:** one of the [field types](#field-types).
   - **Required:** off by default. Turn it on only when the runbook can't go on without the answer.
   - **Help text** (optional): guidance shown with the field.
   - **Choices:** for **Single select** and **Multi select** fields, click **Add choice** for each option the requester picks from. A select field needs at least one choice.

   To reorder fields, drag a field by its handle, or click **Move up** or **Move down**. To delete a field, click **Remove field**.

   *Product example: The Add form dialog's fields in the Risotto dashboard, with a field's type menu open on Date.*

4. **Save the form**

   Click **Save**. **Save** stays unavailable until the form has a name, at least one field, a label on every field, and a choice on every select field.

   Risotto creates the form for your organization ("Form created") and adds it as a chip at the end of the runbook's instructions.

5. **Place the form in a step**

   Move the chip into the step where the details should be collected, wrapped in an instruction. Tell a later step what to do with the answers, for example:

   ```markdown
   1. Collect the new hire's details with [Form: New hire equipment request].
   2. Order the laptop the requester chose, in time for the start date.
   ```

   *Product example: A runbook's instructions in the Risotto dashboard's editor, with the form's chip in step 1, the form in the Forms card, and Save.*

6. **Save the runbook**

   Click **Save**, or **Save as draft**. In the editor, adding or removing a form chip changes only the runbook's instructions, and nothing changes until you save. The form itself was already saved in the previous step.

> **Note:** **Add form** and **Insert existing form** are also on the runbook's page, when
> you aren't editing it. There, Risotto saves the runbook as soon as you add the
> form ("Form added to runbook"), with the form's chip at the end of the
> instructions. Edit the runbook to move the chip into the right step.

### Reusing an existing form

To use a form that already exists, click **Insert existing form** in the **Forms** card, search for the form, and select it. Each form is listed with its field count. Reuse is the best choice when several runbooks collect the same details, for example one *Hardware request* form shared by the laptop, monitor, and peripherals runbooks.

Forms that belong to a [Service Catalog](https://www.tryrisotto.com/docs/dashboard/settings/service-catalog) item aren't listed, because a form imported with a catalog item can't be used by a runbook. The picker says how many forms it left out for this reason.

### Editing and previewing a form

Each form a runbook uses is a row in the **Forms** card, with its name and field count. Click the field count to open a preview of the form as the requester sees it in Slack. To change the form's name, description, or fields, click **Edit form** under the preview, make your changes, and click **Save** ("Form updated"). To remove the description, clear the **Description** box and click **Save**.

*Product example: A runbook's Forms card in the Risotto dashboard, with the form's Slack preview open and Edit form.*

The runbook's side panel also lists its forms under **Form**. Click a form there to open the same editor.

> **Warning:** Editing a form changes it **everywhere it is used**. If several runbooks use
> the form, check that the change makes sense for all of them before saving.

## Field types

| Type              | What the requester sees                                                                                  |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| **Short text**    | A single-line text input                                                                                 |
| **Paragraph**     | A multi-line text box                                                                                    |
| **Email**         | An email-style text input in Teams; a plain text input in Slack                                          |
| **URL**           | A URL-style text input in Teams; a plain text input in Slack. See [URL fields](#url-fields)              |
| **Number**        | A numeric input in Teams; a plain text input in Slack                                                    |
| **Date**          | A date picker                                                                                            |
| **Date & time**   | A text input for a date and time (Slack and Teams have no combined picker, so this is collected as text) |
| **Single select** | A dropdown where the requester picks one of the choices you defined                                      |
| **Multi select**  | A dropdown where the requester picks one or more of the choices you defined                              |

In Slack, optional fields are marked **(optional)**. In Teams, the card won't submit until the required fields are filled in. When the agent collects a form in conversation, it knows which fields are required and which choices each select field offers.

### URL fields

A **URL** field accepts only an `http://` or `https://` address with a host. If the requester leaves out the scheme, for example `example.com/page`, Risotto adds `https://`. Risotto checks URL fields when the requester submits the form:

- **In Slack**, Risotto shows a message that only the requester sees, for example "Please fix the following before submitting: **Website** must be a valid URL". The form stays open, so the requester can correct the address and click **Submit** again.
- **In Microsoft Teams**, Risotto replies "Please correct these URL fields (must be http\:// or https\://):" followed by the field labels. The card stays open for another submit.
- **In conversation**, the agent asks the requester to correct the address before it continues.

## What the requester experiences

**In Slack**, the form is posted in the ticket thread as a message from Risotto, with the form's name, its description, the fields, and a **Submit** button. Filling in a field doesn't send anything. Only **Submit** does.

*Product example: A Slack thread where Risotto posted the New hire equipment request form, filled in, with its Submit button.*

After the requester clicks **Submit**, the form is replaced with a read-only summary: the form's name marked *(submitted)*, each answer under its label (*No response* for a field left blank), and **Response recorded**. The form can't be edited or submitted again.

*Product example: The same Slack thread after Submit, with the form replaced by its answers and Response recorded.*

**In Microsoft Teams**, the form is posted as an interactive card in the ticket conversation. After submitting, the card is replaced with a read-only summary.

**In other channels**, or when a form can't be posted interactively (see [Limits](#limits)), the agent asks for each field in conversation.

In every case, if a required field is still missing, the agent asks for it in conversation before it goes on.

> **Note:** If your organization runs a **custom Risotto Slack app**, its manifest must
> include interactivity for forms to post and submit. If a form fails to post,
> follow the [Update Slack App](https://www.tryrisotto.com/docs/guides/update-slack-app) guide to bring
> the manifest up to date. Organizations on the Marketplace app don't need to do
> anything.

## Where the answers go

- The answers are added to the **ticket conversation** as a message from the requester, headed with the form's name and "form responses", one line per field. You can read them on the ticket's page.
- Risotto records each completed form as a **form response** on the ticket, with a snapshot of the fields as they were at the time. The record stays accurate even if the form is edited later.
- Answers stay in Risotto. A form doesn't file anything in an external system. Use the runbook's later steps and tools (for example, a ticketing tool or a [Custom API Tool](https://www.tryrisotto.com/docs/integrations/tools/custom-api-tools)) to act on the answers.
- There is no separate report of form responses in the dashboard. Read the answers on the ticket.

## The Collect Structured Input tool

The first time a runbook in your organization uses a form, Risotto creates a tool named **Collect Structured Input** in your [Tools](https://www.tryrisotto.com/docs/dashboard/tools) list. The agent calls this tool to present a form and record its answers.

- You don't add this tool to runbooks yourself. The form chip is all you need.
- It does **not** count toward the limit of 10 tools per runbook.
- It doesn't require approval. It only asks the requester for the fields a form already declares.
- Don't turn it off or delete it. If it's off or deleted, Risotto turns it back on or creates it again the next time you save a runbook that uses a form.

## Limits

| Limit                                 | Value                                                                                                        |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Fields per form (interactive form)    | 20. Larger forms still work, but the agent collects them in conversation instead of as a Slack or Teams form |
| Choices per select field              | 100                                                                                                          |
| Choice label length                   | 75 characters for each choice                                                                                |
| Field label length                    | 2,000 characters                                                                                             |
| Form name length                      | 255 characters                                                                                               |
| Submissions per posted form           | One. After submitting, the form locks                                                                        |
| Forms per runbook / runbooks per form | No limit                                                                                                     |

Risotto doesn't reject a form that is over a Slack or Teams limit. The agent collects the same fields in conversation instead.

- The 75-character limit applies to each choice label by itself, not to the whole dropdown. Help text and the form description do not count toward it.
- In Slack, the whole form must also fit in one message of 50 blocks: the title, the description, one block for each field, and the **Submit** button. A long description can take more than one block.
- Risotto does not warn you when a form falls back to the conversation. Keep each choice label at 75 characters or fewer, and test the form after you change it.

### What forms don't do yet

- **Conditional (branching) questions.** Every requester sees every field. A field can't appear, or change its choices, based on an earlier answer. Keep the questions everyone must answer in the form, and let the runbook's instructions ask the follow-ups that depend on those answers.
- **File uploads.** There is no attachment field. Ask for documents in the step after the form. Anything the requester drops into the ticket thread is saved as a ticket attachment and synced to your ticketing system like any other attachment.
- **Picking a person from a directory.** Runbook forms have no user-picker field. Collect a name or, better, an **Email** field, and let the runbook find the person from it. If you need Slack's user picker and the runbook only runs in Slack, use the [Send Slack Form](https://www.tryrisotto.com/docs/integrations/tools/slack/send_form) tool instead.
- **Choices from another system.** The choices of a **Single select** or **Multi select** field are a fixed list that you type into the form. A form can't load them from Okta, your directory, or another integration. For example, to offer your Okta departments, type each department name as a choice, and edit the form when the list changes.

## Building forms with the Assistant

The [Assistant](https://www.tryrisotto.com/docs/dashboard/assistant) understands forms. For example, you can ask: *"Create a hardware request form with laptop model, justification, and needed-by date, and attach it to the Laptop replacement runbook."* The Assistant will:

- Reuse an existing form when one already fits, rather than create a duplicate.
- Create the form, pausing for your approval as it does for any change.
- Propose the runbook change as a [draft](https://www.tryrisotto.com/docs/dashboard/runbooks#reviewing-changes-with-drafts) for you to review and publish.

The Assistant creates, changes, and deletes forms only for Org Admins and Managers. For a department supervisor, it can attach an existing form to a runbook, but not create or change one.

Forms are also available through the [MCP Server](https://www.tryrisotto.com/docs/integrations/mcp-server) as `list_forms`, `get_form`, `create_form`, `update_form`, and `delete_form`, under the `runbooks:write` scope. Creating, changing, and deleting a form also needs the Org Admin or Manager role.

## Permissions

- **Org Admins and Managers** can create and edit forms, and attach them to runbooks.
- **Department supervisors**, who edit their departments' runbooks, can attach an existing form with **Insert existing form**. Forms are shared across the organization, so they can't create or edit one: saving a form fails with "Failed to save form."
- Anyone who can view a runbook can see the forms it uses and their preview.
- **Requesters** don't need any permission. The form comes to them in their ticket's thread or conversation.

Creating, changing, and deleting a form is recorded in your organization's audit events.

## Deleting a form

The dashboard has no button to delete a form. To delete one, ask the [Assistant](https://www.tryrisotto.com/docs/dashboard/assistant) or use the `delete_form` tool of the [MCP Server](https://www.tryrisotto.com/docs/integrations/mcp-server). A form that belongs to a Service Catalog item can't be deleted this way.

You can delete a form even while runbooks still use it. Those runbooks keep working, but the agent is told the form was removed, and nothing is collected at that step. In the editor, the form's chip shows as broken, and the **Forms** card lists it as "Unknown form" with **Not found**. After deleting a shared form, edit each runbook that used it and either remove the step or insert a replacement form.

## How this compares to other forms

| Feature                                 | Runbook Forms                                                                             | [Send Slack Form](https://www.tryrisotto.com/docs/integrations/tools/slack/send_form) tool | [Campaign Forms](https://www.tryrisotto.com/docs/dashboard/campaigns#form-campaigns) |
| --------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Where the form is defined               | On its own, for the organization; reusable across runbooks                                | On each tool instance; one form per tool                                                   | In the campaign editor                                                               |
| How it's attached to a runbook          | **Add form** or **Insert existing form** in the **Forms** card                            | Add the tool with the `#` picker                                                           | Not used in runbooks                                                                 |
| Delivery                                | Slack form, Teams card, or conversation, chosen automatically                             | Slack only                                                                                 | Slack DM to every recipient                                                          |
| Field types                             | Short text, Paragraph, Email, URL, Number, Date, Date & time, Single select, Multi select | Select, Multi-select, Checkbox, Radio, Date, Time, User picker, Free text                  | Same as Send Slack Form                                                              |
| Counts toward the 10-tool runbook limit | No                                                                                        | Yes                                                                                        | —                                                                                    |

Choose **Runbook Forms** when the runbook should work wherever the ticket came from, or when several runbooks share the same questions. Choose **Send Slack Form** when you need Slack-only field types such as user pickers, checkboxes, or radio buttons.

## Troubleshooting

### The agent asked for the fields one by one instead of showing a form

This is the conversational fallback. It happens when the ticket didn't come
from Slack or Teams, when the form is over an interactive limit (more than 20
fields, a choice label over 75 characters, or a very large form), or when
posting the form failed. Trim the form to fit, or check that your custom Slack
app's manifest is current.

### The runbook shows 'Unknown form' or 'Not found' in the Forms card

The form the runbook uses was deleted. Remove the form's step, or use **Insert
existing form** to attach a replacement, then save the runbook.

### The agent skipped the form step

Check that the runbook is enabled and that the agent followed it: on the
ticket's page, the **Runbook** panel shows a checkmark next to a runbook the
agent followed. Also check that the form chip is inside a clear step of the
**Agent instructions**, such as *"Collect the request details with \[form]"*,
and that a later step tells the agent what to do with the answers.

### Collect Structured Input appeared in my Tools list

This is expected. Risotto creates this tool the first time a runbook uses a
form. Leave it on; see [The Collect Structured Input
tool](#the-collect-structured-input-tool).

## Related

- [Runbooks](https://www.tryrisotto.com/docs/dashboard/runbooks): writing match conditions and instructions
- [Tools](https://www.tryrisotto.com/docs/dashboard/tools): the tools runbooks can call
- [Send Slack Form](https://www.tryrisotto.com/docs/integrations/tools/slack/send_form): a per-tool, Slack-only form
- [Campaigns](https://www.tryrisotto.com/docs/dashboard/campaigns#form-campaigns): send a form to many recipients
- [Assistant](https://www.tryrisotto.com/docs/dashboard/assistant): build forms and runbooks in conversation

Source: https://www.tryrisotto.com/docs/dashboard/runbooks/forms
