Skip to main content

Add custom fields

Custom fields are project-specific ticket fields. Use them when a project repeatedly filters, reports, or reviews information that does not belong in standard ticket fields.

Decide whether you need a custom field​

  1. Name the decision or review that needs the data.
  2. Check whether a built-in field already covers it.
  3. Use labels for loose tags.
  4. Use a custom field for structured values that the team will maintain.
  5. Choose the narrowest field type that works.

Examples:

NeedField choice
Customer segment with controlled reportingSingle select
Affected environmentsMulti select
Launch dateDate
Severity scoreNumber or single select
ReviewerUser single
Freeform investigation notesParagraph

Create a custom field​

  1. Open Projects.
  2. Open the target project.
  3. Select the Fields tab.
  4. Enter Name.
  5. Review the generated Key.
  6. Choose Type.
  7. Add Description so admins know how to use it.
  8. If the type uses options, enter one option per line.
  9. Select Add field.

Option format:

enterprise=Enterprise
mid_market=Mid-market
startup=Startup

The left side is the stable option key. The right side is the label people see.

Choose stable keys​

  1. Use lowercase letters, numbers, and underscores.
  2. Start with a letter.
  3. Avoid project slang.
  4. Keep keys stable after teams start filtering on them.

Good keys:

  • customer_tier
  • severity
  • implementation_phase
  • target_launch_date

Changing the field name is safer than changing the key. TQL, boards, and workflow rules depend on keys.

Add the field to tickets​

  1. Create or open a ticket in the project.
  2. Find the custom field section.
  3. Enter the value or choose the option.
  4. Save the ticket.
  5. Filter or search for the value if the field will drive reporting.

If a field is required by a workflow transition, fill it before moving the ticket.

Use the field on a board​

  1. Open Projects.
  2. Open the project.
  3. Select Boards.
  4. Edit the saved board.
  5. Go to Card layout.
  6. Drag the custom field from Fields onto the card grid.
  7. Format the block.
  8. Preview the card.
  9. Save the board.

Use card fields only when reviewers need the value without opening the ticket.

Use the field in TQL​

  1. Confirm you are inside the project scope.
  2. Use cf.<key> in the query.
  3. Use option keys for select-style fields.
  4. Preview the result.

Examples:

cf.customer_tier = enterprise
cf.severity IN (high, critical) AND status = open

Require the field in a workflow​

  1. Open the selected project.
  2. Select Project settings, then Workflow.
  3. Open Workflows and edit the workflow that owns the transition.
  4. Choose or create a restricted transition.
  5. Add the custom field to Required fields.
  6. Save the workflow.
  7. Test the transition with a ticket missing the field.
  8. Fill the field and test the transition again.

Require values only when the work cannot safely move forward without them.

Edit options​

  1. Open Projects.
  2. Open the project.
  3. Select Fields.
  4. Select Edit on the field.
  5. Update Name, Description, Order, or Options.
  6. Put old option keys in Archived option keys when they should no longer be used.
  7. Select Save.

Archiving an option preserves older ticket values while keeping active choices clean.

Archive or restore a field​

Archive a field when the project no longer maintains it.

  1. Open Fields.
  2. Find the field.
  3. Select Archive.
  4. Review saved boards, TQL filters, card layouts, and workflow rules that used it.

Restore a field when the process becomes active again.

  1. Open Fields.
  2. Find the archived field.
  3. Select Restore.
  4. Confirm boards and workflows still use it correctly.

Related concepts: Custom fields, TQL query language, Design board cards.