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.
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 workbench.developerforce.com, 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.
Users:
SELECT Count() FROM User WHERE IsActive=True
SELECT Count() FROM User WHERE IsActive=True AND IsPartner=False
Roles:
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!
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:
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.
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:
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.
Be sure to consider how you are going migrate your users to their new role assignments:
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:
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
At Salesforce, we love giving our admin community a closer look at what’s coming next. In this post, our product managers share sneak peeks of upcoming innovations designed to make your work easier, more efficient, and more impactful. Even if you couldn’t make it to Dreamforce 2025, you can still get a front-row seat to […]
Looking for more True to the Core Deep Dive? In this post, we recap the highlights from our third session on Lightning Experience performance and Agentforce Vibes. This special monthly series builds on the trusted True to the Core format you know and love, offering you a closer, more focused look at specific Salesforce Platform […]
After years of staring at bright screens, managing eye fatigue, and cleaning your blue-light glasses, we’re thrilled to finally launch dark mode (beta) to Starter orgs in Winter ’26. We know you’ve been asking for this feature for years, so we needed to do it right and ensure the experience would be stable across our […]
