Newer Version Available

This content describes an older version of this product. View Latest

PermissionSet

Represents a set of permissions that's used to grant additional access to one or more users without changing their profile or reassigning profiles. You can use permission sets to grant access, but not to deny access. This type extends the Metadata metadata type and inherits its fullName field.

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

Apex classes
Apps
Custom field permissions
Custom object permissions
Custom tab settings
External data sources
Record types
Visualforce pages

For more information, see Managed Component Access in Sample package.xml Manifest Files.

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.

Fields

Field	Field Type	Description
applicationVisibilities	PermissionSetApplicationVisibility[]	Indicates which apps are visible to users assigned to this permission set. Available in API version 29.0 and later. In API version 29.0, this field supports custom apps only. In API version 30.0 and later, this field supports both standard and custom apps.
classAccesses	PermissionSetApexClassAccess[]	Indicates which top-level Apex classes have methods that users assigned to this permission set can execute. Available in API version 23.0 and later.
customPermissions	PermissionSetCustomPermissions[]	Indicates which custom permissions are available to users assigned to this permission set. Available in API version 31.0 and later.
description	string	The permission set description. Limit: 255 characters.
externalDataSourceAccesses	PermissionSetExternal DataSourceAccess[]	Indicates which data sources with identity type of Per User are available to users assigned to this permission set. Available in API version 27.0 and later.
fieldPermissions	PermissionSetFieldPermissions[]	Indicates which fields are accessible to a user assigned to this permission set, and the kind of access available (readable or editable). Available in API version 23.0 and later.
hasActivationRequired	boolean	Indicates whether the permission set requires an associated active session (`true`) or not (`false`). Available in API version 37.0 and later.
label	string	Required. The permission set label. Limit: 80 characters.
objectPermissions	PermissionSetObjectPermissions[]	Indicates the objects that are accessible to a user assigned to this permission set, and the kind of access available (create, read, edit, delete, and so on). Available in API version 23.0 and later.
pageAccesses	PermissionSetApexPageAccess[]	Indicates which Visualforce pages that users assigned to this permission set can execute. Available in API version 23.0 and later.
recordTypeVisibilities	PermissionSetRecordTypeVisibility[]	Indicates which record types are visible to users assigned to this permission set. Available in API version 29.0 and later. This field is never retrieved or deployed for inactive record types.
tabSettings	PermissionSetTabSetting[]	Indicates the tab visibility settings for this permission set. Available in API version 26.0 and later.
userLicense	string	The User License for the permission set. A user license determines the baseline of features that the user can access. Every user must have exactly one user license.
userPermissions	PermissionSetUserPermission[]	Specifies an app or system permission (such as “API Enabled”) and whether it's enabled for this permission set. In API version 28.0 and earlier, this field retrieves all user permissions, enabled or disabled. In API version 29.0 and later, this field retrieves only enabled user permissions.

PermissionSetApplicationVisibility

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

Field Name	Field Type	Description
application	string	Required. The app name.
visible	boolean	Required. Indicates whether this app is visible to users assigned to this permission set (`true`) or not (`false`).

PermissionSetApexClassAccess

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

Field	Field Type	Description
apexClass	string	Required. The Apex class name.
enabled	boolean	Required. Indicates whether users assigned to this permission set can execute methods in the top-level class (`true`) or not (`false`).

PermissionSetCustomPermissions

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

Field Name	Field Type	Description
enabled	boolean	Required. Indicates whether the custom permission is enabled (`true`) or not (`false`).
name	string	Required. The custom permission name.

PermissionSetExternalDataSourceAccess

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

Field	Field Type	Description
enabled	boolean	Required. Indicates whether the data source is enabled (`true`) or not (`false`).
externalDataSource	string	The name of the external data source.

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.

Field	Field Type	Description
editable	boolean	Required. Indicates whether the field can be edited by the users assigned to this permission set (`true`) or not (`false`).
field	string	Required. The API name of the field (such as `Warehouse__c.Description__c`).
readable	boolean	Indicates whether the field can be read by the users assigned to this permission set (`true`) or not (`false`).

PermissionSetObjectPermissions

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

Field	Field Type	Description
allowCreate	boolean	Required. Indicates whether the object referenced by the object field can be created by the users assigned to this permission set (`true`) or not (`false`).
allowDelete	boolean	Required. Indicates whether the object referenced by the object field can be deleted by the users assigned to this permission set (`true`) or not (`false`).
allowEdit	boolean	Required. Indicates whether the object referenced by the object field can be edited by the users assigned to this permission set (`true`) or not (`false`).
allowRead	boolean	Required. Indicates whether the object referenced by the object field can be viewed by the users assigned to this permission set (`true`) or not (`false`).
modifyAllRecords	boolean	Required. Indicates whether the object referenced by the object field can be viewed, edited, or deleted by the users assigned to this permission set (`true`) or not (`false`), regardless of the sharing settings for the object. This includes private records (records with no parent object). This is similar to the “Modify All Data” user permission, but limited to the individual object level.
object	string	Required. The API name of the object (such as `Warehouse__c`).
viewAllRecords	boolean	Required. Indicates whether the object referenced by the object field can be viewed by the users assigned to this permission set (`true`) or not (`false`), regardless of the sharing settings for the object. This includes private records (records with no parent object). This is similar to the “View All Data” user permission, but limited to the individual object level.

PermissionSetApexPageAccess

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

Field	Field Type	Description
apexPage	string	Required. The Visualforce page name.
enabled	boolean	Required. Indicates whether users assigned to this permission set can execute the Visualforce page (`true`) or not (`false`).

PermissionSetRecordTypeVisibility

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

Field	Field Type	Description
recordType	string	Required. The record type name, for example `Account.MyRecordType`.
visible	boolean	Required. Indicates whether the record type is visible to users assigned to this permission set (`true`) or not (`false`).

PermissionSetTabSetting

PermissionSetTabSetting represents the tab settings for a permission set.

Field	Field Type	Description
tab	string	Required. The tab name.
visibility	PermissionSetTabVisibility (enumeration of type string)	Required. Indicates the visibility settings for the tab. Valid values are: `Available`—The tab is available on the All Tabs page. Individual users can customize their display to make the tab visible in any app. `None`—The tab isn’t available on the All Tabs page or visible in any apps. `Visible`—The tab is available on the All Tabs page and appears in the visible tabs for its associated app. Individual users can customize their display to hide the tab or make it visible in other apps.

PermissionSetUserPermission

PermissionSetUserPermission represents an app or system permission for a permission set. Use one of these elements for each permission.

Field	Field Type	Description
enabled	boolean	Required. Indicates whether the permission is enabled (`true`) or disabled (`false`).
name	string	Required. The name of the permission.

Declarative Metadata Sample Definition

When adding or changing a permission set, you don't need to include all permissions—you only need to include the permissions you're adding or changing.

1<?xml version="1.0" encoding="UTF-8"?>
2<PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
3    <description>Grants all rights needed for an HR administrator to manage employees.</description>
4    <label>HR Administration</label>
5    <userLicense>Salesforce</userLicense>
6    <applicationVisibilities>
7        <application>JobApps__Recruiting</application>
8        <visible>true</visible>
9    </applicationVisibilities>
10    <userPermissions>
11        <enabled>true</enabled>
12        <name>APIEnabled</name>
13    </userPermissions>
14    <objectPermissions>
15        <allowCreate>true</allowCreate>
16        <allowDelete>true</allowDelete>
17        <allowEdit>true</allowEdit>
18        <allowRead>true</allowRead>
19        <viewAllRecords>true</viewAllRecords>
20        <modifyAllRecords>true</modifyAllRecords>
21        <object>Job_Request__c</object>
22    </objectPermissions>
23    <fieldPermissions>
24        <editable>true</editable>
25        <field>Job_Request__c.Salary__c</field>
26        <readable>true</readable>
27    </fieldPermissions>
28    <pageAccesses>
29        <apexPage>Job_Request_Web_Form</apexPage>
30        <enabled>true</enabled>
31    </pageAccesses>
32    <classAccesses>
33      <apexClass>Send_Email_Confirmation</apexClass>
34      <enabled>true</enabled>
35    </classAccesses>
36    <tabSettings>
37        <tab>Job_Request__c</tab>
38        <visibility>Available</visibility>
39    </tabSettings>
40    <recordTypeVisibilities>
41        <recordType>Recruiting.DevManager</recordType>
42        <visible>true</visible>
43    </recordTypeVisibilities>
44</PermissionSet>

The following is an example package.xml manifest used to retrieve the PermissionSet metadata for an organization. When you retrieve permission sets, you should 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.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>Job_Request__c</members>
5        <name>CustomTab</name>
6    </types>
7    <types>
8        <members>Job_Request__c</members>
9        <name>CustomObject</name>
10    </types>
11    <types>
12        <members>JobApps__Recruiting</members>
13        <name>CustomApplication</name>
14    </types>
15    <types>
16        <members>Recruiting.DevManager</members>
17        <name>RecordType</name>
18    </types>
19    <types>
20        <members>*</members>
21        <name>PermissionSet</name>
22    </types>
23    <version>37.0</version>
24</Package>

Metadata API Developer Guide