All Collections
Compare and deploy metadata
Guides on deploying specific metadata types
Guides on deploying specific metadata types
Profiles - how to retrieve profiles and their components using Gearset's metadata filter
Profiles - how to retrieve profiles and their components using Gearset's metadata filter

Guidance on how to use the metadata filter to find and deploy changes to Profiles.

Quinn Kuiper avatar
Written by Quinn Kuiper
Updated this week

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

Component

Profile + Apex page

Component

Profile + Custom application

Top level

Profile + Custom permissions

Top level

Profile + External data source

Component

Profile + Custom object

Component

Profile + Layout

Component

Profile + Custom object

Component

Profile + Custom object

Component

Profile: Set of user permissions for a new profile

Profile

Top level

Profile + Custom object + Custom Tab

Top level

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

  • 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, 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.

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

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.

Did this answer your question?