Folder: tasks/

Kanban-style task management for tracking internal work — separate from tickets, which represent end-user-raised issues. Tasks are for the IT team's own work: project follow-ups, admin items, things spawned out of a ticket but tracked separately.

Tasks can repeat — daily, weekly, monthly or yearly, on chosen weekdays, on a day of the month including the last, or on a named weekday such as the third Monday — either when you complete the last one or on a fixed schedule. See Repeating tasks.

🔴 A repeat set to a fixed schedule needs cron/task_recurrence.php running. Without it nothing is created and nothing warns you — see Scheduled tasks.

The Table view opens a task from the open icon at the start of each row, or Open on the right-click menu: the panel the Calendar and Timeline use slides in over the table, so the filters, sort and scroll position stay put. It is a quick look (status, dates, assignee, the description) with an Edit button that turns it into the full task in the same panel - the board's own editor, with subtasks, checklists, forms and comments. To always get the full task from the Table, Calendar and Timeline, choose The full task under Preferences → Opening a task (per analyst; the quick look is the default). Its launch icon goes to the task on the board. Developers: the full task is tasks/embedded.php?host=tasks in a frame - the ticket workspace's embedded editor with no ticket, checked by analystCanAccessTask() - and TasksQuickPanel asks it before closing (freeitsm:task-embed:leave), so an unsaved edit is never dropped. Ctrl- or middle-click the icon to open the full task in a new tab. Clicking a cell still edits it in place (#219). Developers: the open link is the shared table engine's rowOpen option (assets/js/data-table.js) - a real link, with a plain click handed to onOpen - so any other table can have one; tests/data-table-row-open.php covers it.

The Table view supports saved views: save the columns, sort and filters under a name, share it with a team or everyone, and set one as the view the table opens with.

The same tasks are presented through four views. A change made in one is reflected in all of them.

• Board (tasks/) — a Kanban board with one column per status (see below), drag-and-drop card movement, and drag-to-reorder columns
• List (tasks/, View toggle) — a sortable table; click any column header to sort, click again to reverse
• Calendar (tasks/calendar/) — a month grid placing tasks by due date, coloured by status
• Timeline (tasks/timeline/) — a Gantt-style chart, one bar per task from start date to due date

The board generates one column per active status from Settings → Statuses, in display order, each headed with the status's colour. Adding a status adds a column — there is no separate "column" concept. The three hardcoded To Do / In Progress / Done columns were replaced by this dynamic model, so custom statuses (e.g. Blocked, an Icebox) get their own column and nothing silently falls off the board.

Columns → Analyst in the left panel, under View, shows one column per person with tasks in view instead - yours first, Unassigned last - and each card carries a chip with its status. Dragging a card to another person's column assigns the task to them, through the same save as changing the assignee in the panel, so notifications and workflow events behave the same way. A task still assigned to an analyst who no longer exists sits under Former analyst #id rather than disappearing.

The choice is per analyst and remembered (user_preferences.tasks_board_group); nothing in the schema changed. Dragging columns to reorder them and the quick-add + are status features, so they are off in this mode. How it is built: Task board and subtasks — Developer Guide.

Card order in the left panel, under View, chooses how cards sit inside each column:

• Manual (the default) - the order cards were dragged into. This order is shared: everyone sees the same one.
• Due date - overdue work first, then work due today, then the rest by date; tasks with no due date come after those, and done tasks after everything open. Tasks with the same due date keep their manual order between them. On the board by analyst the date decides and status only breaks a tie.

Due date is a personal view (user_preferences.tasks_board_sort). It orders the display only - the shared manual order (tasks.board_position) is never rewritten, so switching back to Manual shows it exactly as it was. While sorted by due date, dragging a card to another column still moves it (it joins the end of that column's manual order); dropping it in the same column changes nothing, because its place there is decided by its date. To rearrange cards within a column, switch to Manual. Changing a task's due date moves its card straight away. How it is built: Task board and subtasks — Developer Guide.

Drag a column header left or right to reorder the columns — this rewrites the underlying task_statuses.display_order (via reorder_task_statuses.php), so the board and the Settings tab stay in sync.

• Drag a card to another column to change its status, or up/down within a column to reorder. Dropping into a Closed status stamps the completion time. A drag to another status tells the people on the task and runs workflows, exactly as changing the status from its menu does; reordering within a column tells nobody. (Before #266, dragging told nobody.)
• New (3.13.0, #185) — at the right of the action row under the module header, on every Tasks view (Board, List, Calendar, Timeline, Table). It asks for a title, creates the task in the default status assigned to you, and opens it. Hidden for Read only access.
• Quick create — the + on a column header opens an inline box; type a title, press Enter, and the task is created in that column's status, assigned to you.
• Right-click any card for a context menu — assign analyst, assign team, change status, change priority, or create a subtask — without opening the card.
• Configurable card fields — Settings → Card chooses which extras each card shows: assignee initials, team, start date, due date, a description excerpt (first 250 chars), subtask progress, and a linked-item indicator. Priority is chosen separately, below.
• Subtasks under the card (2.10.0) — a task's subtasks are listed beneath its card like branches of a tree, ticked or not, with a due date when one is set and not yet done. Click a subtask to open it (not its parent). They ride on the same subtask progress card setting as the 3/5 bar. Which ones are listed is each analyst's choice (#184): Subtasks on cards in the sidebar (also in Preferences) is All, Open — only the ones still to do — or None, just the count. Click a card's count (e.g. 1/4) to show or hide that one card's subtasks whatever the setting; both are remembered. Open replaced the older Preferences switch Hide them once all are complete, and anybody who had that on starts on Open.

Requested in discussion #108. Settings → Card offers four placements for a task's priority, rather than a simple on/off:

Placement	What appears
Hidden	Nothing
Dot	A coloured dot — the default
Dot and name	The dot, with the priority's name beside it
Left edge	A coloured stripe down the left side of the card

The choice follows the task everywhere it is drawn — the board, the timeline, and the subtask list inside a task — so all three read the same way. The list view is the one exception: it always shows the dot and the name, because that view is a table with a column headed Priority.

A live preview sits under the options, built from the real card markup so it cannot drift from the board. It previews your own default priority, so you see your names in your colours.

The colour is the one set against each priority under Settings → Priorities. Nothing is derived from the priority's name, so renaming or translating your priorities — or adding new ones — keeps the indicator working. This was not always true: see the priority dot was invisible if you had renamed your priorities.

A search box at the top of the sidebar filters the board and list as you type, matching task title and description (and tag names, if enabled). Multi-word queries are AND-matched. Filtering is client-side on the loaded task set, so it is instant.

Hide done (3.9.0, #184) — a tick in the sidebar's Show section leaves out every task in a closed status, on the board and the list. On the status board the closed columns (Done, Cancelled) go too, since they could only ever be empty. Remembered per analyst, like Board/List. A done task never shows Overdue or Due today anyway — before 3.9.0 the card and the list said Overdue for a task finished late.

A month grid (Monday-first) with prev / next / today navigation and a status-colour legend. How a multi-day task (start date earlier than due date) is drawn is configurable per-install in Settings → Calendar:

Mode	Behaviour
Deadline chip (default)	One chip on the due date only — tidiest
Spanning bar	One continuous bar across the range, wrapping at week rows, lane-stacked so bars never overlap
Every day	A chip in every day cell the task covers

A task with only a due date always shows as a single chip whatever the mode. Clicking a task deep-links to the board with its panel open (?task=N).

A Gantt-style chart. Each task with at least one date is a horizontal bar from its start date to its due date (a due-date-only task is a single-day bar). Rows group by assignee, status, or flat; a dashed marker shows today; the task-name column and date header stay put while scrolling; and a zoom control switches the day-column width.

A slide-in panel; every field auto-saves the moment it changes (no save button):

• Title, Status, Priority — status/priority dropdowns are built from the configured lookups
• Assignee and Team
• Start Date and Due Date — together they define the span shown on the calendar and timeline
• Estimate (hours) (3.3.0) — how long the work should take. Optional; Projects reads it for estimate-against-logged and the Capacity page
• Tags — a type-to-filter picker (see below)
• Description — TinyMCE rich text
• Links — searchable attach of related tickets / changes
• Subtasks and Comments
• Work starts / Work ends and All day — when the task is planned for. Naive wall-clock values: a 2pm slot reads 2pm for everybody, exactly like a ticket's scheduled work
• Time — how long the work actually took, as many sittings as it needed, each with a note, totalled. A parent also shows the total including its subtasks. Unlike the fields above, these are real instants and convert to each reader's timezone

The delete button removes the task and all its subtasks (with confirmation). An occurrence of a repeat can be refused deletion, or kept as Removed in its evidence - see Settings → Evidence.

With Settings → Checklists → Forms on tasks on, a task can need forms from the Forms module - Required, Required (warn) or Optional - filled in for that occurrence, with a shared draft, linked automatically and checked before the task completes. A repeating task's occurrences each start unanswered. See Forms on tasks. A Work section (the Work tab, in the tabs layout) brings the task's instructions, Knowledge procedures (whose text is kept when the task is completed), checklists and forms together with progress and Complete - see The Work view.

A History tab (or section, in the panel) lists everything that happened to the task, newest first: who created it - a person or the repeat - status changes, who completed it, reopening, due-date, start-date and assignee changes, skips, checklists attached and removed, and every checklist step tick, untick, value and result. It cannot be edited, and it outlives the task. See Repeating task evidence.

The panel slides in from the right by default, which keeps the board visible behind it. The expand button in its corner swaps to a large, nearly full-screen window that lays the same content out in two columns — description, subtasks and comments on the left, the short fields down a narrow right-hand column, the title across the top. It collapses back the same way.

The choice is remembered per analyst and can also be set at System → Preferences → Opening a task. Both write the same tasks_detail_view preference, so they always agree. Below 1100px the window falls back to a single column, and on a phone it fills the screen. In the tabs layout (the button beside expand), the Details tab fits as many fields to a row as the window allows - six on a wide screen - with the people involved, tags, checklist, repeats and the description each on a full row, so the description is on screen without scrolling (3.9.0).

Most of the panel is reachable without opening the task:

Open	Opens the task in whichever view you prefer
Assign to me	One click, no submenu
Involve me / Stop being involved	Follow a task without owning it (People on a task); not shown on your own tasks
Assign analyst / team, Change status / priority	Submenus built from the configured lookups
Due date	Today, tomorrow, next Monday, or clear it
Mark complete / Reopen	Decided by the status's Closed flag, so it still works if you rename Done
Log time	Opens the task with the cursor in the minutes box. Absent where Settings → Time excludes that kind of task
Create subtask, Copy link, Delete	Delete names the task and asks first

The board and the open task catch up with other people's changes within about 15 seconds; a card being dragged, an open menu or a field being typed in is never redrawn from under you. See Live updates.

A workflow can set a task's status, give it an owner or add a comment. A comment from a workflow shows as written by System, and the task's History says a workflow made the change, naming it. Completing a task from a workflow follows the same rules as completing it yourself: required checklist steps or forms set to block stop it.

Multi-value labels for cross-cutting themes — e.g. Security, ISO, Environment (seeded as defaults). Status answers "what stage?", priority "how urgent?", and a tag "what is this about?" A task can carry any number of tags.

Tags are managed in Settings → Tags (each a name + colour). Five Display options there govern tagging:

• Allow new tags from a task — off = a fixed, governed vocabulary (tags added only in Settings); on = analysts can create tags inline from the task picker
• Card chips — coloured tag chips on board/list cards
• Sidebar filter — a tag filter dropdown in the board/list sidebar
• Search matching — the search box also matches tag names
• Calendar & timeline — small tag dots on task bars in those views

Two-level hierarchy (a subtask is a tasks row with a parent_task_id). Parent cards show a progress indicator (e.g. 3/5) and, since 2.10.0, list the subtasks themselves (see Cards above).

Inside the task, each subtask is a row: a ⋮⋮ handle, the tick box, its priority and title, who has it, and its Start and Due dates in two columns that line up down the list. Where that does not fit — the side panel, a phone — each subtask takes two lines: its name across the full width, then who has it and the two dates under their headings (#184: before 3.9.0 the side panel squeezed the name out entirely).

• Tick the box to complete it; click the row to open the subtask.
• Change a date in place. Saving one does not rebuild the window, so you stay where you were (and on the Subtasks tab, if you use tabs).
• Drag a row by its handle to change the order. The board lists them in the same order. Only the handle starts a drag, so clicking a row or selecting its text behaves as before.
• Adding one: type a title, optionally give a start and a due date, press Enter or Add. A new subtask goes to the bottom of the list.

How it is built: Task board and subtasks — Developer Guide.

Subtasks or a checklist? A subtask is a piece of work with its own owner and due date. A checklist is the steps of one job, ticked off by whoever is doing it - and it can stop the task being completed until its Critical steps are done. Checklists on tasks are off until switched on (see Settings below).

A task can be attached to:

• A ticket — when a ticket leads to follow-up work ("order the replacement PSU")
• A change — pre-implementation prep tied to a change request
• A contract — work carried out under a support agreement

A task belongs to at most one ticket. A ticket, though, can have as many tasks as it needs — the link is a column on the task, so several tasks can point at the same ticket.

Tickets show their tasks, and can create them. In the Links bar at the top of a ticket — the same bar that holds problems, changes, equipment and CMDB objects — choose Link to… → Task:

• One box does both jobs. Typing searches your existing tasks and offers to create a task with exactly what you typed. You see the near matches as you type, which is what stops a second copy of a task that already exists.
• A task created here is assigned to you and takes the ticket's company, so it lands on your own list and alongside that client's work.
• The pill shows progress — ☐ while outstanding, ☑ once done, and a fraction such as 2/5 when the task has subtasks.
• Right-click a ticket in the list and choose Link to task… to attach one without opening the ticket.
• The ✕ unlinks, it does not delete. The task stays in the Tasks module; deleting is done from the task itself.
• Closing a ticket with unfinished tasks warns you, but never blocks — the outstanding work is often somebody else's by then.

A task and the ticket it is attached to must belong to the same company. That holds even for staff who can reach both, because a scope check alone would happily let one client's task be attached to another's ticket. See Multi-Tenancy Progress.

The link is visible from the task, in its detail panel. Changes and contracts do not yet list the tasks attached to them — only tickets do. That is the obvious next step if it turns out to be wanted.

Every view shares the sidebar filters:

• My Tasks / All Tasks
• Team
• Analyst
• Tag (when the sidebar-filter tag option is enabled)
• Project (3.2.0) - All projects, Not in a project, or one project; shown only when a task on the board belongs to a project

A project's work items are ordinary tasks, so they stay on this board for the people doing them. A card that belongs to a project shows a chip with the project's name in its colour, and the task window has a Project field for top-level tasks (a picker for analysts who can open Projects, plain text for everyone else). Deleting a project never deletes its tasks. See Projects.

When an outside firm does the work, give the task to a contractor: in the task window, Contractor is a supplier from Contracts and Contact there is a person at that supplier (optional). The Assignee stays the person here who owns the task and chases them. Choosing a contractor needs access to Contracts; anyone who can see the task sees the firm's name.

Hiding the contractor fields (4.9.0). Under Tasks -> Settings -> Involved -> Contractor fields on tasks, choose Hide - for the whole install, or per company. The Contractor and Contact there fields and the sidebar Contractor filter disappear from the task screen; the assignee stays. A task that already has a contractor still shows it, read-only, with a note, and saving anything else on the task never touches it. This only tidies the task screen: Projects and the REST API can still assign contractors. To switch contractors off entirely, turn off the Contracts module.

The card shows the firm (and person), and a Contractor filter appears in the left panel once any task has one: one firm, With a contractor or Not with a contractor. Projects can email the person at the firm when they are given a task and when it is due - off unless someone turns it on. See Projects - Contractors.

tasks/settings/ has nine tabs:

Tab	Configures
Statuses	Workflow states (= board columns) — name, colour, display order, default, Closed flag, active flag
Priorities	Priority bands — name, colour, default. The colour set here is the colour drawn on cards, the timeline and subtasks
Calendar	Multi-day render mode — deadline chip / spanning bar / every day
Card	Which extra fields appear on board cards, and how priority is shown — hidden, dot, dot and name, or a left-edge stripe
Tags	The tag list, plus the five tag display options
Time	Where scheduled work and time entries are offered: tasks, subtasks, both, or nowhere
Involved	Whether each person on a task ticks off their own part (GH #89)
Checklists	Whether tasks can carry checklists from the Checklists module (off by default, 2.10.0) - see Checklists on tasks
Evidence	Whether a completed task's checklist can still change, whether an occurrence of a repeat can be deleted, the status a skipped occurrence moves to, and who can run the evidence report (#181) - see Repeating task evidence

Module options (tasks_calendar_span_mode, tasks_card_fields, tasks_tag_settings, tasks_time_scope, tasks_collaborator_completion, tasks_checklists_enabled, tasks_evidence_*) are stored as keys in the shared system_settings table.

Tasks can be granted at the Read only level (System → Module access), like Change Management and Forms: the person can open every task and its history and change nothing. With the Run the evidence report permission that makes an Auditor role. See Repeating task evidence.

The whole module — PHP pages and JavaScript — runs through the shared i18n system. Strings resolve through t('tasks.*'), with lang/<locale>/tasks.php files for all 24 supported locales and per-key fallback to English. The active language follows the analyst's interface-language preference. Date formatting follows the page locale, so month and weekday names localise too.

tasks/help.php — a built-in scroll-spy guide (reachable from the Help link in the module header) covering the board, list, calendar, timeline, the task panel, tags and settings.

Overdue and due-today counts appear on the Watchtower attention dashboard so unfinished work surfaces alongside open tickets and pending changes.

The Contracts module's view page has Create Task and Add to Calendar buttons that open inline modals — they prefill sensible defaults from the contract (title, description, due date = notice date or end date, assignee = contract owner) and link the new task back to the contract via contract_id. See Contracts.

Table	Purpose
tasks	Core task record (subtasks are rows with parent_task_id; tenant_id is the owning company, NULL = Default)
task_statuses	Status lookup — drives the board columns
task_priorities	Priority lookup
task_comments	Threaded comments
task_tags	Tag lookup (name, colour)
task_tag_map	Task ↔ tag many-to-many junction
task_time_entries	Time recorded against a task — one row per sitting. Mirrors ticket_time_entries
tasks.assigned_supplier_id / assigned_contact_id	(3.3.0) The contractor doing the task - a supplier and a person there (suppliers, contacts); includes/task_contractors.php

---

• Projects - plans, phases and health built on top of tasks

• Task board and subtasks — developer guide — columns by analyst, subtasks under cards, re-ordering, the date columns, the tabs and their counts

• Time on tasks — developer guide — how the scheduled slot and the time entries are built, and the traps in the way

• Tasks on tickets — developer guide

• Record previews — the ⓘ beside a task's linked ticket or change

• Scheduled work in your own calendar — putting a task's work slot or its due date into Outlook, and what changes come back

• Timezones and time handling

A task links to at most one ticket and one change — tasks.ticket_id and tasks.change_id are single columns, not join tables. The search boxes stay visible once something is linked and offer to link one instead, and choosing a different record asks first, naming what would be unlinked.

The same warning appears from the other end: attaching a task that already belongs to another ticket moves it, so the Tickets picker marks such a row currently on TICKET-x and asks before doing it. Both sides of the relationship confirm, because it is one event and they should not disagree about whether it is worth confirming.

---

A task opens in the side panel by default; the ⤢ button in its header switches to a large window, and remembers which you prefer.

Inside the large window there is a second button, offering two shapes for the same task:

Layout	What it does
Two columns	The description, subtasks and comments down the left, the short fields stacked on the right.	the default
Tabs	Details · Subtasks · Time · Comments · Links · Documents.

A task carries a lot now — its fields, the people involved, tags, a description, repeats, links, subtasks, time recorded, comments and any attached documents — so reaching the comments can mean scrolling past all of it. Tabs put each part one click away.

Neither is imposed, and columns stay the default: one long page is genuinely better when you want to take the whole task in at once.

• Tabs holding a list carry a count — Subtasks (3), Comments (2), Documents (6) — so three subtasks behind a tab are never mistaken for none. The Documents count arrives a moment after the window opens, once the documents have loaded.
• They look like tabs (2.10.0): each one a raised tab on a line, the open one joined to the page below it, and all the same width, so the strip is evenly spaced whatever the labels say.
• An empty tab is not drawn. A subtask cannot have subtasks of its own, so it simply shows fewer tabs.
• The button appears only in the large window — there is nothing in the side panel it could apply to.
• On a phone the strip scrolls sideways rather than wrapping into three rows.

The choice is remembered per analyst, so it does not affect anybody else.