Why are profiles different?
Profiles are different to many other metadata types on the metadata API. The subcomponents returned by Salesforce for a profile depend on the other metadata types in your metadata filter. More information on Profiles can be found here.
For example, if you select just the Profile metadata type in your custom metadata filter and run a comparison, you'll get only the user permissions of the Profile.
So which metadata types should you include in the custom filter to retrieve each individual part?
We created a Default profiles and permission sets comparison filter for those of you that don't need the details further below. Not sure how to manage your custom metadata filter? See here.
Here is a handy reference table showing you which other metadata types you'll need to include in your filter to get each subcomponent type in your profile:
Metadata Type in results page | Custom Filter | Top level or Component |
Apex class permissions | Profile + Apex class | Top level |
Apex page permissions | Profile + Apex page | Top level |
Custom field permissions | Profile + Custom object | Top level |
Custom object permissions | Profile + Custom object | Top level |
Flow permissions | Profile + Flow definition | Top level |
Layout permissions | Profile + Layout + (Custom object) | Top level |
Profile | Top level | |
Profile Password Policy | Top level | |
Profile Session Setting | Top level | |
Profile: Apex class access | Profile + Apex class | Component |
Profile: Apex page access | Profile + Apex page | Component |
Profile: Application visibility | Profile + Custom application | Top level |
Profile: Custom permissions | Profile + Custom permissions | Top level |
Profile: External data source access | Profile + External data source | Component |
Profile: Field level security | Profile + Custom object | Component |
Profile: Layout assignment | Profile + Layout | Component |
Profile: Object permission | Profile + Custom object | Component |
Profile: Record type visibility | Profile + Custom object | Component |
Profile: Set of user permissions for a new profile | Profile | Top level |
Profile: Tab visibility | Profile + Custom object + Custom Tab | Top level |
Profile: User permission | Profile | Top level |
Profile: Flow access | Profile + Flow definition | Component (API' 44 or below) |
The Custom Filter column lists the metadata types you need to select in Gearset's custom metadata filters to retrieve the profile component
Custom metadata
has the permissions retrieved as Custom object permissionsThe Top level or Component column defines if the profile component will appear as a top level item in the results, or is a subcomponent of another top level item
To view subcomponent items, you may need to expand out its parent object in the comparison results, see examples below.
System permissions are located within the Profile metadata type, and you just need Profile metadata type to retrieve that in Gearset.
Examples
Profile: Field level security
Since this is under component in the table, select the profile with the FLS changes and using the dropdown arrow, find components.
In my metadata filter I have Profile
and Custom object
selected. Once you have expanded components you should be able to see all the FLS that you expected to see.
Intra-Profile Dependencies
Sometimes, you may run into order-dependency issues when trying to deploy changes to Profiles. Here’s one example for Profile MyCustomerSuccess
Item | Profile source org | Profile target org |
CRUD on Case (objectPermission) | R - C - E - | R - C - E - D - |
Manage Cases (userPermission) |
|
|
When you try to deploy this, Salesforce first removes the Delete (D) and Modify All permission from the Profile in the target org and then immediately throws up a Validation Error: “Manage Cases requires delete permission”.
There are two options for working around this:
Option 1: Do two deployments - one to remove Manage Cases
permission first, then a second deployment to remove D and Modify All
from Case.
Option 2: Go into the target org and manually remove Manage Cases
user permission. Then deploy the object permissions via Gearset.
Apex class permissions
Since this is under Top level
in the table, you can see the Apex class permissions in the comparison table.
In my metadata filter I have Profile
and Apex class
selected.
Deploying profiles that are entirely new
If a profile is completely new - it does not exist at all in the target environment for your deployment - it will always appear as a single item in your comparison results with a change type of New.
In this case, you'll need to deploy the entire profile object. You can't select a subcomponent to deploy as the profile framework does not yet exist in the target environment.
If you want to work around this limitation on new profiles, you can try creating the profile manually in your target environment as a blank placeholder. When you refresh your comparison, Gearset will then be able to deploy any changed subcomponents.
Please note: You will still need to include the relevant metadata types in your filter to ensure each component of the new profile is retrieved).
When deploying an entirely new profile, you will also run into this Salesforce metadata API behavior here. This will cause some false custom object (and others) permissions to be set to true on the target org after deployment based on the Standard User
profile in your target org.
To address this behavior, it is recommended to deploy an entirely new profile in two steps: First the new profile itself, then in a second deployment all the custom permissions that were missed due to the above behavior.
Deploying permissions from multiple profiles
Gearset also makes it possible and easy to deploy the permissions of an item across multiple profiles and/or permission sets. The following 6 groupings of metadata types allow you to deploy the permission of not just one profile at a time, but of multiple profiles in one go.
Apex class permissions
Apex page permissions
Custom object permissions
Custom field permissions
Flow permissions
Layout permissions
What should I do if I get stuck with anything?
If you ever need support, just contact our live chat support by clicking the blue button in the bottom right in every Gearset screen.
A real human (no robots here) will get back to you very quickly! We typically reply in under 15 minutes.