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
Best Answer
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.