Help! My Role Hierarchy is a Mess


Is your role Hierarchy a mess? Did you inherit a role hierarchy that hasn’t been maintained? Was it last edited by me like nine years ago? (There’s only a small chance of this. But if so, I am sorry.)

Don’t worry we are here to help! You see, things change over time and so too must your role hierarchy. The roles you once used may not match your current needs. Unwinding such a mess may sound extremely time consuming and overwhelming. This blog post will go through some different options, tools and techniques you can use to address a messy role hierarchy.

A friendly note from Codey about Partner Roles:
If you use the partner community it may be a good idea to filter out those roles so you can focus on internal company roles only.

First – you need to do some research!

When it comes to reviewing your roles, sure you can just look at Setup. But, to look deeper we can use SOQL. While typically used by developers, SOQL can be used by any Admin using tools like Workbench or the Developer Console. Workbench is an open-source community supported tool that allows you to test various integrations and queries. It’s simple to use; just navigate to, log into your sandbox (not production), click “queries” in the top menu and copy and paste the code below into the large text area and then click query.

A good place to start is to find a list of roles that aren’t assigned to any users. Here is an SOQL query you can run in Workbench.

*Update: As of Summer ’17 the Salesforce Optimizer now reports on roles that aren’t assigned to any users.*

SELECT Id, Name FROM UserRole WHERE Id NOT IN (SELECT UserRoleId FROM User WHERE UserRoleId !=’000000000000000′ And IsActive=TRUE)

To filter out Partners:

SELECT Id, Name FROM UserRole WHERE Id NOT IN (SELECT UserRoleId FROM User WHERE UserRoleId !=’000000000000000′ And IsActive=TRUE And IsPartner=False)

Do you have lots of roles with no users assigned? They are ripe for removal!

Now you may want to determine your role to user ratio by getting a total count of users and roles.


SELECT Count() FROM User WHERE IsActive=True

SELECT Count() FROM User WHERE IsActive=True AND IsPartner=False


SELECT Count() FROM UserRole

SELECT Count() FROM UserRole WHERE IsPartner=False

What is your org’s user to role ratio? Salesforce orgs vary dramatically–one may have 10 users and another may have 10,000 users–so there is no hard and fast rule on what is an acceptable ratio. Personally, for the best performance and maintainability, I like to see something around 10:1 in an optimized org. Generally the closer you are to a 1:1 ratio, the more cleanup or consolidation may be needed.

How many sharing rules does your org have? Take a look at your Sharing Settings page in Setup. Having lots of sharing rules can point to having an under-performing role hierarchy. You should also take note of any sharing rules as they may need to be removed or updated based on your new design.

Ensure you know exactly how roles are used and consider that they don’t necessarily need to match your actual company hierarchy. Roles should be designed to reflect data access, not your company’s org chart. A common error is to create a role for every position in your company which may not be required. Check out the Data Security Trail that goes over role hierarchy for more information.

You can do some further research using the Salesforce Optimizer and Org Doctor (part of the free SFToolKit) to get even more information about your roles and other areas of the system.

Now that you learned a bit about the roles in your org, you need to do some research on your business needs. Poor role hierarchies often cause issues and complexity with data access and reporting. What are your unique business requirements? Why is the existing role hierarchy not working for your business? Where is it causing problems? Document the feedback from various stakeholders.

Ok enough research – let’s do something about this mess!

Decide on an Approach

So now you have two basic choices: Should you get out a bucket and sponge and go through your role hierarchy role by role and clean it all up (otherwise known as “The Big Clean”) or should you create a brand new role hierarchy leaving your old hierarchy in the past – otherwise known as “Start Fresh”?

The Big Clean can be done by exporting all the roles using Data Loader or Workbench, including their Ids. Here is some more SOQL for you:

SELECT Id, DeveloperName FROM UserRole

SELECT Id, DeveloperName FROM UserRole WHERE Is Partner=False

Now you need to go through each role and take some notes. Things like:

  • Why was it created, by whom and when?
  • How many users are assigned? (You may want to eliminate roles that were unassigned)
  • Is the role still needed?
  • Can it be merged with a similar role?
  • Should the role be removed?

Use the research you conducted earlier to guide you in your decision-making.

Starting Fresh may be a good option if your business has radically changed, or if it will take a longer time to review each and every role as part of a big clean.

I have personally been involved in many time-consuming org cleanups that have taken months to complete and once we got to the end of the process we realized – hindsight being 20/20 – that it would have been easier to just start fresh as opposed to trying to retrofit the existing structure into what we wanted it to become.

The great thing about this option is that Salesforce will allow you to build a new role hierarchy in parallel with the old one! Create a temporary placeholder role for the new role hierarchy under the top-most role so you can build out your new set of roles. Later, when you deploy you can re-parent your top level roles from the placeholder to the top most role and delete the placeholder role.

Keep in mind, most Salesforce org’s have a default limit of 500 roles. Contact support if you think you are going to need more.

Tip from Astro: Do you have many inactive users assigned to Roles you plan on deleting? Salesforce won’t allow you to delete a role unless there are no users assigned. Consider creating an “Old Employees” role for your distinguished alumni and migrate all of your inactive users to this role.

How do you know which option to choose? Well, the simplest way may be to evaluate both options and determine which one would take less time. If your business has radically changed or if the role hierarchy hasn’t been maintained in years then Start Fresh is for you. If you want to maintain the overall structure but eliminate old and unused roles and merge a few others together then The Big Clean is the way to go.

Keep in mind sharing rules when designing your role hierarchy. In fact, one of the goals of a Role Hierarchy Redesign may be to reduce the number of sharing rules so as to reduce complexity in your sharing and security setup. Carefully review sharing rules since it’s very likely that if there are many role changes there will be corresponding changes needed to your sharing rules.

Build and Test

Since large-scale changes to a role hierarchy can have a dramatic impact on how Salesforce controls visibility, you should test your changes in a sandbox. You should test all of your changes in a Sandbox. Also, did I mention you should test your changes in a Sandbox? Ok, just checking to make sure you are still paying attention!

Another Astro Tip: You need to be on the lookout for any customizations that directly reference a role you may be removing, like validation rules, workflows, sharing rules, folder and list view access, apex, visualforce etc., which may need to be updated as part of this process.

Here is a checklist of things you need to test in a Sandbox:

  • Create new roles
  • Re-parent any existing roles as needed
  • Update Sharing Rules
  • Verify security and sharing settings by logging in as various users/roles
  • Update any other customizations that reference Roles
  • Migrate users
  • Delete old roles
  • Go through a UAT cycle

Keep in mind that when you modify which users are in a group, role, or territory, the sharing rules are reevaluated to add or remove access as necessary. There are Tools for Large-Scale Realignments that can help speed up the process of making mass updates to your role hierarchy and user assignments. When making a change to your role hierarchy, you may get locked out of making further changes while the sharing rules are recalculated. This is normal and you should plan for it. However when making lots of changes, look into Deferred Sharing Maintenance to allow you to make many changes at once.

Deploy to Production

Be sure to consider how you are going migrate your users to their new role assignments:

  • By point and click
  • All at once using a tool like the data loader
  • In smaller groups

Set aside specific maintenance windows to complete the migration, ideally outside of business hours. This will ensure minimal business impact while the system is being updated.

Basic steps you should take:

  1. Backup roles and their user assignments
  2. Deploy new roles (via change set or other method)
  3. Re-arrange role hierarchy as needed
  4. Migrate users to their new role
  5. Remove unneeded roles

You can check out this cool free app by Qandor called Draggin’ Role. It allows you to drag and drop your way through any hierarchy modifications.

If you are deleting roles and require a detailed process for decommissioning customization in Salesforce check out this blog post on cleaning up technical debt.

Well there you have it – a squeaky clean role hierarchy! Now that wasn’t so bad, was it?

Other Resources:
Who Sees What: Record Access via Sharing Rules

Designing Record Access for Enterprise Scale

Record-Level Access: Under the Hood

A Guide to Sharing Architecture

Cloudy standing with a laptop next to text that says "Admin Best Practices User Management."

Admin Best Practices for User Management

Managing users is a core Salesforce Admin skill. One element of this skill is ensuring that each user has access to the right data so they can do their job. As admins, we also need to protect data that may be confidential, preventing users who don’t need to access that data from viewing, editing, or […]

Introducing Customer Service Incident Management

Build Customer Trust with Customer Service Incident Management

Since COVID-19, we’ve witnessed a remarkable transformation as more companies go digital to run their business from anywhere. While digital transformation has enabled so many companies to innovate in their service offerings, it has also introduced a new challenge: ensuring availability and uptime of those services. The reality is that a service disruption is inevitable. […]

Cloudy, Astro, and a snowman next to text that says, "LeeAnee's Ultimate 2021 Design Thinking Playlist."

LeeAnne’s Ultimate 2021 Design Thinking Playlist

As Salesforce Admins, we’re constantly working to design engaging and delightful user experiences. Whether we’re building custom pages with App Builder, customizing a mobile experience, or creating a useful and compelling dashboard, design is core to the work we do. With all of the new product releases and enhancements happening on the Salesforce Platform, especially […]


Have an Idea for a Story?

We are all about the community and sharing ideas.
Do you have an interesting idea or useful tip that you want to share?