Custom Forms

This guide covers building, publishing and versioning a custom form, attaching it to tickets, change requests, assets, sites, projects and project tasks by rule, publishing it to the client organizations an MSP manages, filling it in from the customer portal and the staff portals, and reviewing and exporting the responses.

Audience: organization administrators, MSP administrators and technicians, and anyone supporting them.

What it is

A custom form is a set of typed questions your organization writes itself, attached to records by rule and filled in alongside them. A form has a draft you edit, a published version people fill in, one or more placement rules that decide where it appears and to whom, and the responses collected against it. Published versions are frozen: editing a live form opens a new draft, and every response stays pinned to the version that asked its questions.

Forms live under Settings → Forms in both the organization portal (/org/settings/forms) and the MSP portal (/msp/settings/forms). The two screens are identical; what differs is whose records the rules reach.

Concepts

Roles and permissions

The role hierarchy is platform administrator > MSP administrator > MSP technician > organization administrator > power user > CUSTOMER`.

“Customer portal” below means a request made from the /user portal, or by anyone holding the CUSTOMER role in any portal. Every other request is a staff request.

¹ The share list is the set of client organizations your account manages. An organization that manages no other organization sees “You do not manage any other organizations, so there is nobody to publish this form to.”

Three things to know about the floor:

• Every authoring write is floored at organization administrator, not MSP technician. MSP technician ranks above organization administrator in the hierarchy, so an MSP technician floor would lock out the organization administrators the feature is largely for. Both MSP roles clear the floor.
• Reads on the library are open to any signed-in user with an organization, so a technician can see which forms exist. The Settings → Forms navigation entry itself is shown only to users who can manage settings (organization administrator in the organization portal, MSP administrator in the MSP portal).
• The customer portal is limited by audience rather than by role: it never receives a staff-only placement, its answers, the Responses tab or the CSV export; it cannot remove answers and may correct only its own.

Walkthroughs

Building and publishing a form

1. Go to Settings → Forms and choose New form. Enter a name (for example “New starter details”) and Create. The editor opens on the Build tab. The header reads “Draft — nobody can see this form until it is published.”
2. Add questions from the palette on the left. It is grouped by how you think about the question — Text, Choice, Number, Date & time, Records, Layout — and each entry has a one-line hint. A new question lands in the selected section, or in the last section, or in a section created for it.
3. Select a question to edit it on the right: label, help text, placeholder, Required, width (full, half or third), and the validation that applies to its type. See Configuration for the full list.
4. Use Add section to group questions, and Move up / Move down on sections and questions to reorder. Everything is reachable from the keyboard.
5. To branch, open a question’s Show this question when… rule, pick an earlier question, a comparison (“is”, “is not”, “contains”, “does not contain”, “is answered”, “is not answered”, “is more than”, “is less than”) and a value. A section can carry a rule too, and a question inside a hidden section is hidden regardless of its own rule.
6. Choose Preview to see the form exactly as responders will, including the branching. Back to editing returns.
7. Save draft at any time. A draft saves even while it has problems; the Build tab lists them.
8. Publish. If any problem remains, publishing is refused and the list is shown under “This form cannot be published yet”. Otherwise the header changes to “Version 1 is live and up to date.” Publishing also saves the draft first, so the version that goes live is what you see on screen.

Attaching a form to ticket categories

1. Open the form and choose the Placement tab.
2. Under Attach to, choose Tickets and Add rule. A rule with no conditions matches every ticket.
3. In the rule, set Shown to (The person raising it, Staff working it, or Everyone) and When (When the record is created, or Any time, on the record).
4. Tick Must be filled in if the ticket should not be created until this form is answered. It is not available for an any-time rule, which has no moment to block.
5. Under Only when…, choose the ticket categories, types, priorities and queues the rule applies to. Values within one list are OR; different lists are AND. Categories match by prefix: a rule on Access also matches Access / New Starter, and does not match Accessories.
6. Rules save as you change them. If the form is still a draft, the tab says “Rules are saved now and take effect once the form is published.”
7. Confirm from the other side: Settings → Ticket categories shows the form’s name against each category the rule covers, linking back to this tab. Queues, change templates and project templates carry the same label.

The same tab attaches a form to change requests (by type, category, risk level and template), assets (by type, category and status), sites and locations (by type), projects (by template and status) and project tasks (by the project’s template).

Filling in a form on a record

On a create page — the organization’s and the MSP’s new-ticket pages, the customer portal’s New request, the new-change wizard, asset intake and new project — any form placed for creation and matched by what has been chosen so far appears in place, marked Required where the rule says so. The page validates the form before creating the record and lists any problem against the question. Once the record exists, the answers are saved against it. A required form is always saved; an optional form is saved only if something was entered in it.

On an existing record — the ticket, change, asset, site, project and task screens — every placement for that record type and record appears under Additional information. An unanswered form offers Fill in; an answered one shows the answers read-only with Edit and Remove. The save button reads Save answers, and a saved form confirms with “Answers saved.” Answers are shown against the version they were collected under, so a question removed since still shows its answer.

An MSP technician opening a client’s ticket, change, site or project sees the client’s forms there and can answer them; the answers belong to the client.

Publishing a form to managed clients

MSP portal, on a form you author.

1. Open the form and choose the Sharing tab. It lists the client organizations your account manages.
2. Tick each organization that should receive the form and choose Save.
3. The client now sees the form in its own Settings → Forms list with the badge “From ”. Opening it shows “Published to you by . You can attach it to your records and read the answers; only they can change what it asks.” The client can Duplicate it into a copy it owns and edit that.
4. Untick an organization and save to withdraw the form. Withdrawal deactivates the share rather than deleting it, so re-ticking restores exactly what was there.

The per-client option Let them decide where it appears in their own portal records a placement right on the share. See Limits and known behaviour before relying on it in this release.

Reviewing and exporting responses

1. Open the form and choose the Responses tab. The tab shows the response count.
2. A row collected under an older version shows blanks where that version had no such question.
3. Export CSV downloads every response as a UTF-8 CSV that opens cleanly in Excel, with the same columns plus Submission ID, Organization, Attached to, Record ID, Submitted by and Submitted at. Choice answers export as their labels; person, asset and site answers export as the stored reference.

An MSP reviewing a form it published sees its own responses and every managed client’s; a client sees only its own.

Changing a live form

1. Open the form and edit on the Build tab. The header changes to “Version N is live. Your changes are not live until you publish.”
2. Save draft as often as you like. People filling in the form continue to see version N.
3. Publish changes to release version N + 1, or Discard changes to throw the draft away and return to version N. Discarding asks for confirmation: “This form goes back to version N — the one people are filling in right now. Anything edited since is lost.”
4. Changing a question’s Field key on a form that already has responses shows a warning, because answers are stored under the key and old answers would no longer line up with the question.

To retire a form, choose Archive (or Delete, if nothing was ever submitted against it) from the list. An archived form stops appearing everywhere, keeps its rules, and can be Restored to a draft. A form with responses is never deleted.

Configuration

Question types

Question settings

Accepted by the API but not offered in the builder in this release: a validation pattern with patternMessage, a numeric step, and a defaultValue.

Form settings

The Settings tab carries everything about a form that is not a question and not a rule. The form’s name stays in the header, edited in place.

Settings are merged on update, not replaced, so this tab and the header cannot clobber each other.

Placement settings

Condition keys that do not belong to the chosen record type are stripped on save, so a control that does nothing is never shown back to you.

Sharing settings

Plan tiers

Custom forms carry no plan gate. Building, publishing, placing, sharing, collecting and exporting are available on every tier, including Free, in both the MSP and end-customer tier families.

The one plan-linked limit is storage. Every file answer counts toward the account’s storage allowance, and an upload that would exceed it is refused before anything is written, with a message and, where a larger plan exists, an upgrade prompt.

Limits and known behaviour

• Sizes. Name up to 150 characters; description 2,000; 50 sections per form; 200 questions per section; 200 options per choice; 10 conditions per display rule; labels 300 characters; instructions blocks 4,000; field keys lowercase letters, digits and underscores, up to 64, starting with a letter; up to 500 share targets; files 25 MB each and at most 20 per question; CSV export up to 10,000 responses; list pages up to 100 forms and 200 responses.
• Where forms appear. Create pages: organization and MSP new ticket, customer portal new request, new change wizard, organization asset intake, new project. Record pages: ticket (organization and MSP), change, asset (organization), site, project hub, and the task editor when editing an existing task. Forms placed on a new task appear only once the task exists.
• Resolve and close triggers. “When it is resolved” and “When it is closed” are evaluated. A form on either trigger does not appear on the record until it reaches that state, and a required one blocks the transition: resolving or closing a ticket with an unanswered required form is refused with “Fill in … before resolving it.” Two deliberate exceptions: a required form whose audience is the person raising it never blocks staff (they cannot answer it), and a customer accepting a resolution from their own portal is never blocked either. If the check itself cannot be run, the transition is allowed — a form gate must not freeze a queue.
• Placing a shared form in the client’s organization. The Placement tab takes a target organization. An MSP sees its own organization plus every client it has shared the form to; a client that a form was shared to sees its own organization, and only when “Let them decide where it appears” is ticked. A rule that lives in an organization you cannot write to is shown but not editable. A client is never told which other organizations the form was shared with, or where they placed it.
• Customer portal after submission. The customer’s request detail page shows the forms pointed at the requester, with what they submitted. They can correct their own answers where the form allows it.
• Per-record visibility. A customer-portal reader must be able to see the RECORD, not just its organization: the ticket’s own service is asked whether the request is theirs. Staff are unaffected. If that check cannot be run the answer is “no”, so a customer may briefly see no forms on their own request rather than someone else’s answers on another.
• Record pickers render as a dropdown of the organization’s people, assets or sites and store the reference. The responses table shows the stored reference; the CSV export resolves it to the person’s name, the asset’s name or tag, and the site’s name.
• Draft responses. Saving a response with status: DRAFT skips required questions but still type-checks and still drops hidden answers. The screens always submit; drafts are reachable through the API. A draft never satisfies a required form on resolve or close.
• Abandoned uploads. A file uploaded on a create page that is then abandoned stays in storage under the tenant’s prefix until the tenant’s data is erased.
• Audit log. Publishing, sharing, archiving and answering write to the platform audit log (FORM_PUBLISHED, FORM_SHARED, FORM_ARCHIVED, FORM_SUBMITTED) alongside the attribution on the rows themselves.
• Notifications. The people named under Who hears about it are notified in the app the first time a set of answers is submitted. Corrections afterwards do not notify again, nobody is notified about their own submission, and anyone who has left the account is dropped.
• Not on mobile.

Troubleshooting