Salesforce recently sent out an email entitled
ATTENTION: Update to Permission Set Metadata Deployment in API 40.0 with Summer ‘17
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?
- 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