Configure board columns and filters

Columns decide where matching tickets appear. Filters decide which tickets match the board at all.

Decide what the board should include

1. Name the review question.
2. List the issue types the board should show.
3. List the workflow statuses reviewers need to see.
4. Decide whether done-category work should be hidden.
5. Identify required custom fields for filtering, such as customer tier or severity.

Write this down before editing the board. It will help you avoid accidental hidden work.

Map workflow statuses to columns

1. Open Projects.
2. Open the target project.
3. Select Boards.
4. Select Edit for the board.
5. Go to Columns.
6. For each lane, add the workflow statuses that belong there.
7. If a lane has multiple statuses, choose the default drop status.
8. Move columns left or right until the order matches the workflow.
9. Review the Unmapped section.
10. Save after previewing the board.

Example mapping:

Column	Statuses	Default drop status
Backlog	backlog, todo	todo
Doing	in_progress, blocked	in_progress
Review	in_review	in_review
Done	done	done

Hide a status intentionally

1. Confirm another board, list view, or saved query will review that status.
2. Remove the status from the board's columns.
3. Add the reason to the board description.
4. Preview the board.
5. Check the hidden-status warning in Tickets after saving.

Do this for statuses such as archived or canceled when the board is meant for active operations. Do not hide blocked or in_review unless there is another process watching them.

Build the board filter

1. Go to the board editor Filters step.
2. Choose visual issue-type filters first.
3. Select Apply filters to generate TQL.
4. Add more conditions in the TQL editor.
5. Keep the query readable enough for another project admin to maintain.
6. Preview the board before saving.

Common patterns:

type != epic

type IN (task, bug, story, subtask) AND status_category != done

project = APP AND cf.customer_tier = enterprise AND status = open

Use custom fields in board TQL

1. Confirm the board is scoped to one project.
2. Confirm the custom field exists in that project.
3. Use the field key with the cf. prefix.
4. Use option keys, not only display labels, when filtering select fields.
5. Preview the board.

Example:

cf.severity IN (high, critical) AND status_category != done

Custom-field TQL only works when the project scope is unambiguous.

Troubleshoot a missing card

1. Search for the ticket by issue key in Tickets.
2. Switch from board to List view.
3. Check whether the ticket matches the board TQL.
4. Check whether the ticket type is included.
5. Check whether the ticket status maps to a board column.
6. Check whether the ticket is archived or done-category work hidden by the filter.
7. Check project scope and permissions.
8. Edit the board or ticket after you find the mismatch.

Troubleshoot a blocked move

1. Open the ticket.
2. Check its current status.
3. Check the destination column's default status.
4. Review the project workflow transition from current status to destination status.
5. Fill missing required fields.
6. Confirm the mover has the minimum project role.
7. Try the move again.

Related concepts: Project boards, Workflows, TQL query language.