Salesforce recently sent out an email entitled
ATTENTION: Update to Permission Set Metadata Deployment in API 40.0 with Summer ‘17

Email contents:

Product & Service Notification

As an admin for a Salesforce org using Permission Set Metadata, we want to notify you that permission set behavior will be changing with the Summer '17 release.

What is Permission Set Metadata?

A permission set is a collection of settings and permissions that give users access to various tools and functions. The Metadata API is used to manage customizations and build tools that can manage the metadata model, including permission sets.

What is changing?

With the Summer '17* release in API version 40.0 and greater, when you retrieve permission set metadata, all metadata API exposed contents for the permission set(s) are retrieved. Retrieval includes Apex associated with the permission set, CRUD, and so forth.

In API version 39.0 and earlier, retrieving permission set metadata returns only app and system permissions that are assigned to the permission set. Junction metadata (such as Apex, CRUD) are only included if the metadata for the related component is also included in the package definition.

**Currently targeted June 2017, but subject to change*

What does this mean for you?

In API 39.0 and earlier, when you deploy your retrieved permission set output to another org, the contents of deployment are merged with your current org data. However, in API version 40.0, when you deploy the output of the retrieval to another org, the target org data is replaced by the metadata in the deployment.

For example, in API version 39.0, if your permission set contains the "Manage Roles" user permission and you deploy a metadata file without this user permission, "Manage Roles" remains enabled. However, in API version 40.0, if you deploy a metadata file without this user permission, "Manage Roles" is disabled.

What action do I need to take?

Understand this behavioral change in API version 40.0 before you deploy permission set data using the metadata API to avoid unintended data overwrites. If an overwrite occurs, use the audit trail as a basis for manually recreating data in your org.

Why is Salesforce making this change?

This change simplifies the metadata packaging definition needed to produce consistent permission set outputs. The consistent output allows changes to be trackable in standard version control systems and aligns with the new Salesforce DX features. This change also allows transfers of permission set content between production, sandbox, and other related orgs to be easier and more predictable.

How can I get more information?

To learn more about permission sets, watch this video Permission Sets in Help and Training. For more information about Salesforce APIs, see https://developer.salesforce.com/.

How will admins and developers need to be aware of this change?

For example:

  • How can you determine the API version of any tooling to see which of the two behaviors will be applied?
  • What will happen if you retrieve metadata about Permission Sets from v39.0 and then deploy that metadata with v40.0?
  • How will this benefit storing Permission Set metadata in source control?
  • Will this impact including Permission Sets in managed packages?

Corresponding Summer '17 Release Notes page: Permission Set Metadata Behavior Change

  • Posted this question as there appears to be some confusion about the impacts of this change. Apr 9, 2017 at 20:25
  • Another example of users not understanding the impact. "I'll be honest, I have no idea what Salesforce emails mean." Apr 9, 2017 at 20:37
  • 2
    Any idea how this is going to effect permission sets included in managed packages?
    – Serena
    Apr 14, 2017 at 22:21
  • @Serena That's an interesting question, because once Summer '17 comes out all managed packages will be created using v40.0. Apr 16, 2017 at 7:59
  • Any changes on the way Profiles behave in change sets? Is the impact only for Permission Sets?
    – Laxman
    Oct 24, 2017 at 16:52

2 Answers 2


By fully retrieving all permissions all the time, it will avoid the various Bad Things that happen when you only retrieve a partial package. This would lead to the XML file spuriously growing very large/small simply based on how the tool you're using decided to retrieve your org's metadata (e.g. a partial retrieve would result in a partial permission set, causing artificial changes that you'd have to continually revert, merge, resolve conflicts, etc). In other words, your source control system will be happy, merges will be happy, deployments will be happy (at least, in theory).

This is part of a larger change that's been rumored, where we will eventually be able to point a source control tree at an org and say "make this org exactly as specified from this source control." No more unexpected surprises, since we will be able to literally recreate an org as it existed at any point in the source control system, potentially even to the point of deleting classes, pages, fields, objects, etc. Of course, all of this is part of the new Salesforce DX experience. Salesforce wants developers, particularly ISVs, to have modern deployment capabilities, and a consistent deployment is part of that vision.

It's okay to retrieve from version 40 and deploy as a lower version, but retrieving as a lower version (e.g. 39) and deploying as 40 may delete permissions that were previously set outside of source control. This is a good thing, because we don't like unexpected permissions, but it does mean you need to get a clean retrieve first. Only deploy a file using 40 or above if you are certain it was retrieved from 40 or above. Your package.xml states the version the API runs with. Realistically, this is a once-per-source-control change developers will need to perform.

The Force.com IDE will automatically capture the new permission sets as part of the Upgrade Wizard that pops up with each new release, so there's little danger of something going wrong there. Developers using other systems, like the Migration Toolkit, must make sure that the first thing they do after changing to version 40 is a full refresh before making any permission set-based deployments.

  • I doubt that anything will be deleted here .Because to delete anything from org we need a destructive XML .This will get more clear once v40.0 is out Apr 9, 2017 at 21:22
  • 1
    @MohithShrivastava Deleting classes and whatnot without a destructiveChanges.xml is not part of Summer '17, nor did I mean to imply that it will be. I am simply saying that the rumor mill is saying that eventually developers will have the ability to set an org's metadata to a precise state of being without having to use destructiveChanges.xml.
    – sfdcfox
    Apr 9, 2017 at 21:25
  • 2
    @MohithShrivastava Maybe not deleted as such, but the email they sent out said a deploy to v40.0 would disable a Permission if it wasn't included. if you deploy a metadata file without this user permission, "Manage Roles" is disabled. Apr 9, 2017 at 21:26
  • 1
    @MohithShrivastava Re-read the paragraph carefully. I am not saying that permissions are deleted (they're unset), I'm saying that this is part of a larger system of control we may eventually have that will allow us to deploy an org's entire state, to the point where the repository literally determines everything that's in the org without having to manually figure out which metadata to delete.
    – sfdcfox
    Apr 9, 2017 at 21:34
  • 1
    @OK999 It applies per permission set(s) being deployed. Permission Sets that are not deployed won't be updated. Any permission set that is deployed will be set explicitly to the values in the file, and all other permissions will be removed.
    – sfdcfox
    Oct 17, 2017 at 17:27

Here is what I infer from the email and my experience with salesforce metadata API

Permission set does not have API version tied to it in the metadata XML file .So the question on how do I determine the version of permission set ?It is the version of package.xml that we must be aware of .

So lets answer the queries

1.How can you determine the API version of any tooling to see which of the two behaviors will be applied?

Its from package.xml version .


2.What will happen if you retrieve metadata about Permission Sets from v39.0 and then deploy that metadata with v40.0?

Since you are deploying with v40.0 while you have retrieved using 39.0 no overrides should happen .The mail mentions that junction metadata related to the PermissionSet is not retrieved with 39.0 while v40.0 bring all the related metadata like CRUD access and apex along and potentially could overwrite .

3.How will this benefit storing Permission Set metadata in source control?

The dependency is also maintained in your source control automatically without you having to manually worrying about adding dependency metadata to the source control .

To test this as soon as I will have v40.0 org ,summer 17 pre release org ,you will need to create an unmanaged package with permission set added to it and clicking on add dependencies should add all the dependent metadata related to the permission set automatically or I guess salesforce will automatically add all dependent metadata for us .This is consistency to me which platform was missing from long time .

  • 1
    Thanks Mohith. I agree that we will need to wait until Summer '17 orgs become available before we can really test the impact of this change. Apr 9, 2017 at 21:01

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .