Skip to content

Workflow tasks and to-dos

Workflow tasks are the platform's to-do items: things a person needs to do, optionally tied to a record (a deal, document, contact, or company). They show up on a central task list and, most visibly, in the related tasks panel that appears on deals, documents, contacts, and events.

This is separate from the task scheduler, which runs background jobs. Both happen to use the same underlying table, but the platform keeps them apart: workflow to-dos are the user-owned tasks; the scheduler's are system-owned and never surface in the task UI.

What a task has

  • Name and description, an optional due date, and a related record (type + ID) so it can be shown against that record.
  • Actors — the contacts the task is assigned to (one or more). Assignment is to people, not roles; there are no watchers and no priority levels.
  • Completion mode — manual (someone marks it done) or event (it auto-completes when a business event fires; see below).
  • Reminders — dated reminders that email chosen recipients.

Statuses and the pool/claim model

A task's status runs pending → started → finished, or cancelled.

How a task gets completed depends on its assignment:

  • Single actor — the assignee completes it.
  • Any-of-pool — several actors are assigned; any one can complete it, and completing it dismisses the others.
  • Claim pool — actors must claim the task first (first claim wins), then the claimer completes it.

Event-driven auto-completion

A task set to event completion carries a trigger event and a related record. When that event fires on that record, the task auto-completes. Wired events:

  • Document approved → completes tasks watching that document for document.approve.
  • Document rejected → document.reject.
  • Invoice paid → invoice.paid — registered but currently never fires (nothing announces the invoice-paid event yet).

Auto-completion matches on trigger event + related type + related ID + open status, and completes exactly like a manual completion.

The panel embedded on records (deals, documents, contacts, events) lists that record's tasks, with an open-only toggle and a shortcut to create a new task pre-linked to the record. This is the most common way people encounter tasks.

Reminders and notifications

The only outbound messaging is reminder emails: a task's reminders email their named recipients on the reminder date (batched per person), driven by a scheduled dispatcher. Notably, assigning or completing a task does not notify anyone in-app — assignees aren't automatically told they've been assigned, and creators aren't told when their task is done.

Who can do what

Task actions require a logged-in user; access is site-scoped (you only see your site's tasks). Beyond that:

  • Claim/complete on pooled tasks is restricted to the task's actors.
  • On non-pooled tasks, any authenticated user of the same site can complete, cancel, or comment — there is no check that they're the assignee or creator.

Why does a task change unexpectedly

  • A task completed itself — it was an event task and its trigger fired (e.g. its document was approved).
  • A pooled task vanished from your list — someone else claimed or completed it, dismissing the other actors.
  • You didn't get told about an assignment — there are no assignment notifications; only dated reminders email people.

What workflow tasks are not

  • Not the task scheduler — that runs background jobs (system-owned tasks in the same table).
  • Not support tickets — those are the separate YouTrack-backed tracker.
  • Not notifications — the in-app notification system is separate.