Server and account setup
Create a distributable Asana OAuth app and register the exact HTTPS callback /cloudwork/callback. Enable the listed granular read scopes. Make the app available to the target workspace and connect as a user who can access the selected projects. OAuth uses PKCE and a server-held client secret; access tokens refresh automatically.
Configure Asana:ClientId, Asana:ClientSecret, Asana:RedirectUri in the server secret store/environment (for example Asana__ClientSecret). Do not commit secrets. All three providers use /cloudwork/callback, with distinct app registrations and secure provider-bound state. Required permissions: workspaces:read projects:read project_sections:read tasks:read users:read.
Connect and select work
An administrator opens Settings → Integration connections, adds a Asana 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 active projects in one workspace; title, notes, completion status, assignee, due date, source URL and child suggestions. Tasks belonging to multiple selected projects are deduplicated. Native estimated-time display text is retained; arbitrary custom numeric fields and points are not converted into minutes. Supply local effort explicitly.
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 project with assigned/unassigned tasks, a due date, a completed task, a subtask without its own project membership, and another unselected project. If available, add the native Estimated time field.
- 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