Profiles are one of the most complex metadata types in Salesforce, and are notoriously hard to migrate with change sets or the command line. 

(In the context of permissions, the Profile metadata type in this article can also be substituted by Custom permission and Permission set metadata types, as they work on the same principle as Profile.)

Gearset makes managing profile changes much easier by breaking them down into small components and intelligently stitching the files together as part of your deployment. This article explains how profiles work in Gearset and how to deploy the changes you're after.

Profiles are large objects in Salesforce. To help make managing them easier, Gearset breaks down the profile metadata API object into its individual subcomponents. Each component is individually deployable without affecting the other parts of the profile. 

This gives fine-grained control over what changes you migrate. For example, you can migrate just a single field level security setting without affecting the rest of the profile.

Because Gearset separates profiles into these individual subcomponents, the parent profile will show up in comparisons as No difference even if the subcomponents, such as tab visibility, have been changed. You can find the changed subcomponents by expanding out the components of the parent object in the comparison table, or by searching up their names in the filter.

In Gearset, profiles are split into the following subcomponent types:

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.

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.

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:

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.

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).

In the screenshot below, Profile: Tab visibility is found by selecting Profile and Custom object metadata types in the Manage custom filters view, and displayed as a component of the parent Profile.

Whereas Profile: Application visibility is found by selecting Profile and Custom application metadata types in the Manage custom filters view, and displayed as a top level item in its own right.

Sometimes, you may run into order-dependency issues when trying to deploy changes to Profiles. Here’s one example for Profile MyCustomerSuccess

When you try to deploy this, Salesforce first removes the D(elete) 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.

Hopefully this article will make it easier to know how to track down constituent parts of the profile object for your deployment. If you have any questions, let us know.