> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Forms

> Create structured ticket forms with custom fields, lifecycle states, audience controls, and folder organization to route requests intelligently.

<Callout icon="megaphone" color="#FFC107">
  **Request Types are now Forms.** This rename is rolling out to all organizations soon.
</Callout>

Forms transform generic support requests into structured, categorized tickets with the right information, routing, and workflow. Use folders to organize related forms by department, process, or team structure. AI-powered classification automatically identifies the right form based on request content.

## Mental model

A form defines the structure and defaults for a type of support request. When a ticket is created using a form, the form determines which fields are collected, what default values are applied (priority, channel, tags), and which custom sub-statuses are available.

Key relationships:

* One workspace has many forms, organized into folders.
* One form produces many tickets.
* One form can specify a default channel (affects ticket routing priority).
* One form can have specific custom sub-statuses assigned to it.
* One form can be referenced in agent rules with `@` and in workflow triggers.
* Each form has a lifecycle status (Draft, Published, Archived) that controls end-user visibility.
* Each form has an audience type (Everyone, Members Only, User Groups) that controls which users can see and submit it.
* Only Published forms with matching audience appear in end-user surfaces (portal, Slack, ticket creation).

Forms are workspace-scoped. Each workspace maintains its own form library.

AI classification matches incoming requests to the most appropriate form based on the request content and each form's description and sample messages. This is separate from category classification. Forms determine ticket structure, categories determine ticket topic.

***

## Form design patterns

**When to create a separate form:**

* The form needs different fields (e.g., "Software Access" needs an application select field, "Hardware Request" needs a device type field).
* The form needs different defaults (e.g., incidents default to high priority, feature requests default to low).
* The form needs a different status workflow (e.g., access requests use "Pending Approval" sub-status, bug reports use "Needs Review").
* The form should route to a different channel by default.

**When to use the same form:**

* The requests collect the same information and follow the same process. Differentiate with categories or tags instead.

**Folder organization:** Group forms into folders that match how requesters think about their needs, not how the support team is organized. "I need help with..." is a better mental model than "This goes to team X."

**Naming:** Use action-oriented names that describe what the requester needs: "Request Software Access", "Report a Bug", "Submit Expense Report." Avoid internal jargon.

***

## Form lifecycle

Forms have three statuses:

| Status        | End-user visible           | Admin visible                        | Valid transitions                         |
| ------------- | -------------------------- | ------------------------------------ | ----------------------------------------- |
| **Draft**     | No                         | Yes (forms table)                    | Draft -> Published                        |
| **Published** | Yes (filtered by audience) | Yes                                  | Published -> Draft, Published -> Archived |
| **Archived**  | No                         | Yes (forms table, hidden by default) | Archived -> Published                     |

New forms default to Draft so admins can finish configuring them before they become available to end users. The lifecycle is enforced server-side via the `updateStatus` endpoint, which validates transitions.

**UI controls:** The form detail page header has a toggle switch that controls Published/Draft. The toggle is disabled when the form is archived. Archive/unarchive buttons are in the Details tab. The forms table shows Publish/Unpublish in row actions and Archive as a bulk action.

**Deletion rules:** A form can only be deleted if it has zero associated tickets. Forms with tickets must be archived instead. The default form cannot be deleted or archived.

**Table visibility:** Archived forms are hidden from the forms table by default. They only appear when the user adds an explicit status filter.

Draft and Archived forms do not appear in the Portal, Slack form selection, or ticket creation form picker. Existing tickets created with a now-archived form retain their data.

***

## Audience access control

Audience determines which users can see and submit a published form:

| Audience type              | Who can access                           |
| -------------------------- | ---------------------------------------- |
| **Everyone**               | All users in the organization            |
| **WorkspaceMembers**       | Only workspace members and admins        |
| **Specific** (User Groups) | Only members of the selected user groups |

Audience filtering is server-side via `getPublishedAccessibleForms`. The Portal, Slack form selection, and semantic loader all use this endpoint. This replaces previous client-side filtering.

When audience is set to "Specific", the form stores `allowedGroups` (array of user group IDs). A user gains access if they are a member of any of the allowed groups.

***

## Form-ticket-channel integration

Forms influence ticket creation in several ways:

1. **Field collection:** The form determines which fields the requester fills out (system fields + custom fields).
2. **Default values:** Priority, channel, and tags can be pre-set per form.
3. **Title template:** Forms can auto-generate ticket titles from field values for consistent naming. Date fields support format suffixes (e.g., `{{fieldKey:MM/DD/YYYY}}`) to control date display.
4. **Channel routing:** A form's default channel takes highest priority in the routing order (form default > Slack channel connection > workspace default).
5. **Status options:** Custom sub-statuses assigned to the form determine which statuses are available beyond the five system statuses.
6. **Privacy:** Forms can default tickets to private, useful for HR, security, or confidential forms.
7. **Icon display:** Forms support custom image icons (uploaded images), Lucide icons, or a default fallback. The Portal renders them in priority order: custom image URL, then configured Lucide icon, then default icon.

When designing forms, consider the full ticket lifecycle: what information is needed at creation, what defaults reduce manual work, and what channel/status configuration matches the handling process.

***

## Forms in automation

**Workflow triggers:** The "Form Submitted" trigger fires when a ticket is created using a specific form. Filter by form to build form-specific automations. Form field data is available as dynamic values in downstream workflow actions.

**Agent rules:** Reference forms in agent rules using `@Form Name`. Common patterns:

* "When a user asks about software access, present the @Software Access Request form."
* "For hardware issues, use the @Hardware Request form and set priority based on urgency."

The agent can present forms to users during conversation, pre-fill fields from conversation context, and let the user review before submission.

**AI classification:** The system matches incoming requests to forms based on form descriptions and sample messages. Well-written descriptions and diverse sample messages improve classification accuracy. This classification is separate from category classification and runs independently.

***

## Constraints and gotchas

* Every form must have at least one field. The title field is always required and cannot be made optional.
* Forms are workspace-scoped. There is no cross-workspace form sharing or import.
* A form's default channel takes highest routing priority. If a form specifies a default channel, tickets created with that form always go to that channel regardless of which Slack channel the request originated from.
* AI form classification and AI category classification are separate systems. A request can be matched to a form and independently classified into a category.
* Custom sub-statuses must be explicitly assigned to each form. Creating a sub-status does not make it available on all forms.
* Moving a form between folders does not affect existing tickets or form configuration.
* Private forms create private tickets by default. Users can still change ticket visibility after creation if they have permission.
* Form field data is accessible in workflows via dynamic values, but only for tickets created with that specific form. Tickets created without a form (or with a different form) will not have those field values available.
* Only published forms appear in end-user surfaces (Portal, Slack, ticket creation). Draft and archived forms are admin-only.
* AI agents also honor form lifecycle. The agent only presents Published forms, even if a Draft or Archived form is referenced in an agent rule. Publish the form before relying on it in agent rules.
* Audience filtering is server-side. The `listAccessible` endpoint returns only forms the current user can access based on publish status and audience.
* Changing a form's audience does not affect existing tickets created with that form.
* A form's audience setting has no effect when the form is in Draft or Archived status, since those forms are not visible to end users regardless.
* A form cannot be deleted if it has any associated tickets. The only option is to archive it.
* The default form for the workspace cannot be deleted or archived.
* Archived forms are hidden from the forms table by default. They appear only when the user adds an explicit status filter.
* The publish/draft toggle in the form header is disabled when the form is archived. You must unarchive first.
* Archiving a folder offers two modes: archive the folder with its contents, or archive only the folder and reparent its contents to the nearest non-archived ancestor. Bulk archive applies the chosen mode to every selected folder in one transaction.
* Forms created inside an archived folder inherit the archived status at creation time. The same applies to duplicates whose target parent is archived. Unarchive the parent first if you want new forms to start as Draft.