> ## 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. **Request Types are now Forms.** This rename is rolling out to all organizations soon. 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. *** ## Getting started Organize your forms using folders that match your team's workflow. Consider department-based, process-based, or complexity-based organization. Navigate to **Forms** and create folders with clear names, descriptions, and visual elements to help users quickly identify categories. Create forms within folders, configure them with system and custom fields, and set up AI classification with sample messages. Set up defaults, status management, channel integration, and AI responses to streamline ticket handling. *** ## Organize with folders Folders group related forms and provide the same organizational approach you use for workflows and knowledge pages. Forms and folders are workspace-specific, allowing each team to create a support system matching their unique requirements. ### Create folders Give folders clear names and descriptions that explain their purpose. Folders support nested structures that mirror your organization. **Example:** An "IT Support" folder might contain subfolders for "Hardware", "Software", and "Network" issues. ### Organization patterns Organize by team ownership - IT Support, DevSecOps, IT Admins. This structure matches organizational hierarchy and ownership. Group by business function - Onboarding, Procurement, Maintenance. This structure aligns with business processes and workflows. Separate simple requests from complex processes and specialized workflows. This helps users find the right level of detail quickly. ### Moving forms and folders Move forms and folders between locations as your organization evolves. Use drag-and-drop or bulk operations to reorganize your form structure. Drag forms or folders to move them between locations. **Single item:** 1. Click and hold on a form or folder 2. Drag to the target folder or breadcrumb 3. Release to move **Multiple items:** 1. Select multiple forms or folders using checkboxes 2. Drag any selected item 3. All selected items move together **Create new folder during move:** Drag items to the "Move to new folder" button to create and move in one action. Move multiple forms at once using bulk actions. 1. Select forms or folders using checkboxes 2. Click the **Move** action in the toolbar 3. Select the target folder 4. Confirm the move Bulk move is ideal for reorganizing large numbers of forms or restructuring your folder hierarchy. Some moves are prevented to maintain system integrity: * Forms keep their history and configuration when moved * Folders cannot be moved into their own subfolders (prevents circular references) * Moving a folder also moves all forms and subfolders within it *** ## Create forms Create forms within folders or at the root level based on your organizational needs. Each workspace maintains its own collection tailored to specific support requirements. ### Basic configuration Choose a clear, recognizable name and helpful description that eliminates guesswork for requesters. #### Icon and color customization Visual elements like icons and colors help users quickly identify the right form in the portal, Slack, and ticket views. Forms support three types of icons, displayed with the following priority: 1. **Custom image**: Upload a branded or project-specific image (PNG, JPEG, GIF, WebP, or SVG, max 1MB). The image is cropped to a square during upload. 2. **Lucide icon**: Select any icon from the full [Lucide](https://lucide.dev/icons) library. Use the search bar in the icon picker to find an icon by name or keyword. 3. **Default icon**: If no icon is configured, a default icon is used automatically. Custom icons appear on Portal request cards, the forms list page, ticket rows, and task rows. Select a color for your form icon to create visual distinction between forms. Colors apply to both Lucide icons and the icon background in the Portal. Upload branded icons to help users visually distinguish forms in the Portal, especially when you have many forms in a single folder. ### Form builder Use the form builder to create custom data collection forms with system fields and custom fields. Drag and drop fields to arrange your form layout, nest dependent fields under parent fields, and collapse groups to manage complex forms. Every form must have at least one field configured to collect information from requesters. System fields are core built-in ticket components: title, description, status, priority, requester, assignee, approvers, and followers. You can control whether they're required or optional. The title field must always be required. Custom fields provide flexibility to collect specific information for different forms. Available types include text, text area, number, date, boolean, select, multi-select, user select, and application select. All field types can be configured to show or hide based on the value of another field, including layout fields (headings, dividers, text blocks) and system fields. For example, a "Department" select field can control which follow-up fields and section headings appear. Conditional fields display as nested under their parent in the form builder and are grouped in collapsible sections for easier management. Visibility rules are enforced both during form filling and in the ticket detail view. Learn more about [custom fields](/documentation/tickets/forms/custom-fields) and how to configure them for your forms *** ## Configure forms Configure form behavior through settings tabs. Control basic behavior and appearance. Set it as the default when the system can't determine the most appropriate type. Updates in the **General** section auto-save as you edit. Toggling a setting or selecting an audience card applies the change immediately — there is no manual save step. ### Privacy settings The **Private** toggle controls default ticket privacy for this form. When enabled, tickets created with this form are automatically marked as private. **When to use private forms:** * HR requests * Security incidents * Personal information * Confidential business matters **Configure privacy:** 1. Go to **Settings > Forms** 2. Select the form you want to configure 3. Click the **Details** tab and open the **General** section 4. Enable or disable the **Private** toggle — the change saves automatically Your organization may have different needs for private forms based on your security policies and compliance requirements. The **Private** toggle controls default ticket privacy only. It does not hide the form itself. Published forms with the Private toggle enabled still appear in the Portal and the Slack form selection list (subject to their audience settings); the resulting tickets are marked private when submitted. To hide a form from end-user surfaces entirely, move it to **Draft** or **Archived**, or restrict its audience. ### Feature in Portal Enable **Feature in Portal** to surface a form on the **Start new request** tab of the Portal home. Featured forms keep your most common requests front and center. Forms that are not featured still appear in the Portal's full forms catalog when the requester has access. Streamline ticket creation with automatic values. ### Title templates Title templates generate consistent, informative titles using field values, especially valuable when requesters don't provide clear titles. Insert tokens using the dropdown in the title template editor. Available tokens include system values like requester name, assignee, and form name, plus any custom fields on the form. Date fields support an optional format suffix to control how the date appears in the generated title. When you insert a date field token, a submenu lets you pick from common date formats. If no format is specified, date fields default to MM/DD/YYYY. Set default priority, type, channel, and tags to ensure tickets start with appropriate settings, reducing manual work and ensuring consistent handling. ### Shortcut public acknowledgement The **Shortcut Public Acknowledgement** toggle controls the default acknowledgement for tickets created from this form through the Slack [message shortcut](/integrations/slack/creating-tickets#methods). It applies in DMs and in channels that are not connected request channels. This setting is Slack-only. Microsoft Teams does not have a 1:1 DM entry point or shortcut equivalent in the current beta; Teams tickets are always created from channel messages. See the [Microsoft Teams integration overview](/integrations/microsoft-teams/overview). * **Enabled (default):** Ravenna posts a public threaded message confirming the ticket was created so everyone in the conversation sees the acknowledgement. * **Disabled:** Only the user who created the ticket sees an ephemeral confirmation. The original thread stays untouched. Submitters can still change the choice per ticket using the **Publicly acknowledge that a ticket was created?** checkbox on the Slack modal. This setting only changes the default state of that checkbox. The setting has no effect inside connected request channels, where Ravenna always posts a public confirmation in the thread. *** ## Form lifecycle Forms follow a Draft, Published, and Archived lifecycle that controls their visibility to end users. Draft forms are works in progress. They are visible to workspace admins in the forms table but do not appear in ticket creation flows, the Portal, or Slack. Newly created forms start in Draft so you can build and review them before exposing them to end users. Publish the form when you're ready to make it available. You can also move a published form back to Draft if you need to make changes before re-publishing. Published forms are active and available to users based on their audience settings. They appear in ticket creation flows, the [Portal](/documentation/platform/portal), and Slack form selection. Archived forms are removed from all user-facing surfaces. Existing tickets created with an archived form retain their data and history. Archive a form when it is no longer needed but you want to preserve its configuration. ### Manage form status The form detail page includes a toggle switch in the header that controls whether a form is **Published** or **Draft**. Toggle it on to publish, or off to move back to draft. A confirmation dialog appears before the change is applied so you can review the impact before publishing or unpublishing. Publishing makes the form available in end-user surfaces; unpublishing hides it from the Portal, Slack, and ticket creation flows. Click **Confirm** to apply the change, or **Cancel** to keep the current status. The toggle is disabled when a form is archived. You must unarchive a form before you can change its publish state. Archive and unarchive controls are in the **Details** tab at the bottom of the form detail page. * Click **Archive** to remove a form from all user-facing surfaces. A confirmation dialog appears before the form is archived. * Click **Unarchive** to restore an archived form back to Published status. **Archiving folders:** When you archive a folder, a confirmation dialog asks whether to include the folder's contents: * **Include contents:** The folder and every form and subfolder inside it are archived together. * **Folder only:** Only the folder is archived. Forms and subfolders inside it are moved up to the nearest non-archived parent so they remain available to end users. Forms created inside an archived folder — including duplicates — inherit the archived status automatically. Unarchive the parent folder first if you want new forms to start as Draft. The delete option is also in the **Details** tab. Delete is only available for forms that have **no associated tickets**. If a form has been used to create tickets, it cannot be deleted. Archive it instead. The default form for the workspace cannot be deleted or archived. You can also manage status from the forms table: * **Three-dot menu**: **Publish** appears for draft forms, **Unpublish** appears for published forms. Both actions show a confirmation dialog before the status change is applied. * **Bulk actions**: Select multiple forms or folders and use the **Archive** bulk action. When the selection includes folders, you're prompted to choose whether to archive their contents along with them. The default form cannot be archived and is skipped if included in the selection. * **Status column**: Color-coded badges show each form's current status (Draft = gray, Published = green, Archived = amber). * **Filtering**: Use the status filter to show or hide forms by status. Archived forms are hidden by default unless you add an explicit status filter. *** ## Audience settings Control who can see and submit a form by setting its audience. Audience settings work alongside the form lifecycle to determine which users can access a form. All users in your organization can see and submit the form. This is the default audience for new forms. Only workspace members and admins can access the form. End users who are not workspace members will not see it in ticket creation flows or the Portal. Only members of selected user groups can access the form. Select one or more groups to define the audience. ### Configure audience Navigate to the form and click the **Details** tab, then select the **General** section. In the **Who Can Access** card, select one of the three audience cards: **Everyone**, **Members only**, or **User Groups**. The selected card is highlighted to confirm your choice. If you chose **User Groups**, a group picker appears below the audience cards. Search for and add the groups you want to grant access to. Changes in the **General** section save automatically as you make them. There is no separate **Save changes** button — selecting a card or updating a field commits the change immediately. Audience settings only apply to published forms. Draft and archived forms are not visible to end users regardless of their audience setting. Learn more about [user groups](/documentation/platform/groups) and how to create and manage them *** ## Advanced features ### Status management Forms can define custom statuses beyond the standard system statuses. All forms include default statuses (Open, In Progress, Waiting, Done, Closed), but you can add custom statuses within these groups. **Example:** The "In Progress" group might include "Needs Review" for requests requiring approval. The "Done" group could have "Completed" and "Delivered" to track different completion states. Learn more about [status management](/documentation/tickets/organize/statuses) and custom statuses ### Channel integration Forms integrate with your channel structure to ensure proper routing and assignment. Each form can specify a default channel for streamlined ticket creation. Learn more about [setting up and managing channels](/documentation/tickets/channels) for your workspace ### Share forms in Slack Paste a Ravenna form URL into any Slack channel, DM, or thread to share it as an unfurled card with an **Open Form** button. Teammates can click the button to launch the form as a Slack modal and submit a request without leaving Slack. Learn more about [sharing forms in Slack](/integrations/slack/creating-tickets) including URL formats and routing behavior. ### Share forms publicly Turn on **Public access** to host a form at an unguessable URL that anyone can submit without signing in. Use it for requests from people outside your organization, like vendor onboarding, event sign-ups, or external bug reports. Open the **Share** popover on a published form and toggle **Public access**. Ravenna generates a public link you can copy and share. Submitters enter their email, and Ravenna creates or reuses a guest user as the requester so the ticket routes like any other. Public access is only available on published forms. The public link becomes active once the form is published. Public forms support simple input fields (text, paragraph, number, date, time, yes/no, select, multi-select, and timezone) plus layout blocks. Fields that reference workspace data, such as user, tag, or status pickers, are not allowed. If a form has an incompatible field, Ravenna lists the fields to remove before you can enable public access. Copy the public link from the **Share** popover and distribute it however you like. To invalidate the current link, use **Rotate link** to generate a new token. Rotating breaks the existing link for everyone. Public forms never expose workspace data. Responses are limited to the allowed field types, submissions are rate limited, and a CAPTCHA challenge protects against abuse. Turn off **Public access** at any time to deactivate the link. ### Workflow automation Forms integrate with workflows through the Form Submitted trigger, enabling automated responses when specific forms are submitted or updated. **Automation capabilities:** * Trigger workflows on form submission * Filter workflows by specific form types * Access form field data in workflow actions * Automate routing, assignment, and approvals based on form type Learn more about [workflow triggers and actions](/documentation/automate/workflows/triggers-actions) including the Form Submitted trigger ## 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.