Custom fields
Enterprise feature (new in 1.20.6,
helpdesk). See the Helpdesk overview.
A ticket has a priority, a team, an owner, a category and tags. A custom field is anything else your teams need to record on a ticket: a device type, an order number, a location, a date something is promised for.
A desk admin creates the fields and assigns each one to the teams that need it. Every ticket of those teams shows the field in its side panel, and agents fill it in there.
Until you add a field, tickets look exactly as they always have.
Adding fields
Section titled “Adding fields”Desk settings → Forms and fields → Custom fields lists the fields. It needs the desk capability Helpdesk settings (Admins, out of the box).
New field opens the editor:
- Label: what agents see beside the field, such as “Device type”.
- Kind: one of the kinds below.
- Help line (optional): one sentence shown where the field is filled in.
- Options: for a “Pick one” field, the choices. Each can carry a short hint.
- Teams: All teams, or Chosen teams and one or more teams.
- Who sees it: Agent only or Public (see Agent only and Public).
| Kind | What an agent enters |
|---|---|
| Short text | One line, up to 500 characters. |
| Long text | Several lines. |
| Pick one | One of the field’s options. |
| Yes / no | Yes, No, or nothing yet. |
| Date | A calendar day. |
| Date and time | A day and a time of day, as the clock reads it. |
| Number | A number. |
| A person | Someone with an account in the workspace. |
These are the same kinds a request type’s form and a Before you solve closing field use.
The key
Section titled “The key”Each field has a key, made from its label when you create it
(“Device type” becomes device_type). The editor shows it as you type.
The key is unique and never changes, even when you rename the field,
so the API, webhooks and the Claude connector
can rely on it.
The list
Section titled “The list”Each row shows the field’s label, Public or Agent only, its kind and options, its teams, its key and how many tickets hold a value for it. From the row you can:
- Move up and Move down: tickets list the fields in this order.
- Edit: change the label, help line, options, teams or who sees it.
- Archive: see Archiving and deleting.
- Delete.
Editing a field later
Section titled “Editing a field later”- Renaming a field or an option changes what people read. Values stay.
- Removing an option from a “Pick one” field: tickets that chose it still show it. It can’t be chosen again.
- The kind can change freely while no ticket holds a value. After that it can only change between Short text and Long text. To change it further, archive the field and add a new one.
- Changing the teams takes effect at once: tickets of a team you remove stop showing the field (their values are kept), and tickets of a team you add show it.
On a ticket
Section titled “On a ticket”A ticket whose team has fields shows a Custom fields card in the side panel, under the properties. Each field is edited in place:
- Pick one and Yes / no open a menu. None clears the value.
- Short text, Number, Date and Date and time open a small box to type in. Saving it empty clears the value.
- Long text reads under its label, with a pencil to edit it.
- A person opens a people picker.
Anyone who can work the ticket can fill in its custom fields, the same as its category and tags. Each change leaves a line on the ticket’s timeline (“Ana set Device type to Laptop”), which only agents see.
A ticket with no team shows only the fields set to All teams.
The filled-in fields are printed with the ticket’s details when you print it or save it as a PDF.
Moving a ticket to another team
Section titled “Moving a ticket to another team”When a ticket moves to another team it shows that team’s fields.
Values already filled in are kept. A field that isn’t assigned to the new team is simply not shown. If the ticket comes back, or you assign the field to the new team too, the value is there again.
Agent only and Public
Section titled “Agent only and Public”- Agent only: only agents see the field. It never reaches the requester: not on their request, not in any email, not in the customer portal, and not in their personal data export.
- Public: agents and requesters see it. Once it has a value, the requester sees it, read-only, in a Details card on their request in Get help and in the customer portal. An empty Public field is not shown to them.
Only agents fill in custom fields. Requesters can’t edit them.
In the ticket’s side panel, a Public field has an eye beside its label, so agents know the requester will see what they enter.
Things worth knowing:
- Switching a field from Public to Agent only hides it from requesters at once. Nothing is left behind in their conversation, because the timeline lines of custom fields are always agents-only.
- The customer portal doesn’t show A person fields, as it never shows a colleague’s full name to a customer.
- Requester emails don’t carry custom fields, Public or not.
Requiring a field before a ticket is solved
Section titled “Requiring a field before a ticket is solved”A Before you solve requirement set can require a custom field. On the set’s page, under On the ticket, pick it from A custom field. It joins the list as “A custom field: Device type”.
When an agent solves a ticket whose field is still empty, the Before you solve dialog asks for it, and saves it with the solve. A field that isn’t assigned to the ticket’s team, or is archived, is not asked for.
Archiving and deleting
Section titled “Archiving and deleting”- Archive takes a field off every ticket and out of the Before you solve dialog. Its values are kept. It moves to the Archived list; Restore brings it back, with every value.
- Delete removes the field and every ticket’s value for it. It asks first and says how many tickets hold a value. Deleting can’t be undone. A requirement set that required the field stops requiring it.
A deleted team drops out of its fields. A field whose teams are all gone is shown on no ticket until you give it a team.
Filtering the queue by a custom field
Section titled “Filtering the queue by a custom field”From 1.20.8 the queue’s Filter dialog has a Custom fields block. Choose Add a custom field…, pick a field, then a condition that fits its kind:
| Kind | Conditions |
|---|---|
| Pick one | is any of: tick one or more options, and Not filled in if you want those too |
| Yes / no | is Yes, is No, is not filled in |
| Short text, Long text | contains (any case), is empty, is not empty |
| Number | equals, is at least, is at most, is empty |
| Date, Date and time | is on, is before, is after, is empty. A date and time is compared by its day, as entered (the workspace’s time zone) |
| A person | is (pick the person), is empty |
- Add up to 10 fields, one condition each. Every condition must match, together with the dialog’s other filters.
- Teams. A field only has a value on the teams it is for. A condition never matches a ticket of another team, even one that kept a value from before it moved. Not filled in and is empty count only tickets of the field’s teams (every ticket, those with no team too, for an All teams field).
- The list shows each condition as a chip under the Filtered line, such as Device type: Laptop, Phone. The chip’s × removes that condition.
- Save view keeps the conditions with the view. See Saved views and filters.
- Archived fields are not offered for new conditions. A saved view that already uses one keeps working, and its Filter dialog marks the field “(archived)”. A view whose field was deleted shows “This field was deleted” in its Filter dialog; remove the condition to show the list again.
- Export CSV gives each live custom field a column of its own.
The API, webhooks and the Claude connector
Section titled “The API, webhooks and the Claude connector”- REST API:
GET /tickets/{number}carriescustom_fields, andPATCH /tickets/{number}sets them.GET /custom-fieldslists the fields. From 1.20.8,GET /ticketsfilters by them withcf.<key>=<condition>(Filtering by a custom field), andhd_queuetakes the same conditions ascustom_fields. See API tokens and webhooks. - Webhooks: the
ticketin every delivery carriescustom_fields, andticket.updatedlistscustom_fieldsinchangeswhen one changed. - Claude connector:
hd_read_ticketlists the ticket’s fields with their keys, kinds, options and values (custom_fields).hd_update_tickettakescustom_fields. The requester’shd_read_requestshows only Public fields that have a value.
Integrations that act as an agent read agent-only fields too, as an agent does.
Retention
Section titled “Retention”Anonymizing a ticket removes the values that are free text or name a person (Short text, Long text, A person). Choices, numbers, dates and yes / no answers stay. Deleting a ticket deletes its values.
Not in this release
Section titled “Not in this release”- Requesters can’t fill in custom fields, and request forms don’t feed them.
- Reports can’t be split by a custom field, and the queue’s list has no custom field column (filter by it, or export the list as CSV).
Limits
Section titled “Limits”| What | Limit |
|---|---|
| Custom fields, archived ones included | 100 |
| Options in one “Pick one” field | 50 |
| Teams one field names | 100 (or All teams) |
| A label | 80 characters |
| A help line | 500 characters |
A change to a field takes effect at once on the server that saved it, and within 30 seconds on any other.
Upgrading
Section titled “Upgrading”There is nothing to do. No fields exist until you add one, and tickets, requests and integrations work as before. 1.20.8 (filtering and Export CSV) adds no table or column, and saved views made before it work as they did.
In the audit log
Section titled “In the audit log”| Action | Shown as |
|---|---|
helpdesk.custom_field.created |
Created a helpdesk custom field |
helpdesk.custom_field.updated |
Changed a helpdesk custom field (records what changed) |
helpdesk.custom_field.archived |
Archived a helpdesk custom field |
helpdesk.custom_field.restored |
Restored a helpdesk custom field |
helpdesk.custom_field.reordered |
Reordered the helpdesk custom fields |
helpdesk.custom_field.deleted |
Deleted a helpdesk custom field (records how many tickets held a value) |
