Server and account setup
Create an Entra ID confidential Web app for work/school accounts (multi-tenant if other organisations will connect). Register the exact HTTPS callback /cloudwork/callback. Add delegated Microsoft Graph permissions Tasks.Read, User.Read and User.ReadBasic.All; request offline_access. Tenant policy may require administrator consent. Use a user with a Planner licence and membership/access to a basic plan. Personal Microsoft accounts and premium plans are not supported.
Configure Planner:ClientId, Planner:ClientSecret, Planner:RedirectUri in the server secret store/environment (for example Planner__ClientSecret). Do not commit secrets. All three providers use /cloudwork/callback, with distinct app registrations and secure provider-bound state. Required permissions: offline_access User.Read Tasks.Read User.ReadBasic.All.
Connect and select work
An administrator opens Settings → Integration connections, adds a Microsoft Planner 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
Basic plans shared with the authenticated user; title, description on direct import/refresh, all task assignments, percent-complete status and due date. No standard estimate, checklist-to-stage conversion, premium plans 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 basic plan shared with the connecting user, two tasks (one assigned, one unassigned), a due date and a completed task. Create a second unselected plan.
- 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