What happens when you transition to roles? Conflicting documentation

[Laura Campbell_Seibert]

I'm trying to understand what happens when you activate roles on your site.

This documentation page https://confluence-permissions-help.atlassian.net/wiki/external/MTllYzg0YjViNDUzNDMxYjgxZGM4Y2IwNDg4NmE4YzI#How-to-transition-to-roles says "First, any user or group with a permissions configuration that exactly matches a role will automatically be assigned that role as soon as the role experience lands on your site. Otherwise, they will display with “Custom access.”"

However, this documentation https://support.atlassian.com/confluence-cloud/docs/custom-access-and-how-to-transition-to-roles/ says "As soon as the role experience lands on your site, all users and groups access will display with “Custom access”. This allows the system to maintain the exact permissions configuration they had in the new role-based model."

Will users or groups with permissions that match a role indeed be automatically assigned a role? Or will everyone be with "custom access" until you assign them a role?

[Ben Spillane]

Hi Laura, 

Which documentation you've sighted is correct? I believe neither are incorrect from a practical perspective. 

Real-World Migration Experience

I’ve managed several Cloud-to-Cloud migrations recently and am currently navigating a DC-to-Cloud transition. Regarding your specific scenario—moving from a legacy permissions setup to a site with Confluence Roles—here is what I’ve observed:

• The Outcome: In my experience, users transitioned with "Custom Access" permissions by default.
• The Caveat: This isn't a "one size fits all" rule. The final result is often context-based depending on your specific source configurations.

Post-migration, I streamlined permissions by migrating users from legacy custom access to native Confluence roles.

---

Why permissions may rarely map exactly to roles

Atlassian has moved from ~13+ granular checkboxes to 4 standard Roles. "Custom access" is triggered whenever a user’s current permissions have even one single deviation from the preset role templates.

1. The Standard Role Blueprints

For a user to be automatically assigned a role, their permissions must exactly match one of these four templates:

Role	Core Purpose	Key Permissions
Admin	Space Ownership	All permissions, including Delete Space, Export Space, and Manage Access.
Manager	Team/Content Lead	Can manage content and user access, but cannot delete the space or change anonymous access settings.
Collaborator	Active Contributor	Can view, create, edit, and delete their own content/comments.
Viewer	Consumer	View and comment only. No editing or creating pages.

2. Deep Dive: Why "Custom Access" Triggers

The transition fails to "auto-match" if your manual setup created a hybrid user. Here are the most common misalignment scenarios:

A. The "Partial Admin" Problem

• The Scenario: You want someone to manage permissions but you don't want them to be able to Export the entire space.
• The Result: Since the Admin role includes Export, and the Manager role excludes it, this user fits neither.
• Status: Trigger "Custom access."

B. The "Restricted Editor" Problem

• The Scenario: You have a user who can Edit pages but you’ve unchecked their permission to Delete their own pages.
• The Result: The Collaborator role assumes if you can create it, you can delete it.
• Status: Trigger "Custom access."

C. The "Split Permissions" Legacy

Atlassian recently split older permissions into smaller pieces (e.g., "Edit" is now distinct from "Create").

• The Scenario: If you have an old group that had "Add" but not "Update," the system sees this as a gap that doesn't fit the new Collaborator role.
• Status: Trigger "Custom access."

3. The "Additive Permissions" Logic

This is the most complex reason for "Custom access." In Confluence, permissions are additive:

If User A is in Group 1 (Viewer) AND Group 2 (Collaborator), their total access is Collaborator. 

• The Conflict: If you assign a specific role to the group, but then manually check an extra box for the individual user, the system sees the individual's "total" permission set as a unique combo. It will label that individual as "Custom access."

Regards,

Ben