Custom Ticket Fields - edmozley/freeitsm GitHub Wiki

🧾 Custom ticket fields

Make up the extra details a kind of ticket needs, so they arrive with the ticket instead of in a chain of replies. A new starter needs a start date, a username and whether they work remotely; a purchase request needs a cost code; an access request needs the system. Tickets → Settings → Custom fields is where you create them.

Developers: see the Custom ticket fields - Developer Guide.

⚙️ Making a field

Tickets → Settings → Custom fields → Add.

Setting	What it does
Name	What the field is called on the ticket, the New ticket form and the portal
Kind of field	Text, Number, Date, Yes / no, Dropdown, Web address or Email address (see below)
Hint	A line shown under the field - "As it will appear in Active Directory"
Which ticket types is it on?	Every ticket type, or Only these types with a tick for each
Must be filled in	When the ticket is logged, Before the ticket is closed, both or neither (see below)
Ask the requester on the portal	Shows the field on the portal's New ticket form

Kinds of field

Kind	Notes
Text	One line, or tick Allow several lines
Number	Choose the decimal places, and an optional unit shown beside it - GB, days, £
Date	Records a date, a date and time, or a time
Yes / no	Has three answers: Yes, No and Not set. "Nobody has said" is never mistaken for No
Dropdown	The options are one per line, in the order they should appear. Only those options are accepted
Web address	Must start `http://` or `https://`
Email address	Must be an email address

A field's kind is fixed once a ticket has answered it. Everything else - the name, the hint, the types, the options, and whether a date records a time - can change at any time. The dialog says so when the kind is locked.

The ▲ ▼ arrows set the order fields appear in, everywhere.

✅ When a field must be filled in

Each field decides for itself:

When the ticket is logged - on the New ticket form, through the REST API, and on the portal for fields the requester is asked. The ticket cannot be created without it. Tickets that arrive by email or chat cannot be asked anything, so they are never refused for it - use the next option to catch those.
Before the ticket is closed - follows Tickets → Settings → Mandatory fields: warn, warn and email someone, or refuse the close. The field is listed by name alongside the built-in fields, wherever the ticket is closed - the ticket screen, bulk actions, the REST API and workflows.

Both can be ticked. A field required when logging also cannot be cleared later.

🎫 What analysts see

New ticket - pick the type, and its fields appear under the Department / Type / Priority row. Fields on every type show before a type is chosen. Required ones carry a red star.
The ticket - the fields sit in the ticket's properties panel beside the built-in ones, and each saves as you change it. Every change is in the ticket's history (Audit), with who made it.

Changing a ticket's type

The new type's fields appear. Answers to fields the new type does not have are hidden, never deleted - change the type back and they are all there again.

🌐 What requesters see on the portal

Only fields with Ask the requester on the portal ticked. Anything only your team should fill in - a username, an asset tag - is never shown to them.

When at least one asked field is on particular types only, the portal's New ticket form gains What kind of request is it?, with the ticket types the requester's company can see. Choosing New starter then shows the New starter's questions. When choosing a type would change nothing, the picker does not appear.

Required answers are checked again on the server, and a requester can never answer a field they were not asked, whatever they send.

Where the questions are asked (4.9.0, #218)

Tickets -> Settings -> Custom fields -> Where the portal asks these questions:

Choice	The New ticket page
In the side panel (the default)	As it has always been: the questions sit in the panel beside the description, with priority, attachments and Submit
In the main form	Subject, then the request type (when it matters), then the questions - two to a row on a wide screen - then the description - the order someone explains a request in. The description box gets a fixed height and the page scrolls, so several questions and their error messages have room. On a phone everything stacks in that order, with Submit at the bottom

Either way the questions, their order, hints and required markers are the same, answers survive a change of request type and a refused submit, and the server checks them as before.

Their answers on their ticket (3.13.0, discussion #193)

Once the ticket is logged, the requester sees what they gave under Your details in My Tickets. Tickets → Settings → Custom fields → Show requesters the answers they gave chooses where:

Under the ticket's title (the default) - a row of answers between the title and the conversation.
In a panel beside the conversation - down the right of the ticket. It needs a wide screen; on anything narrower, a phone included, the answers show under the title instead.
Do not show them.

They are the answers as they are now, so if your team corrects one, the requester sees the correction. Only fields with Ask the requester on the portal ticked are ever shown, and only answered ones. A manager who can see the ticket sees them too, under the same rule as the conversation. Changing this setting needs the same permission as designing the fields.

🏷️ The Department field (4.9.0, #218)

Tickets -> Settings -> Custom fields -> Department field has two choices, for the whole install and, on a multi-company install, per company (Follow the default hands a company back to the install-wide answer):

Choice	What it does
Department field: Show / Hide	Hide removes the field everywhere a ticket shows it: the ticket panel and workspace, the Dept line in the summary, New ticket, the bulk Department button and the right-click Set department. When every company on your board hides it, the Department folder grouping and the Department table column go too, and the folders show the Analyst grouping instead.
Department for new tickets	The department a new ticket starts in when nothing else gives it one - on every channel: New ticket, the portal, email, chat, web chat, the REST API, catalogue requests and workflows. A department chosen on the form, sent by the API or set by a catalogue item always wins.

Hiding only removes the field from the screen. A ticket keeps its department, nobody loses access to any ticket (departments decide folders and rules, not who may open a ticket), and workflows, SLA notification rules, department notifications and confidential departments all still use it. Switch the field back on and everything is as it was.

If Department is hidden with no default, new tickets have no department: they do not appear in any department's folder, and department SLA and notification rules do not apply to them. The settings panel warns you when that is the case.

Kept consistent for you:

Department cannot be hidden for a company while Mandatory fields requires it at closure - and it cannot be made mandatory while it is hidden. Either way you are told which company and how to fix it.
The default must be an active department, and a department that is somebody's default cannot be deactivated or deleted until you choose another default (or No default) here.
If a default stops being active anyway, new tickets are created without it, the ticket's history says why, and this panel shows a red warning until you choose another.

🧹 Retiring a field

The bin icon retires a field: it stops appearing on tickets and forms. Every answer already given is kept - nothing is deleted.

🏢 Several companies

A field made while working in the default company is shared by every company. One made while working in a client company belongs to that company and appears only on its tickets. A company sees the shared fields read-only - they are managed from the default company - the same way as ticket types.

🔐 Permissions

Design custom fields is its own permission (System → Roles, the Custom fields tab), because it decides what requesters are asked and can stop tickets being logged or closed. Filling a field in on a ticket is ordinary Tickets access.

🔌 REST API

GET /tickets/{id}, POST /tickets and PATCH /tickets/{id} carry a custom_fields object keyed by each field's key. See REST API: Tickets.

❓ Not in this first version

Using custom fields in workflow conditions, email template merge codes, report packs or search.
Link fields that pick a person, an asset or a configuration item.