Custom forms turn repeatable agent actions into structured, queryable, automatable events. Instead of agents free-texting "escalating to vendor" into ticket notes, they fill out a Vendor Escalation form. The data is structured, the action is logged, and a form lifecycle (covered last lesson) can fire the right downstream actions automatically. This lesson covers building forms.

What forms are for

Problem: Some actions on a ticket need the same information captured the same way every time — "request approval to spend over $500", "escalate to vendor", "send to manager for review", "document a security incident". Without a standard way to capture that info, agents free-text it into notes, approvers don't know where to look, the action that should follow doesn't happen consistently, and the data isn't queryable later.

Horizon's answer: Custom forms. You define a form once. Agents fill it out from the ticket widget. The data attaches to the ticket. If the form has a lifecycle rule, downstream actions fire automatically. Submissions are stored, attributed, and queryable.

The split is clean:

• Admins create and configure forms (this lesson) and wire them to lifecycles (last lesson).
• Agents consume forms from the ticket widget by submitting them.

Where forms live

Open the admin panel and navigate to Components → Custom Forms. You'll find:

A Test Form action on the form list lets you preview a form without submitting it for real.

Anatomy of a form

A form has:

• Name — what shows up in the agent's submit-form picker (e.g. "Request Manager Approval").
• Description — optional context shown above the form when an agent submits it.
• Active flag — inactive forms don't appear in the agent picker.
• Fields — what the agent fills in.
• Lifecycle rule (optional) — what happens on submission. Configured under Form Lifecycle.
• Submissions — historical record, read-only.

Available field types include text, textarea, number, toggle (yes/no), dropdown, user picker, date, and datetime.

Each field has:

• Label — what the agent sees.
• Type.
• Sort order — fields render in this order.
• Required flag.
• Validation rules — type-specific (min/max for numbers, options for dropdowns, etc.).
• Help text (optional).

Creating a form

1. Navigate to Components → Custom Forms → Create.
2. Fill in Name, Description, and Active.
3. Save.
4. On the edit page, open the Fields relation manager.
5. Add fields one at a time. For each: pick the type, set label, set required/optional, set validation, set sort order.
6. When the structure is right, click Test Form to preview it as an agent would see it.

The form now exists but doesn't do anything beyond storing submissions. To make it actionable, you wire it to a form lifecycle rule (last lesson) — that's where you specify what should happen when a submission lands.

Wiring to a form lifecycle

Once the form fields are stable, navigate to Form Lifecycle → Create and pick this form. The lifecycle rule is where you configure:

• Notifications to send (e.g. "email the requestor's manager").
• Helpdesk actions to fire (e.g. "add a note to the ticket with the form contents").
• Sub-tickets or related records to create.
• Status changes on the underlying ticket.

A form without a lifecycle rule is just structured data collection. A form with a lifecycle rule is automation — the act of submission triggers the work.

Where forms appear for agents

Once a form is active, it shows up in the agent's submit-form picker inside the ticket widget. The agent:

1. Opens the ticket in the helpdesk.
2. Clicks Submit Custom Form in the ticket widget.
3. Picks the form from a dropdown (if multiple exist).
4. Fills in fields.
5. Submits.

If the form has a lifecycle rule, downstream actions fire immediately. Submissions appear in the form's Submissions relation manager, and on the ticket itself as part of its activity history.

You can also surface specific forms as named actions on agent or dispatch panels via Panel Settings (covered in the panel customization lesson). That moves a form from "pick it from the dropdown" to "a labeled button on the ticket card".

Validation, defaults, and field behavior

Two things to think about when designing fields:

Validation — every field can enforce rules. Min/max on numbers. Required on critical fields. Options on dropdowns. The agent gets a clear error if validation fails on submit, listing which fields are wrong. Don't over-validate — too many strict rules makes the form annoying and discourages use. Validate the things that downstream actions depend on, leave the rest open.

Defaults — fields can pre-populate from the ticket context (e.g. a Customer Email field that defaults to the ticket contact's email) to save the agent typing. --INSERT EXACT DEFAULT/PREFILL OPTIONS--.

Submissions — the audit trail

Every submission is stored against the ticket and the form. The Submissions relation manager on the form shows every time it was submitted: by whom, when, on which ticket, with all the field values. This is the data that makes forms more useful than internal notes — it's structured, queryable, and tied to a specific action.

Submissions also appear on the ticket itself, so reviewing a ticket later shows the full history of forms that were submitted against it.

Iterating on forms

Forms get better as you watch them in use. A few signals to act on:

• Agents free-text the same notes repeatedly — a form likely doesn't exist for that action yet. Create one.
• A form has fields nobody fills out — drop them or make them optional.
• A form's submissions are inconsistent — the field design is unclear. Tighten labels, add help text, add validation.
• A form's lifecycle rule fires the wrong thing — the rule needs adjustment, not the form.

Forms are cheap to add and cheap to retire (mark inactive instead of deleting; deletion is blocked if submissions or lifecycle rules reference the form).

When forms are set up correctly

• Repeatable agent actions are captured via forms, not free-text notes.
• Each active form has a clear name and a stable field set.
• Forms with downstream consequences are wired to form lifecycle rules.
• The Submissions relation manager shows steady usage on the forms you expect to be active.
• Test Form previews look exactly like what the agent sees in the ticket widget.

Tip: Don't build forms speculatively. Build them in response to "agents keep doing the same thing manually and getting it wrong half the time." A form is only worth creating if the action is repeatable, the structure matters, and the downstream consequence is real. A catalog of fifteen rarely-used forms is worse than three that everyone knows when to reach for.