PermissionSet

This type extends the Metadata metadata type and inherits its fullName field.

In API version 40.0 and later, when you retrieve permission set metadata, all content exposed in Metadata API for the permission sets is included. The metadata includes Apex associated with the permission set, CRUD, and so on. Likewise, when you deploy a permission set, you must include all of its metadata to avoid accidentally overwriting the permission set’s contents.

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

In API version 29.0 and later, you can retrieve and deploy access settings for these managed components in profiles and permission sets:

For more information, see the Managed Component Access section of Sample package.xml Manifest Files in the Metadata API Developer Guide.

Declarative Metadata File Suffix and Directory Location

Permission sets are stored in the permissionsets directory. The file name matches the permission set API name and the extension is .permissionset. For example, a permission set with the name User_Management_Perms is stored in permissionsets/User_Management_Perms.permissionset.

Version

Permission sets are available in API version 22.0 and later.

Special Access Rules

Fields

PermissionSetAgentAccess

PermissionSetAgentAccess represents the agent access configuration for users assigned through a permission set.

PermissionSetApplicationVisibility

PermissionSetApplicationVisibility determines whether an app is visible to a user assigned to this permission set.

PermissionSetApexClassAccess

PermissionSetApexClassAccess represents the Apex class access for users assigned to a permission set.

PermissionSetCustomMetadataTypeAccess

PermissionSetCustomMetadataTypeAccess represents the custom metadata type access for users assigned to a permission set. Available in API version 47.0 and later.

PermissionSetCustomPermissions

PermissionSetCustomPermissions represents the custom permissions access for users assigned to a permission set. Only enabled custom permissions are retrieved.

PermissionSetCustomSettingAccesses

PermissionSetCustomSettingAccesses represents the custom setting access for users assigned to a permission set. Available in API version 47.0 and later.

PermissionSetEmailRoutingAddressAccess

PermissionSetEmailRoutingAddressAccess represents the Email Routing Address access for users assigned to a permission set. Only enabled email routing addresses are retrieved.

PermissionSetExternalCredentialPrincipalAccess

PermissionSetExternalCredentialPrincipalAccess represents the access to the external credential’s principals. Users assigned to the permission set can make callouts using a named credential that references the external credential. Available in API version 59.0 and later.

PermissionSetExternalDataSourceAccess

PermissionSetExternalDataSourceAccess represents the data source access for users with identity type of Per User. Available in API version 27.0 and later.

PermissionSetFieldPermissions

PermissionSetFieldPermissions represents the field permissions for users assigned to a permission set. In API version 30.0 and later, permissions for required fields can’t be retrieved or deployed. In API version 54.0 and later, only field permissions enabled in the permission set are returned in queries.

As of API version 38.0, you can change field permissions to make a field editable using the Metadata API for fields that you can't change through the user interface. For example, you can deploy Asset.ProductCode as an editable field even though you can't through the user interface.

PermissionSetFlowAccess

PermissionSetFlowAccess represents which flows a permission set grants access to. Available in API version 47.0 and later.

PermissionSetObjectPermissions

PermissionSetObjectPermissions represents the object permissions for a permission set. Use one of these elements for each permission.

PermissionSetApexPageAccess

PermissionSetApexPageAccess represents the Visualforce page access for users assigned to a permission set.

PermissionSetRecordTypeVisibility

PermissionSetRecordTypeVisibility represents the visibility of record types for this permission set.

PermissionSetTabSetting

PermissionSetTabSetting represents the tab settings for a permission set.

PermissionSetUserPermission

In API version 28.0 and earlier, PermissionSetUserPermission represents an app or system permission for a permission set. In API version 29.0 and later, this field retrieves only enabled user permissions. Use one of these elements for each permission.

PermissionSetServicePresenceStatusAccess

Represents the presence statuses that reps assigned to this profile have access. Available in API version 64.0 and later.

Declarative Metadata Sample Definition

The following is an example of a PermissionSet component.

<?xml version="1.0" encoding="UTF-8"?>
<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>Grants all rights needed for an HR administrator to manage employees.</description>
    <label>HR Administration</label>
    <userLicense>Salesforce</userLicense>
    <applicationVisibilities>
        <application>JobApps__Recruiting</application>
        <visible>true</visible>
    </applicationVisibilities>
    <userPermissions>
        <enabled>true</enabled>
        <name>ApiEnabled</name>
    </userPermissions>
    <objectPermissions>
        <allowCreate>true</allowCreate>
        <allowDelete>true</allowDelete>
        <allowEdit>true</allowEdit>
        <allowRead>true</allowRead>
        <viewAllRecords>true</viewAllRecords>
        <modifyAllRecords>true</modifyAllRecords>
        <viewAllFields>true</viewAllFields>
        <object>Job_Request__c</object>
    </objectPermissions>
    <fieldPermissions>
        <editable>true</editable>
        <field>Job_Request__c.Salary__c</field>
        <readable>true</readable>
    </fieldPermissions>
    <pageAccesses>
        <apexPage>Job_Request_Web_Form</apexPage>
        <enabled>true</enabled>
    </pageAccesses>
    <classAccesses>
      <apexClass>Send_Email_Confirmation</apexClass>
      <enabled>true</enabled>
    </classAccesses>
    <tabSettings>
        <tab>Job_Request__c</tab>
        <visibility>Available</visibility>
    </tabSettings>
    <recordTypeVisibilities>
        <recordType>Recruiting.DevManager</recordType>
        <visible>true</visible>
    </recordTypeVisibilities>
</PermissionSet>

The following is an example package.xml manifest used to retrieve the PermissionSet metadata for an organization. When you retrieve permission sets, also retrieve the related components with assigned permissions. For example, to retrieve objectPermissions and fieldPermissions for a custom object, you must also retrieve the CustomObject component.

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Job_Request__c</members>
        <name>CustomTab</name>
    </types>
    <types>
        <members>Job_Request__c</members>
        <name>CustomObject</name>
    </types>
    <types>
        <members>JobApps__Recruiting</members>
        <name>CustomApplication</name>
    </types>
    <types>
        <members>Recruiting.DevManager</members>
        <name>RecordType</name>
    </types>
    <types>
        <members>*</members>
        <name>PermissionSet</name>
    </types>
    <version>64.0</version>
</Package>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.