Projects, boards and tasks
What a project holds, the projects list and its filters, the task board with drag and drop and keyboard moves, what a task holds, project files, and archiving and restoring.
For the Full Stack package
What a project holds
| Part | Values |
|---|---|
| Name and description, in English and Arabic | The English name is required (up to 120 characters); the Arabic name and both descriptions are optional. A page in Arabic shows the Arabic text when there is one, the English otherwise. |
| Owner | A member of the workspace. The drawer offers every member except Billing; a new project's owner is its creator unless another is chosen. |
| Due date | Optional. The overview lists open projects due within its period under Projects needing attention. |
| Status | In progress (the default), Review, Blocked or Completed. In progress, Review and Blocked count as active. |
| Progress | 0 to 100, set by hand in Project settings; setting the status to Completed sets it to 100. |
| Board | Its tasks, in four columns: Backlog, In progress, Review and Done. |
| Files | Uploads of up to 10 MB each. |
The seeded workspace, Forma Studio, has 12 projects (6 in progress, 1 in review, 1 blocked and 4 completed) with their boards, and one archived project, Pilot dashboard, so the archive has something to restore.
The projects list
/en/dashboard/projects lists the workspace's projects, seven a page, most recently updated first, for members who hold projects.read.
- Three tabs with their counts: All projects, Active and Completed.
- Filters: a search over the names and descriptions, Status, Owner (the members who own a project) and Due date (due on or before the day picked). Reset clears them. The tab, the filters and the page are kept in the address.
- Columns: Project, Status, Owner, Progress, Due date, and an actions menu with Open, Edit and Archive.
- New project opens the project drawer. Archived opens the archived projects.
Creating and editing a project
New project, on the projects list and on the overview, opens a drawer with the name and description (an English and an Arabic tab each), the owner, the due date and the status; Create project saves it and opens its page. On a project's page, Project settings opens the same drawer with Progress (%) as well. Closing the drawer with unsaved changes asks first.
- Creating, editing, archiving and restoring need
projects.write(owners, admins and members as seeded). - Once a past-due workspace's grace period (
BILLING_GRACE_DAYS, 7 days in.env.example) has run out, or once its subscription is canceled, a new project is refused with "The plan's limits are reached. Change the plan to add projects." Existing projects keep working. - Each change is written to the activity log:
project.created,project.updated(with the status it moved from and to),project.archivedandproject.restored.
The task board
A project's page (/en/dashboard/projects/all/<id>) shows its status, owner, due date and progress, then three tabs: Board, Activity and Files.
- The board has four columns, Backlog, In progress, Review and Done, each with its count. A card shows the task's title, priority, assignee and due date.
- Drag a card to another column or another place in its column. With the keyboard, press Space to pick a task up, the arrow keys to move it, Space to drop it and Escape to cancel. Each card's menu also has Edit, Move to and Archive. A move that the API refuses puts the card back where it was.
- View switches between Board and List, a table with the task, status, priority, assignee and due date.
- Filters: Search tasks, Assignee and Priority.
- New task opens the task drawer. Members without
projects.writesee the board and the tasks read only.
What a task holds
| Field | Values |
|---|---|
| Title and description, in English and Arabic | The English title is required; each title takes up to 160 characters ("Keep the title to 160 characters."), and the Arabic title and both descriptions are optional. |
| Assignee | A member of the workspace (the drawer offers every member except Billing), or Unassigned. |
| Due date | Optional. |
| Priority | High, Medium (normal) or Low. |
| Status | Backlog, In progress, Review or Done: the board's column. |
Archive on a card takes the task off the board after a confirmation; its history stays in the activity. Archived tasks have no restore screen. Every task change is an activity event (task.created, task.moved, task.updated, task.archived), and the overview's weekly chart counts them.
Project files
- The Files tab lists a project's files newest first, with who uploaded them, their size and when. Upload file takes any file type up to 10 MB (
projects.write); Download needsprojects.read. - Each upload adds to the workspace's storage, which Billing measures against the plan.
- A file is stored under a random name in the Cloudflare R2 bucket when the five
R2_*variables are set, otherwise in the API'sMEDIA_UPLOAD_DIR(the data volume with Docker), and is served from that address. Anyone holding a file's address can open it, so share links with care. - From the API's own disk, a file that is not a picture, a PDF, plain text, audio or video, such as an HTML or SVG file, is sent as a download rather than opened in the browser, so an uploaded page never runs on the API's address. A bucket serves each file with the type it was uploaded with.
Archiving and restoring
Archive on a project takes it out of the lists, the overview and search; its board, tasks and files stay as they are. Archived (/en/dashboard/projects/deleted) lists the archived projects, and Restore brings one back to the list with its tasks and files. An archived project's files can still be listed and downloaded.
The routes behind these pages
| Route | Permission |
|---|---|
GET /api/workspaces/:workspaceId/projects (status, state, search, ownerId, dueBefore, sort, order, page, limit up to 100) | projects.read |
GET .../projects/archived, GET .../projects/owners, GET .../projects/:projectId, GET .../projects/:projectId/activity | projects.read |
POST .../projects, PATCH .../projects/:projectId, DELETE .../projects/:projectId (archive), POST .../projects/:projectId/restore | projects.write |
GET .../projects/:projectId/files, GET .../files/:fileId/download | projects.read |
POST .../projects/:projectId/files (multipart, field file) | projects.write |
GET .../projects/:projectId/tasks (assigneeId, priority, search) | projects.read |
POST .../projects/:projectId/tasks, PATCH .../tasks/:taskId, POST .../tasks/:taskId/move, DELETE .../tasks/:taskId (archive) | projects.write |
.../tasks/:taskId/move takes the column as status and, to place the card, the id of the card it now sits before as beforeId. Your own systems can read, create and edit projects and add tasks with an API key on /api/v1 instead.