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

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.

Splitting profiles into individually deployable components

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.

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

Apex class permissions
Apex page permissions
Custom field permissions
Custom object permissions
Layout permissions
Profile Password Policy
Profile Session Setting
Profile: Apex class access
Profile: Apex page access
Profile: Application visibility
Profile: Custom permissions
Profile: External data source access
Profile: Field level security
Profile: Layout assignment
Profile: Object permission
Profile: Record type visibility
Profile: Set of user permissions for a new profile
Profile: Tab visibility
Profile: User permission

Configuring your metadata filter to get the profile changes you want

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 only get the Profile and Profile: User permission types in the results. Other subcomponent types won't appear.

So which metadata types should you include in the custom filter to retrieve each individual part?

We created 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:

  • The Custom Filter column lists the metadata types you need to select in Gearset's custom metadata filters to retrieve the profile component
  • The 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
  • Note: for Profile + X, X can be substituted with any other metadata type that has a junction metadata with Profile, e.g. Custom object 

Some examples

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.

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.

Got questions? Get in touch

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.

Did this answer your question?