Server and account setup
A ClickUp Workspace owner/admin creates an OAuth app and registers the exact callback /cloudwork/callback (public HTTPS in deployment). The account authorises relevant Workspaces; select one for each connection. Current OAuth tokens do not expire and do not have a documented refresh flow; reconnect after revocation.
Configure ClickUp:ClientId, ClickUp:ClientSecret, ClickUp:RedirectUri in the server secret store/environment (for example ClickUp__ClientSecret). Do not commit secrets. All three providers use /cloudwork/callback, with distinct app registrations and secure provider-bound state. Required permissions: No granular OAuth scope parameter is documented; the user authorises Workspaces. CYJ only performs reads..
Connect and select work
An administrator opens Settings → Integration connections, adds a ClickUp connection, gives it a meaningful name, and opens Configuration. Connect with the provider, approve access, choose the granted tenant/workspace, discover resources, tick participating resources, enable, save and Test. Reconnection must use the original tenant/workspace; create another connection to use a different one. Multiple connections to the same provider are supported.
Open User mappings, discover users and explicitly map them to existing active team members. Name/email suggestions require review. Discovery does not create staff or user accounts. Add work from Projects using the chosen connection, search titles, then review effort and scheduled people before saving. Child work is offered as a stage suggestion only where supported.
What is imported
Selected Lists discovered through Workspace → Spaces → Folders/Lists, including folderless Lists; title, plain description, all assignees, custom status, due date, time estimate and time tracked, URL and child suggestions. Only home-List tasks participate; tasks present only through additional List membership are excluded. No inferred remaining effort or write-back.
Source dates, assignments and estimates remain source information. They do not overwrite local people, effort, constraints, dependencies, deadlines or scheduling on refresh. Refresh is on demand; no background polling or webhook subscription is installed. Disabled/disconnected connections retain local work, mappings and historical Activity. Disconnection removes protected credentials and requires confirmation.
Troubleshooting
Check resource membership and app permissions if access is refused. Reconnect after revoked/expired authentication. Wait for provider rate limits to reset after a 429; no automatic write is retried. Deleted, archived or inaccessible source work retains its cached reference and local planning. Discovery is bounded (5,000 work records, 100 pages per resource; ClickUp hierarchy 200 requests). Incomplete discovery fails rather than replacing mappings with a partial list; select fewer resources. Microsoft profile discovery uses batches of twenty; Asana child reads use batches of ten, which still count toward provider rate limits.
Real-account smoke test
- Complete the app/account setup above and configure the three server keys with the exact externally reachable callback.
- Create a Workspace with a Space, a folderless List and a Folder/List. Add tasks with two assignees, custom statuses, a two-hour time estimate, time tracked, a due date, an unestimated/unassigned task and a subtask. Keep one List unselected.
- Connect and select only the first participating resource; Test should succeed, and work in unselected resources should not appear.
- Discover users. Map one to an existing team member, leave another unmapped; no team members should be created. Import one task with explicit local effort and people. For Asana/ClickUp, accept a child suggestion after entering effort.
- Change source title, assignment, status and due date, then Refresh from the project's details. Source facts should update; local effort, people, target/deadline, dependencies and forecast should remain intact. Missing source estimates must remain visible and require an explicit local estimate.
- Connect a second connection to the same provider, select the same resource and import the same external ID into another local project. Mapping and refresh must remain independent. Disable/disconnect one; the other and all local history must survive. Reconnect the original scope; trying another scope requires a new connection.
The local preview and automated tests use simulated HTTP responses. Real OAuth consent, tenant policy/licensing, provider permissions, pagination in large accounts and provider URLs require this real-account smoke test.
Official provider documentation · Integration connections