Comments and mentions
Route: /org/tasks?id=<task-id> → Comments tab
1. What a task comment is
A rich-text message on a task, optionally carrying attachments and @mentions. A mention is not decoration: it adds that person to the notification list for the comment.
| Comment | Activity log | |
|---|---|---|
| Written by | A person | The system |
| Editable | No | No |
| Attachments | Yes | No |
| Mentions | Yes | No |
| Sends notifications | Yes | No |
2. How a comment spreads
Comments are the widest-reaching notification a task produces: they go to the whole thread, not just the assignee.
3. Commenting — step by step
Step 1 · Read the thread
Each comment shows the author's avatar (or their initials), name, a MMM d, h:mm a timestamp, the
body, and any attachments as links.
Step 2 · Write
The editor is a full rich-text toolbar:
| Group | Controls |
|---|---|
| Text | Bold · Italic · Underline · Strikethrough |
| Blocks | Heading 1 · Heading 2 · Quote · Code |
| Lists | Bullet · Numbered · Checklist |
| Insert | Link · Table |
| Colour | Text colour · Highlight |
| History | Undo · Redo |
Links autolink as you type and open in a new tab.
Step 3 · Mention someone
Type @ and a suggestion list appears; keep typing to narrow it. Choosing a name inserts a
mention chip.
The assignee, creator and everyone who has commented get notified anyway. A person outside that set
gets nothing unless you @ them.
Step 4 · Attach
Attachments upload as you add them, and can be removed before posting.
If the document category for task attachments has not been set up, the upload fails with
Task Attachment category not configured. That is an administrator task, not something the
commenter can fix.
Step 5 · Post
Post Comment saves it. Comments cannot be edited or deleted afterwards from this panel.
4. Field reference
How a mention is stored
Each mention is written into the comment's HTML as a span carrying a single attribute:
<span class="oo-mention" data-mention-id="<uuid>">@Name</span>
The backend finds recipients by scanning for data-mention-id — the visible name is irrelevant to
routing.
Only a mention chip chosen from the suggestion list carries the id. Text that merely looks like a mention is just text, and it is a silent failure — the comment posts, the person is not told.
If someone did not get notified, check that the mention renders as a chip.
Who receives a comment notification
| Recipient | Included |
|---|---|
| The task's assignee | ✅ |
| The task's creator | ✅ |
| Everyone who commented before | ✅ |
Everyone @mentioned | ✅ |
| The author | ❌ always excluded |
Recipients are deduplicated, so being both assignee and mentioned produces one notification.
What the notification says
| Channel | Content |
|---|---|
| Bell | New comment from <author> — the task, then an excerpt with the HTML stripped |
The TASK_COMMENTED template |
Both are best-effort. Comments created by background processes — the Jira sync worker, for example — send nothing at all, because those processes run without the notification services attached.
5. The admin contract
| Prerequisite | Without it |
|---|---|
| A task attachment document category | Attachments fail to upload |
The TASK_COMMENTED email template | Bell alerts still fire; email does not |
| Users with project access | They do not appear in the @ suggestion list |
6. Downstream
| Effect | Where |
|---|---|
| Bell alert | The notification bell, linking to the task |
| Via the communication templates | |
| Thread membership | Commenting once means you are notified about every later comment |
There is no unsubscribe. One comment on a busy task means every subsequent comment, status change, priority change and due-date change on it reaches you.
7. Don't confuse this with…
| Thing | Where | Why it is different |
|---|---|---|
| Comments (this page) | The Comments tab | Human discussion, notified |
| Activity Log | Activity | System-recorded changes, never notified |
| Description | The Details tab | The same editor, but one shared body rather than a thread |
| Add Comment from a card | Kanban / List | The same modal, opened without the panel |
| Ticket comments | Orbit Resolve | A separate system, with public and internal replies |
8. Troubleshooting
| Symptom | Cause |
|---|---|
| A mentioned person got nothing | The mention was typed as plain text, not chosen from the list |
| Nobody was notified | The comment was created by a background process |
Task Attachment category not configured | The document category has not been set up |
| Cannot edit a comment | Comments are immutable here |
| Too many notifications | You commented once and joined the thread |
| The author got no notification | Correct — actors are always excluded |
Related
- Activity history — the system's record
- Task detail