A board can follow a list of another task tool and keep it up to date: the first run imports every task, later runs create the new ones, update the changed ones, archive the ones the provider deleted and restore the ones that come back. ClickUp (API v2) is the first provider; the contract is ready for others.
The feature is opt-in (sync.enabled: false by default): without it there are no routes, no services, no Doctrine
mapping of the sync tables and no header change.
- What the host provides
- Configuration
- How a run works
- Field rules and conflicts
- Deletions and the mass-archive guard
- Files and images
- Running it in the background
- Console command
- UI
- People directory (since 1.25)
- Creator, assignees, watchers, checklists and comments (since 1.25)
- Statuses and sources (since 1.25)
- Tracked time (since 1.25)
- Pre-scans and re-association (since 1.25)
- People page and step (since 1.27.0)
- Everything a ClickUp task has (since 1.27.0)
- Events
- Testing with the in-memory provider
- Adding a provider
The bundle never stores a token. The host keeps the credentials and gives one for each run.
Hook (service id in sync.*) |
Required | Default |
|---|---|---|
credential_resolver: Nowo\TaskBoardBundle\Sync\Hook\ProviderCredentialResolverInterface |
yes | — (the container build fails without it) |
attachment_storage: TaskAttachmentStorageInterface |
no | files are counted as refused (storage_disabled) |
inline_image_rewriter: InlineImageRewriterInterface |
no | MapInlineImageRewriter (stored copy, else the text "[image not copied]") |
limit_checker: SyncLimitCheckerInterface |
no | no host limit |
runner: SyncRunnerInterface |
no | InlineSyncRunner (one slice per request; the progress page continues it) |
actor_resolver: SyncActorResolverInterface |
no | the user of the request, else the user who linked the board; since 1.24 a disabled user (isEnabled() false) or one actor_checker refuses is never the actor, and a named user that is refused, no longer found or fails to load is not replaced by the linker |
actor_checker: Symfony UserCheckerInterface (since 1.24) |
no | none: only isEnabled() is checked |
people.resolver: SyncPersonResolverInterface (since 1.25) |
no | DefaultSyncPersonResolver: one directory per board, the board's assignable users as candidates, 1.23 e-mail lookup |
time_entries.sink: ImportedTimeEntrySinkInterface (since 1.25) |
no | none: the time_entries phase never runs |
BOARD_ACCESS_CHECK listener for import_tasks (since 1.25) |
no | granted: who may edit the board (and, for the connection, manage it) may import |
use Nowo\TaskBoardBundle\Entity\TaskBoard;
use Nowo\TaskBoardBundle\Sync\Hook\ConnectionChoice;
use Nowo\TaskBoardBundle\Sync\Hook\ProviderCredentialResolverInterface;
use Nowo\TaskBoardBundle\Sync\Provider\ProviderCredential;
final class ProjectConnections implements ProviderCredentialResolverInterface
{
public function connectionsFor(TaskBoard $board, object $user, string $provider): array
{
// The stored connections this user may use on this board: an opaque ref, a label, the last 4 characters.
return [new ConnectionChoice('42', 'Team token', 'a1b2')];
}
public function credentialFor(TaskBoard $board, string $connectionRef): ?ProviderCredential
{
// Decrypt the token for one run; null when the connection is gone or no longer allowed for this board.
return new ProviderCredential($this->decryptedToken($connectionRef), $connectionRef);
}
public function credentialFormUrl(TaskBoard $board, string $provider): ?string
{
return '/settings/connections/new?provider=' . $provider; // where a token is pasted
}
}ProviderCredential is built for one run. It is never stored, logged or dispatched: print_r() / var_dump() show
[redacted], and serializing it throws (so it cannot travel in a Messenger message). Only provider adapters read it
(reveal()).
nowo_task_board:
sync:
enabled: true
credential_resolver: App\Tasks\ProjectConnections
attachment_storage: App\Tasks\StorageKitAttachments # optional
limit_checker: App\Tasks\PlanLimits # optional
runner: App\Tasks\MessengerSyncRunner # optionalEvery key and its default is in CONFIGURATION.md. The schema change is in UPGRADING.md.
Nowo\TaskBoardBundle\Sync\TaskBoardSyncService:
link(TaskBoard, TaskProviderInterface, ProviderCredential, RemoteContainer, object $actor, array $options)links the board to a remote list (one per board).runLinked(TaskBoard, SyncOptions)runs the linked board with the host's credential, its stored options and its cursor.run(TaskBoard, TaskProviderInterface, ProviderCredential, string $listId, SyncOptions, ?SyncCursor)is the low-level call (it links the board on first use).unlink(TaskBoard, object $actor)removes the link and its sync state; the tasks, their import links and the stored files stay.requestCancel(TaskBoard, string $runId).
A run:
- takes the board's run lock (a second run gets status
busyand writes nothing; a lock without heartbeat for 10 minutes is taken over); - reads the tasks page by page — every task on the first run (
initial) or withfull, else those updated since the last successful run minus two minutes (incremental); - writes each page in one transaction (after asking the host's
limit_checker; a refusal writes nothing of the page), then copies the files and comments of the tasks it created or changed; - links the parents and Gantt dependencies whose other task came on a later page;
- compares a complete list of the remote ids with the linked tasks (deletions, below);
- records the run (history: one row per run, kept
history_keepper board), the watermark andSYNC_FINISHED.
SyncOptions::$maxPages / $timeBudgetSeconds (and sync.max_tasks_per_run) end a slice with status paused and a
cursor; a 429 that asks to wait longer than sync.http.max_inline_wait ends it with rate_limited. The next
runLinked() resumes from the cursor under the same run id. Every run clears the entity manager after each page, so
entities loaded before the call are detached afterwards.
A run never reads more than sync.max_pages_per_run task pages (1 000 by default) over all its slices, and a slice at
most
ceil(max_tasks_per_run / 100) + 1; past either cap the run fails with response_too_large and its cursor is
cleared. A page that brings no new task ends the list with the warning paging_stopped: the run is reported as
succeeded with that warning, and the watermark is not moved, so the next run reads again from where this one started.
The list's task count is not used as a cap (audit EG-L7): ClickUp's task_count may leave out the subtasks and closed
tasks the pages hold.
Identity: a synced task carries the same task link a file import writes (import_source = clickup, external_id =
the ClickUp task id). A board that was imported from a ClickUp CSV or JSON file is adopted by its first sync without
duplicates, and a file re-import after a sync matches the same tasks. A remote id already imported into another board of
the tenant is skipped (counted, not named).
For each synced field (title, description, status/column, priority, start, due, estimate, tags, assignees, parent) the
bundle keeps the hash of the value it last wrote (task_board_sync_items.field_hashes):
| Situation | Result |
|---|---|
| No baseline yet (adoption of a file import) | the provider wins where it has a value |
| The provider did not change the field | the local value stays, edited or not |
| The provider changed it, nobody changed it here | the provider's value is written (with a history entry) |
| Both changed it to the same value | nothing to write |
| Both changed it differently | the local value stays; one conflict note (a comment by the run's user) and a sync_conflict history entry list the provider's values; the run summary lists the conflicts too |
A conflict on the same remote value is noted once. An empty remote value never clears a local one. Comments are imported
once per remote id and updated when the provider edits them, unless they were edited here (a conflict on "comment").
Custom fields are typed values since 1.27.0 (sync.custom_fields.mode); with text or both they also go to a task
document "Fields (ClickUp)" that the sync keeps up to date.
Tasks are never deleted by a sync. A linked task the provider no longer lists (deleted, archived or moved to another
list) is archived (archive_reason = remote); it is restored when it comes back. A task archived by a person
stays archived. A task deleted here is never recreated (it is counted as "skipped (deleted here)").
The guard: when a complete scan of the list returns no id at all, or would archive more than
sync.max_archive_ratio (default 0.5) of the linked tasks, nothing is archived and the run reports
mass_archive_guard. The connection page then shows a translated refusal and, to users who may manage the connection,
a Refresh and archive anyway… button behind a confirm dialog (its own CSRF token). The console has
--allow-mass-archive. A scan that fails never archives anything (deletions_skipped).
Archived tasks are hidden from the board, the list, the Gantt and the counts. The list view shows them in an "Archived
tasks" section with a Restore button (any archive reason; route task_restore).
Attachments and the images of descriptions and comments are downloaded by the bundle (RemoteFileFetcher) and handed
to the host's attachment_storage; a remote image is never hot-linked. The fetcher:
- accepts https URLs on the provider's attachment hosts only (exact or
*.suffix), without user info, port or IP literal; - refuses private, loopback, link-local and metadata addresses after DNS (
NoPrivateNetworkHttpClient; withnowo-tech/outbound-url-guard-bundleinstalled its guard also checks and pins the address); - follows at most
sync.attachments.max_redirectsredirects itself, each one checked again; - never sends a credential to a file host;
- caps the size (declared,
Content-Lengthand while streaming) atsync.attachments.max_bytesand the run atmax_bytes_per_run; - sniffs the type from the bytes: it must be in
allowed_mime_types; SVG, HTML, scripts and executables are always refused.
Stored files appear on the task as links of type attachment (excluded from the link form). A file whose remote id,
size and date did not change is reused.
InlineSyncRunner (default) runs one slice of sync.inline_slice_pages pages in the request; the progress endpoint
continues a paused run, one slice per poll. A host with workers implements SyncRunnerInterface::dispatch(SyncRequest)
(ids and flags only) and calls runLinked() in its handler:
final class MessengerSyncRunner implements SyncRunnerInterface
{
public function dispatch(SyncRequest $request): void
{
$this->bus->dispatch(new SyncBoard($request->boardId, $request->actorId, $request->full, $request->allowMassArchive));
}
public function advancesOnPoll(): bool
{
return false; // the worker runs it
}
}In the handler, resolve the actor through SyncActorResolverInterface and stop when it answers null, then run:
$actor = $this->actors->actorFor($board, $message->actorId); // SyncActorResolverInterface
if ($actor === null) {
return; // disabled, erased or refused: never run as anyone else
}
$report = $this->sync->runLinked($board, new SyncOptions(actor: $actor, trigger: SyncTrigger::Schedule, maxPages: 20));Re-dispatch with a delay while $report->status->isResumable() ($report->retryAfterSeconds after a rate limit). A
handler that loads the user itself (e.g. $em->find(User::class, $message->actorId)) bypasses the actor refusal
(disabled, erased or actor_checker-refused users) and must not be used.
php bin/console nowo:task-board:sync <boardId> [--full] [--dry-run] [--allow-mass-archive] [--time-entries] [--restart] [--format=text|json]It runs to completion. Exit codes: 0 succeeded, 1 failed, 2 invalid (board not found, not linked, no user), 3 paused or rate-limited (resumable), 4 refused by a limit, 5 busy. It never prints a token or a URL.
- Board, list and Gantt headers: Connect provider for managers; once linked, the badge "ClickUp · ", the last
sync time and, for managers, Refresh from ClickUp and Connection (block
nowo_task_board_connection, template_connection_badge.html.twig). Readers see the badge only. Since 1.25.2,sync.badge.connect_link: falsedrops the Connect provider link: an unlinked board shows nothing in the header (the connection page stays reachable atboard_connectionfor the host to link from elsewhere); a linked board is unchanged. Since 1.26.3 the badge data carries the running run (activeRunId,progressUrlfor managers,total,processed,pollInterval) andsync.badge.progress: trueshows a determinate bar driven by the progress endpoint (CONFIGURATION). - The connection page (
board_connection, templatetemplates.connection): provider, stored connection (with a link to the host's credential form), the container browser, the import options; once linked, status, progress, history, Refresh, the mass-archive confirmation and Unlink. - The container browser follows the APG disclosure pattern with a radio group (not
role="tree"): containers are buttons witharia-expanded/aria-controls, their level is fetched on first open (aria-busyand a polite live region), lists are radios. Without script the same buttons submit and the page reloads with the level open. - Progress: a
<progress>(indeterminate without a total) and a polite, atomic live region updated at most every 5 s by pollingboard_connection_progress(JSON,Cache-Control: no-store, counters only). - Every action is a POST with its own CSRF token. Users who may not manage the connection get 404 on these routes.
Who may manage: TaskBoardResourceAccessChecker::canManageBoardConnection() — canEditBoard() and the
BOARD_ACCESS_CHECK event dispatched with BoardAccessCheckEvent::ACTION_MANAGE_CONNECTION (default: the board's
creator or a security.manage_roles holder). A listener that grants every action without looking at
getAction() widens it to everyone who can edit the board.
public function onBoardAccess(BoardAccessCheckEvent $event): void
{
if ($event->getAction() === BoardAccessCheckEvent::ACTION_MANAGE_CONNECTION) {
$this->canManageTasks($event->getSubject(), $event->getBoard()) ? $event->grant() : $event->deny();
return;
}
// … the view decision
}Every remote person (ClickUp user) is one row of a directory per (host scope, provider, workspace): every board and
connection of that scope shares it, so a remote identity maps to at most one local user per scope (several remote
identities may map to the same user: old and new e-mails). The scope comes from
SyncPersonResolverInterface::directoryScope() ([a-z0-9:_-]{1,64}, e.g. org:<uuid>; the default resolver uses
board:<id>, no sharing). The directory is attached on the first run of a connection (the workspace is looked up once).
| State | Meaning | Projected |
|---|---|---|
unmatched |
No user; content stays on the run's actor, with the person reference | no |
suggested |
One candidate matched by e-mail, account not verified; needs a confirmation | no |
auto |
One verified candidate matched by e-mail | yes |
manual |
A human chose the user (applyMapping(), kind manual or confirm) |
yes |
external |
A human chose Keep as external person (or detachUser()) |
no |
Automatic matching runs when people are seen (the workspace members at the start of a run, refs in tasks,
comments, checklists and time, and a persisting pre-scan) for persons no human decided. The bundle normalises the
e-mail (trim, NFC when ext-intl is loaded, lower case) and asks autoMatch() for exactly one candidate: verified
→ auto, unverified → suggested, none → unmatched. A person without e-mail is never matched. The bundle passes the
normalised e-mail as the optional third argument $normalizedEmail; a host resolver called with two arguments (the
contract's signature) derives it with SyncUser::normalizeEmail($person->email). Name and e-mail are
refreshed on every run; a changed e-mail sets email_changed_at. manual and external are never overridden; an
auto person whose e-mail changed (or whose user is gone) becomes unmatched with the warning
person_auto_unmatched, and nothing already imported moves. An anonymised person is never refreshed or matched again.
Every mapping change, automatic ones included, dispatches SYNC_PERSON_MAPPED.
Projection rule — a mapping never grants access. Before writing a mapped user as creator, member or comment author,
the writer checks canViewBoard($user, $board). A user who cannot view the board is not written: the actor (creator,
comment author) plus the person reference is, and the person is listed in the item's unmatched_people. The bundle's
default access checker grants a task to its creator and members, so projecting would grant access. The People step can
still map such a person (warning ScannedPerson::$boardAccess = false); the templates show a no access to this board
badge, and the host still receives their time through the sink.
Losing access deletes nothing. Projected rows stay when a user loses board access; access to imported tasks follows
board access only if the host's access checker denies non-members. A host whose checker does not should call
reassign($person, null) to detach the content. When a user gains access, the host calls
TaskSyncPeopleProjector::reprojectForUser($user, ?$board, $batchSize, $cursor, $trigger) from its membership events:
references become rows where the user can view the board now (access and candidacy re-checked inside each board's lock);
idempotent; SYNC_PEOPLE_REPROJECTED once per finished call.
Who may manage the people (applyMapping(), markReviewed(), anonymise(), reassign(), the scans):
canManageBoardConnection() on every board of the directory, else PeopleMappingDeniedException (routes: 404).
Target users must be candidates of every board (isCandidate(), candidateById() is the only id lookup).
SyncOptions::$requirePeopleMapping refuses a first import (people_mapping_required) while someone is undecided and
the People step was not saved (markReviewed()).
Privacy: anonymise() turns the name into "Former user #n" (stored as the token former:<n>, translated at
display) and clears the e-mail; references stay. pruneDirectory() (run on the last unlink) deletes unreferenced
people and anonymises the rest. Export: TaskSyncPersonRepository::exportFor($user) / exportDirectory($directory).
People page queries: TaskSyncPersonRepository::forDirectory($directory, PersonFilter $filter, $limit, $offset)
with new PersonFilter(mappings: [...], q: 'text', changed: true, changedSince: $date): mapping states (empty =
all), q matches part of the name or the e-mail (case-insensitive, at most 120 characters, LIKE wildcards literal),
changed keeps people whose e-mail changed in the provider, changedSince those whose e-mail changed at or after the
date. PersonFilter::mappings(TaskSyncPersonMapping::Unmatched, ...) is the shortcut for states only.
No avatar URL is stored.
- Creator and date. A new task's creator is the projected user of the remote creator, else the actor;
task_board_sync_items.creator_person_idkeeps the person either way.Task::createdAtis the provider's creation date (2000-01-01 … now + 5 min). Updates never move either, except the one-off back-fill of tasks written before 1.25 (backfill_level0 → 1 on their next fetch). - Assignees and watchers. Refs go through the directory; projected users become
TaskMembers and every member the sync adds gets atask_board_sync_membersrow. Only those members are removed when the person leaves the remote set; members added by hand stay. Unprojected people show as Also assigned in ClickUp / Also watching in ClickUp. NoTaskMemberAddedEventis dispatched (no notification during a sync). When a list row has nowatchers/checklistskey,GET task/{id}(E5) completes it for tasks created or changed in the run, at mostsync.watchers.max_detail_calls_per_runper run. - Per run:
SyncOptions::$watchers/$checklists(defaulttrue) leave watchers or checklists out of one run; both also need theirsync.*.enabledoption. A run without either asks no task detail (E5) for it. - Checklists (
sync.checklists.enabled). Each item is a subtask of its task (external id<task>#<item>, tagchecklist:<name>, checklist order then item order, nested items flattened in tree order). Resolved items are done: they go to the column the status map gives the firstclosed(elsedone) status, else the last column. The item assignee goes through the directory. The deletions scan never archives checklist items; an item is archived when its task was fetched with its checklists and the item is gone. An item deleted here is never recreated. - Comments. The author is the projected user, else the actor, with
task_board_sync_comments.author_person_id; no prefix line (the comment template renders name (ClickUp)), and the comment keeps its ClickUp date.TaskSyncCommentLegacyAuthorMigrator::migrate($connection, $batchSize, $afterId)returns aMigrateReport(connectionId,directoryId,migrated,skipped,lastId,done) and removes the 1.23 prefix line once where the name matches exactly one person (see UPGRADING). - Twig:
task_board_sync_creator(task),task_board_sync_comment_author(comment),task_board_sync_unmatched(task, 'assignee'|'watcher')returnSyncPersonView(name,provider,external,anonymised,boardAccess);task_board_sync_token()renders theperson:/user:tokens of thesync_person_reassociatedhistory entries.
Done comes from the status type. A task whose ClickUp status type is closed or done is completed; one that
goes back to an open type is reopened (under the per-field rule of column). The 1.23 rule (completed in the last
column) applies only when the provider gives no status type.
Status → column map. link(..., $statusColumnMap) and updateStatusColumnMap($board, $map) take
list<{status, column, type?}>: column is a column id of the board, __create (a column named like the status,
created when the link is confirmed, in the statuses' order) or __skip (tasks in that status are not imported;
counted skipStatus). Statuses match ignoring case, accents and spaces. A status missing from the map follows the 1.23
rules (same-named column, create missing columns, fallback column) with the warning unmapped_status. type (from the
pre-scan) tells which column receives done checklist items.
Sources. A connection follows a list (1.23), a folder (f:<id>) or a space (s:<id>) through
SourceProviderInterface: findSource(), fetchSourceTasks() (ClickUp GET team/{id}/task with
project_ids[] for a folder or space_ids[]; a list keeps the 1.23 calls), existingSourceTaskIds(), listStatuses() (list or space statuses; for a folder its
own, else the union of its lists'), resolveListFromUrl() (only https://app.clickup.com/… list links; no network
call) and searchLists() (at most 40 calls; cached 300 s in sync.lookup.cache_pool, keyed by a hash of the connection
reference, never the token). With sync.list_as_tag tasks of a multi-list source get the tag list:<name>.
With unmatchedColumns: delete, at the end of the first import, each board column that no provider status maps to is deleted if it is
empty. A status maps through the dialog's map (__skip maps to nothing), else by the same name; the fallback column counts as mapped.
Whatever cannot be decided keeps the column and says so in the run report: a source not read to the end, edit permission lost during
the run, statuses the provider did not give, a database refusal. The decision is marked on the connection before anything is deleted, so
a failure is never retried by a later sync. A run that fails is not the end of the first import: the retry still decides.
The bundle never writes TimeTrack data. With sync.time_entries.sink set and SyncOptions::$timeEntries, a
time_entries phase runs after the deletions:
- Admin token (workspace owner or admin): every directory person's entries, in
assigneechunks ofmax_assignees_per_call(provider ids from the directory only). ClickUp returns other people's time only to workspace owners and admins. - Member token: only the token user's own entries, with the warning
time_member_mode. WithSyncOptions::$timeFallbackPerTask(explicit, never automatic) the legacy per-task intervals (E8) are read for up tofallback_max_tasks_per_runlinked tasks; when the provider no longer serves them,time_fallback_unavailable. - Windows of
window_days(≤ 30) fromSyncOptions::$timeFrom(default: the board's oldest task, else 30 days back), at mostmax_windows_per_runper run; a window withmax_entries_per_windowrows or more is halved and read again, down to one hour (thenresponse_too_large). The phase resumes per window and chunk. - The sink gets
accept($board, $directory, $window, $access, $entries, $windowComplete)once per window and chunk:ImportedTimeEntryCandidate {entry, person, ?task}(tasknull when the remote task is not linked on this board). Running timers and entries without a task are counted ($report->time->skippedRunning,skippedTaskless), never delivered.$windowCompleteis true on the window's last chunk: the host may tombstone what it had for that window. Beacon stages the entries and writes them with TimeTrack'sImportedTimeEntryWriterunderexternalSource = clickup:<directory id>. - Report:
SyncReport::$time(TimeCounts:modeadmin / member / fallback or null,windows,windowsSplit,entries,skippedRunning,skippedTaskless,fallbackTasks) andSyncReport::$people(PeopleCounts:seen,created,autoMatched,suggested,unmatchedNew,changedEmail,autoUnmatched). Other counters (checklist.*,detail.calls,skipStatus) stay inSyncReport::$stats/stat(); the typed ones are not repeated there.
TO CONFIRM against a real workspace (handled defensively): the row cap per answer, the assignee list length,
whether guests can track time, and what a member token gets when assignee lists others (the adapter sends none).
A plain sink gets people mapped to a user, and the rest is counted (time.skippedUnmapped, shown with its hours in the
completeness report). A sink that implements OwnerlessTimeEntrySinkInterface also gets those entries, with user() null and the
person on the candidate; the bundle stores no time and the hours stay at the provider either way. ownerless.entries counts them.
TaskSyncSourceScanner::scan($board, $provider, $credential, RemoteLocation $source, $actor, $persistPeople = true)(the connection dialog, beforelink()): the source, its workspace, its statuses with types, the people scan and the time mode. Read-only on the provider; with$persistPeoplethe draft directory is filled.TaskSyncPeopleScanner::scan($board, $provider, $credential, $workspaceId, $location, $actor, $persist): members, the first task page(s) (sync.people.scan.max_task_pages), the comments of the first tasks (max_comment_tasks) and, with an admin token, one 30-day time window (time_window); at most 15 calls. EachScannedPersonhas the counts per kind, the mapping, the match (auto/suggested/none), the matched user id andboardAccess.TaskSyncPeopleReassigner::reassign($person, ?$newUser, $actor, $batchSize, $cursor)maps the person to a candidate (or external) and moves creator, comment authors and sync members (checklist subtasks included) on every board of the directory, under each board's lock (busyBoardswhen held). Call again with the returned cursor until it is null. The pending target is stored on the person: a restart resumes, another target is refused (ReassignInProgressException) until it finishes orcancelReassign(). Onesync_person_reassociatedhistory entry per task;SYNC_PERSON_REASSIGNEDwhen done (the host moves its own data there, e.g. TimeTrack copies).detachUser($user, $actor, $anonymise, …)is the account-erasure helper: every person mapped or suggested to the user becomes external (optionally anonymised) and their content goes back to the actor plus the reference. Run it before deleting the user (erasure order).
TB-SYNC-2: a UI on top of the people directory, so a manager decides who each remote person is.
- People page (
board_connection_people, templatetemplates.connection_people; linked from the connection page bytemplates.connection_people_summary: "n of m people are mapped. k not mapped yet." and Map people). One row per remote person of the connection's directory (workspace members and every creator, assignee, watcher, commenter, checklist and time-entry user a run or scan saw), by name,page_sizeper page, filter All / Not mapped yet. Each row has a host-user select: Not mapped, the board's candidates (SyncPersonResolverInterface::candidates(), at mostcandidate_limit) and, withsync.people.inviterand a remote e-mail, Invite by e-mail. No remote avatar is shown (none is stored): an initial instead. - Pre-fill, deny by default. The select starts on the current mapping; else the host's suggestion (unverified
e-mail match); else the only candidate with the same normalised e-mail. The only candidate whose label (
UserLabel) has the same normalised name (case, accents, spaces,.,_,-ignored) is suggested beside a select left on Not mapped, because a remote person chooses their own name. A pre-fill is only a starting value: nobody is mapped until a manager saves, and only to a candidate of every board of the directory. A sync still maps automatically only the 1.25 verified e-mail matches. - Stale pages: a row absent from the POST stays as it is.
- Save (
board_connection_people_save, CSRF token idtask_board_connection_people, formConnectionPeopleFormType, fieldsp_<person id>; any other value is a form error): rows whose value changed go throughTaskSyncPeopleReassigner::reassign(), so the tasks already imported follow — creator, assignees and watchers the sync added, comment authors (the comment keeps the remote name as its snapshot), checklist items — on every board of the directory; the host moves its tracked time onSYNC_PERSON_REASSIGNED, and the time phase sends mapped people's entries from then on. Not mapped on a mapped person keeps them as an external person (their sync rows go back to references). A save spends at mostreapply_seconds; what is left is pending (the page says so) and continues on the next save and at the end of every sync of a board of the directory (PeopleMappingService::resume()). The save marks the directory reviewed (SYNC_PEOPLE_REVIEWED) and dispatchesSYNC_PEOPLE_MAPPING_CHANGED(PeopleMappingChangedEvent: board id, directory id, actor id, the changes as ids and mapping states, invitations, pending) once, besides the per-personSYNC_PERSON_MAPPED/SYNC_PERSON_REASSIGNED. - Invite by e-mail (
Sync\Hook\PeopleInviterInterface:canInvite($board, $actor),invite($board, $email, $name, $actor): ?object): a returned user is mapped right away (still checked as a candidate); null = pending invitation, the person stays unmapped until a later sync matches the verified account. - Step (
sync.people.step: true): linking a board attaches the directory and runs the people pre-scan (TaskSyncPeopleScanner, ≤ 15 calls) instead of starting the import, and redirects to the People page, whose buttons are Save and start the import and Start the import without mapping. Without a people capability (no workspace), or when the scan fails (flash with the provider error), the import starts at once as before. - Run summary. The connection page shows the people line; the progress JSON gains
unmappedPeople(people nobody decided: unmatched or suggested). - Access. Every People route needs
canManageBoardConnection()(ACTION_MANAGE_CONNECTION, deny by default) on the board and on every board sharing the directory, else 404: remote e-mails are only shown to those managers. - Scope. The mapping is stored per directory: per connection by default (
board:<id>), or per provider workspace and host tenant when the host'sdirectoryScope()returns a shared scope.
sync.people_bulk_former adds a button marking everyone undecided (unmatched or suggested, not anonymised, across all pages) as a
former person: mapping external. Their name stays on tasks, comments and history; they cannot be assigned, mentioned or notified,
and nothing moves. A person remains changeable, and anonymising stays available.
AttributionOnlyResolverInterface lets a host offer a user for attribution only. The option says so in the select. Such a mapping
writes no membership and does not set the task's creator or a comment's author, because a task's creator gets access through
isTaskParticipant. The panel shows the user's label from the view model, and the sink receives the user for tracked time.
TB-SYNC-3. Remote data is untrusted everywhere: values are type-checked, text is sanitised and cut, links must be
http(s), files go through RemoteFileFetcher (provider attachment hosts only, no private addresses, size caps, type
sniffing), and nothing remote is rendered unescaped.
sync.custom_fields.mode: typed (default), text (the 1.23 Markdown document only) or both.
- Definitions per board (
task_board_sync_fields: provider field id, name, type, remote type, choices, config, position), refreshed when the provider renames or retypes a field. Values per task (task_board_sync_field_values: the typed value as JSON and a one-line text). The provider is their source: a value it drops is removed; there is no local editing. A re-sync writes nothing when nothing changed. - Types (
Sync\Field\SyncFieldType): text (ClickUptext,short_text), number, money (currency, ISO code), date (date, with time when the field says so; UTC), dropdown (drop_down), labels, checkbox, url, email, phone, rating (emoji, 1–10 stars), progress (automatic_progress/manual_progress, 0–100), people (users, stored as references to the directory) and relationship (tasks,list_relationship). Any other type, and any value that does not fit its type, is kept as text (e.g. ajavascript:URL shows as text, never as a link); the field keeps its type and the view re-checks a value before drawing a link. The one exception is a malformed people value, which is left out: a name goes only through the directory. - Leaving types out:
sync.custom_fields.exclude_types(default none). Excluded types are not read into the typed values or the "Fields" document; what is stored of them goes when the task is next written. - Erasure and access: see SECURITY. In
textorbothmode the "Fields" document holds the values as plain text (ausersvalue as names), which neitheranonymise()nor the eraser reaches; prefertyped. - Task panel: a Fields section (
_task_sync_fields.html.twig, Twigtask_board_sync_fields(task)): choices as badges (data-color), checkbox Yes/No, url as an external link (rel="noopener noreferrer nofollow"), emailmailto:, rating as stars with an accessible label, progress as<progress>. - List view: each row carries
data-search-extra(Twigtask_board_sync_search_texts(tasks), only the rows drawn, once per group and request): the list search finds tasks by their field values. - Report counters (
SyncReport::stat()):fields.defined,fields.values,fields.cleared.
- Threads: replies (
GET comment/{id}/reply, read for comments withreply_count > 0; the replies count againstsync.max_comments_per_task) follow their comment, oldest first.task_board_sync_comments.parent_remote_id; the comment shows Reply to . - Files: the attachment segments of a comment are copied like task attachments (same checks and budgets) and listed under the comment body (Attachments: with links to the host's stored copies; a refused file is named without a link). The comment is rewritten when its text or its files change.
- Assigned comments (action items): the assignee (through the people directory) and the resolved state
(
assignee_person_id,resolved), shown as Assigned to and Resolved / Open badges; they are refreshed on every fetch without rewriting the comment. - Edit date:
remote_updated_at(edited in the provider on …). - Twig
task_board_sync_comment_meta(comment):reply,replyTo,resolved,assignee,remoteEditedAt. - Not imported: reactions (optional in the request).
- TO CONFIRM against a real workspace: the reply endpoint and the field names
assignee,resolved,date_updatedand theattachmentsegment shape.
Style (since 1.28.0). A comment's segments become GitHub-flavoured Markdown. Block attributes (list, indent,
code-block, and Quill's blockquote and header) count on the line feed that ends a line, which is what ClickUp
documents, and on the line's text, in the nested ({"list": {"list": "bullet"}}) and the flat form. A task mention links
to https://app.clickup.com/t/<id> when the segment has no address of its own; it does not point at the imported task
here. underline, color and background-color have no Markdown form: the text stays and the style does not.
Descriptions come from markdown_description through RemoteContentSanitizer: a GFM table stays a table, and anything
that looks like an HTML tag stays visible as text (\<u>, rendered <u>), in a table cell too. The sanitizer also
escapes < inside inline code spans, so a span shows its backslash there: block code keeps its text exactly.
Kept read-only on the synced task (task_board_sync_items.remote_meta) and shown in the task panel's From
ClickUp section (_task_sync_details.html.twig, Twig task_board_sync_details(task)):
- Custom task id (
custom_id, e.g.DEV-123, columntask_board_sync_items.custom_id), also found by the list search. - Points (
points). - Done / closed dates (
date_done,date_closed, 2000-2100 only). The done (else closed) date becomes the task's completion date when the sync completed the task or the date has not changed here since the last sync; a date set here is kept (details.completionKept). - Dates with time:
start_date_time/due_date_timesay whether start and due carry a time of day (the dates themselves are the task's start and due, as before; ClickUp dates are UTC instants). - Location: the folder (unless hidden) and list names.
- Estimate per assignee (
time_estimates_by_user, TO CONFIRM against a live workspace). Stored as a reference to the person (Sync\People\PersonToken), not a name:anonymise()covers it; without a directory it shows#<id>. - Recurrence: a read-only text when the answer has one (
recurrence; the v2 task answer usually has none, see the completeness report). - Time in status (
GET task/{id}/time_in_status,Sync\Provider\StatusHistoryProviderInterface): for the tasks a run creates or changes, at mostsync.status_history.max_calls_per_runper run; a table of status, since and minutes. When ClickUp does not serve it (404 / 410, or another lasting error such as the 400 of a disabled ClickApp, counted asstatusHistory.failed) the last one stays and the run goes on. A 403 stops the requests for the rest of the run (statusHistory.forbidden,statusHistory.skipped), and the report showstime_in_statusas Unavailable. A passing error (rate limit, timeout, 5xx, refused token) stops the run as usual and the task is read again by the next one. A task past the budget gets its history when it next changes, or on a full sync. - Linked tasks (
linked_tasks, non-blocking) becomerelatedrelations to the other task (in the Gantt), like dependencies; the file import maps them the same way. - Archived tasks (
sync.import_archived, defaulttrue): after the active pages, the archived ones are read (ClickUparchived=true, cursora<n>, at least one more request per run) and imported archived (reasonremote). They do not count against the host's limit of new tasks (SyncLimitCheckerInterface), which is about active tasks; every restore, by a sync or by hand, asks it. The id scan of deletions still reads active tasks only. - Watchers are mapped to host users through the People mapping (since 1.25); description images are stored and rewritten (since 1.23); attachments keep the provider's order.
- Task files: ClickUp list rows have no
attachments, so the task's detail (GET task/{id}) is read withinsync.watchers.max_detail_calls_per_run. A task past the budget is counted asattachments.unreadand shown as Not read. A version already read spends no request, whatever else the row lacks, so repeated full syncs get through a large board. A lasting error on the detail (403, too large) leaves that task as it is, the run goes on, and it is listed astask_detail, Unavailable; a passing one stops the run as usual.
Since 1.28.0: the task type (custom_item_id, whose 0 is ClickUp's own Task, with the workspace's name for the rest; #<id> if the names cannot
be read), all the task's lists, and tag colours (plain hex only) are in the panel. Subtasks at any depth arrive flat with their parent, closed ones
included (subtasks=true, include_closed=true). sync.include_multi_list_tasks sends include_timl on list sources; ClickUp documents it only on
that endpoint, so a folder or space source does not send it. Columns the connection created take their status's colour and the provider's order among
themselves at the end of the first import; every other column stays where it is. A later run orders and colours only the columns it creates itself.
After each run the connection page lists, per key of the provider's task answers that carried a value, on how many
tasks and whether it is imported, skipped (with the provider's reason: not supported, not needed, internal) or Not
imported yet (a key the provider does not declare; listed in the summary line). Every task the run read counts,
written or not; an incremental run reads the tasks changed since the last one, so a full sync gives the whole picture.
What is still unread is listed above the rest, from what each task keeps (pending_reads), so a later run does not hide
it: attachments, comment_replies and task_detail as Not read (request budget; a full sync reaches the next tasks),
task_detail as Unavailable (a lasting error). time_in_status is Unavailable when the provider refused the token in
the latest run.
The provider declares its keys with Sync\Provider\FieldCoverageProviderInterface::fieldCoverage(); the counts are the
run's keys.<key> stats (RemoteTask::$presentKeys, keys validated as [a-z0-9_]{1,40}, at most 200 keys per run:
completeness.keys). Only keys and counts are stored, never values.
After upgrading, run one full sync per linked board so that existing tasks get all of this (UPGRADING).
What the API does not give (since 1.28.0). Sync\Provider\ProviderApiGapsInterface::apiGaps() adds rows on every report, whatever the answers held. For
ClickUp, from its published reference as read on 2026-11-06: reminders, sprints, goal_links, folder_description, space_description are not exposed. No
reference page documents them on a task, a folder or a space. comment_assigned_by and comment_reactions are exposed and not kept. task_types is Unavailable when the names
were refused, and time_in_status stays Unavailable across runs until a later run reads it.
Already since 1.25 (see Tracked time): each entry (user through the People mapping, start,
end, duration, description, billable, tags) reaches the host's sync.time_entries.sink one by one as an
ImportedTimeEntryCandidate; since 1.27.0 ImportedTimeEntryCandidate::user() gives the mapped host user. The bundle
never deletes tracked time: not on a re-sync, not when a task, a board or a user is deleted. Hosts that must never delete
imported time ignore $windowComplete (it only says a window was read in full).
| Constant | Event | Payload |
|---|---|---|
SYNC_STARTED |
SyncStartedEvent |
board, run id, provider, mode, trigger, actor, dry run |
SYNC_PAGE_DONE |
SyncPageDoneEvent |
board, the report so far |
SYNC_FINISHED |
SyncFinishedEvent |
board, SyncReport (succeeded, paused, rate-limited, refused, cancelled) |
SYNC_FAILED |
SyncFailedEvent |
board, SyncError, the report |
TASK_REMOTE_ARCHIVED / TASK_REMOTE_RESTORED |
TaskRemoteArchivedEvent / TaskRemoteRestoredEvent |
task, provider, external id, run id |
BOARD_CONNECTION_LINKED / BOARD_CONNECTION_UNLINKED |
BoardConnectionEvent |
board, provider, list, connection ref, actor |
SYNC_PERSON_MAPPED (1.25) |
SyncPersonMappedEvent |
directory id, person id, previous / new mapping and user id, actor id (null for automatic), reason (auto, suggested, manual, external, confirm, auto_unmatched, erased) |
SYNC_PERSON_REASSIGNED (1.25) |
SyncPersonReassignedEvent |
directory id, person id, previous / new user id, actor id, reassign id, ReassignReport |
SYNC_PERSON_ANONYMISED (1.25) |
SyncPersonAnonymisedEvent |
directory id, person id, actor id |
SYNC_PEOPLE_REVIEWED (1.25) |
SyncPeopleReviewedEvent |
directory id, actor id, counts per state |
SYNC_PEOPLE_REPROJECTED (1.25) |
SyncPeopleReprojectedEvent |
user id, board ids, ReassignReport, trigger |
SYNC_PEOPLE_MAPPING_CHANGED (1.27.0) |
PeopleMappingChangedEvent |
board id, directory id, actor id, changes (person id, previous / new mapping and user id), invited, pending |
No event carries a credential, an e-mail or a person name (people events carry ids; listeners must not log the person entities). Like file imports, a sync does not dispatch per-task TASK_CREATED / TASK_UPDATED.
Nowo\TaskBoardBundle\Sync\Testing\InMemoryTaskProvider is a scriptable provider (containers, tasks, comments, injected
failures) that never opens a connection. Register it under the id of the provider it replaces, e.g. in when@test:
when@test:
nowo_task_board:
sync:
providers: { clickup: { enabled: false } }
services:
app.fake_clickup:
class: Nowo\TaskBoardBundle\Sync\Testing\InMemoryTaskProvider
arguments: { $providerId: clickup, $acceptedSecret: pk_test_token }
tags: [nowo_task_board.task_provider]The demo uses it (demo/symfony8/src/Sync/DemoTaskProviderFactory.php) and its Playwright suite runs the whole flow
with axe (make -C demo/symfony8 test-e2e).
Implement Nowo\TaskBoardBundle\Sync\Provider\TaskProviderInterface (autoconfigured with the tag
nowo_task_board.task_provider): listContainers(), findContainer(), fetchTasks() (pages, updatedSince),
fetchComments(), existingTaskIds() (must throw rather than return a partial list), capabilities() (including the
attachment hosts) and importScope(). Use ProviderHttpClient for the API calls (fixed base URI, no redirects, rate
limits, caps) and RemoteContentSanitizer for the text, and never put the credential in an exception.