Docs

Help desk / Teach the agent

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.

How it works

  1. You build a form from the Forms card of a runbook, or ask the 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 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.

Creating a form

You build forms from a runbook. Open the runbook at 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.

  1. Open the form builder

    In the Forms card, click 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.

  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.
    • 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.

  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:

    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.
  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.

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 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.

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

Field types

TypeWhat the requester sees
Short textA single-line text input
ParagraphA multi-line text box
EmailAn email-style text input in Teams; a plain text input in Slack
URLA URL-style text input in Teams; a plain text input in Slack. See URL fields
NumberA numeric input in Teams; a plain text input in Slack
DateA date picker
Date & timeA text input for a date and time (Slack and Teams have no combined picker, so this is collected as text)
Single selectA dropdown where the requester picks one of the choices you defined
Multi selectA 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.

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.

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), 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.

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) 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 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

LimitValue
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 field100
Choice label length75 characters for each choice
Field label length2,000 characters
Form name length255 characters
Submissions per posted formOne. After submitting, the form locks
Forms per runbook / runbooks per formNo 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 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 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 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 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 or use the delete_form tool of the 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

FeatureRunbook FormsSend Slack Form toolCampaign Forms
Where the form is definedOn its own, for the organization; reusable across runbooksOn each tool instance; one form per toolIn the campaign editor
How it's attached to a runbookAdd form or Insert existing form in the Forms cardAdd the tool with the # pickerNot used in runbooks
DeliverySlack form, Teams card, or conversation, chosen automaticallySlack onlySlack DM to every recipient
Field typesShort text, Paragraph, Email, URL, Number, Date, Date & time, Single select, Multi selectSelect, Multi-select, Checkbox, Radio, Date, Time, User picker, Free textSame as Send Slack Form
Counts toward the 10-tool runbook limitNoYes—

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.

Something wrong or missing? Report an issue · View as Markdown