Profile

Declarative Metadata File Suffix and Directory Location

The file suffix is .profile. There is one file for each profile, stored in the profiles folder in the corresponding package directory.

Version

Profiles are available in API version 10.0 and later.

Fields

The content of a profile returned by Metadata API depends on the content requested in the RetrieveRequest message. For example, profiles only include field-level security for fields included in custom objects returned in the same RetrieveRequest as the profiles. The profile definition contains the following fields:

ProfileApplicationVisibility

ProfileApplicationVisibility determines whether an app is visible to a user assigned to this profile.

ProfileApexClassAccess

ProfileApexClassAccess determines which top-level Apex classes have methods that users assigned to this profile can execute.

ProfileCustomPermissions

ProfileCustomPermissions represents the custom permissions access for users assigned to a profile. Only enabled custom permissions are retrieved.

ProfileExternalDataSourceAccess

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

ProfileFieldLevelSecurity

ProfileFieldLevelSecurity represents the field level security for users assigned to a profile. In API version 30.0 and later, permissions for required fields can’t be retrieved or deployed.

ProfileLayoutAssignments

ProfileLayoutAssignments determines which layout to use for a profile and a given entity.

ProfileLoginHours

ProfileLoginHours restricts the days and times within which users with a particular profile can log in.

To delete login hour restrictions from a profile that previously had them, you must explicitly include an empty loginHours tag without any start or end times.

ProfileLoginIpRange

ProfileLoginIpRange IP defines an IP address ranges from which users with a particular profile can log in.

ProfileObjectPermissions

ProfileApexPageAccess

ProfileApexPageAccess determines which Visualforce pages that users assigned to this profile can execute.

ProfileRecordTypeVisibility

ProfileRecordTypeVisibility represents the visibility of record types for this profile. Record types let you offer different business processes, picklist values, and page layouts to different users.

ProfileTabVisibility

ProfileTabVisibility represents the visibility of tabs for this profile. For version 17.0 and later, ProfileTabVisibility supports visibility of tabs for standard objects. The manifest file must include the standard object corresponding to a standard tab to retrieve the tab visibility in a profile.

ProfileUserPermission

ProfileUserPermission represents an app or system permission for a profile. Use one of these elements for each permission.

Java Sample

The following sample uses picklists, profiles, record types, and a custom app:

1public void profileSample() {
2  try {
3    // Create an expense report record, tab and app...
4    CustomObject expenseRecord = new CustomObject();
5    expenseRecord.setFullName("ExpenseReport__c");
6    expenseRecord.setLabel("Expense Report");
7    expenseRecord.setPluralLabel("Expense Reports");
8    
9    expenseRecord.setDeploymentStatus(DeploymentStatus.Deployed);
10    expenseRecord.setSharingModel(SharingModel.ReadWrite);
11    
12    CustomField nameField = new CustomField();
13    nameField.setType(FieldType.AutoNumber);
14    nameField.setLabel("Expense Report Number");
15    nameField.setDisplayFormat("ER-{0000}");
16    expenseRecord.setNameField(nameField);
17    
18    AsyncResult[] arsExpenseRecord =
19        metadataConnection.create(new Metadata[] {expenseRecord});
20    
21    Picklist expenseStatus = new Picklist();
22    PicklistValue unsubmitted = new PicklistValue();
23    unsubmitted.setFullName("Unsubmitted");
24    PicklistValue submitted = new PicklistValue();
25    submitted.setFullName("Submitted");
26    PicklistValue approved = new PicklistValue();
27    approved.setFullName("Approved");
28    PicklistValue rejected = new PicklistValue();
29    rejected.setFullName("Rejected");
30    expenseStatus.setPicklistValues(new PicklistValue[] {
31        unsubmitted, submitted, approved, rejected}
32    );
33    
34    CustomField expenseStatusField = new CustomField();
35    expenseStatusField.setFullName(
36        "ExpenseReport__c.ExpenseStatus__c"
37    );
38    expenseStatusField.setLabel("Expense Report Status");
39    expenseStatusField.setType(FieldType.Picklist);
40    expenseStatusField.setPicklist(expenseStatus);
41    AsyncResult[] arsStatusField =
42        metadataConnection.create(new Metadata[] 
43            {expenseStatusField});
44    
45    CustomTab expenseTab = new CustomTab();
46    expenseTab.setFullName("ExpenseReport__c");
47    expenseTab.setMotif("Custom70: Handsaw");
48    expenseTab.setCustomObject(true);
49    AsyncResult[] arsTab =
50        metadataConnection.create(new Metadata[] {expenseTab});
51    
52    CustomApplication application = new CustomApplication();
53    application.setFullName("ExpenseForce");
54    application.setTab(new String[] {expenseTab.getFullName()});
55    AsyncResult[] arsApp =
56        metadataConnection.create(new Metadata[] {application});
57    
58    // Employees and managers have the same app visibility...
59    ProfileApplicationVisibility appVisibility =
60        new ProfileApplicationVisibility();
61    appVisibility.setApplication("ExpenseForce");
62    appVisibility.setVisible(true);
63    
64    Profile employee = new Profile(); 
65    employee.setFullName("Employee");
66    employee.setApplicationVisibilities(
67        new ProfileApplicationVisibility[] {appVisibility}
68    );
69    AsyncResult[] arsProfileEmp =
70    metadataConnection.create(new Metadata[] {employee});
71    
72    Profile manager = new Profile();
73    manager.setFullName("Manager");
74    manager.setApplicationVisibilities(
75        new ProfileApplicationVisibility[] {appVisibility}
76    );
77    AsyncResult[] arsProfileMgr =
78        metadataConnection.create(new Metadata[] {manager});
79    
80    // But employees and managers have different access
81    // to the state of the expense sheet
82    RecordType edit = new RecordType();
83    edit.setFullName("ExpenseReport__c.Edit");
84    RecordTypePicklistValue editStatuses =
85        new RecordTypePicklistValue();
86    editStatuses.setPicklist("ExpenseStatus__c");
87    editStatuses.setValues(new PicklistValue[] 
88        {unsubmitted, submitted});
89    edit.setPicklistValues(new RecordTypePicklistValue[] 
90        {editStatuses});
91    AsyncResult[] arsRecTypeEdit =
92        metadataConnection.create(new Metadata[] {edit});
93    
94    RecordType approve = new RecordType();
95    approve.setFullName("ExpenseReport__c.Approve");
96    RecordTypePicklistValue approveStatuses =
97        new RecordTypePicklistValue();
98    approveStatuses.setPicklist("ExpenseStatus__c");
99    approveStatuses.setValues(new PicklistValue[] 
100        {approved, rejected});
101    approve.setPicklistValues(new RecordTypePicklistValue[]
102        {approveStatuses});
103    AsyncResult[] arsRecTypeApp =
104        metadataConnection.create(new Metadata[] {approve});
105  } catch (ConnectionException ce) {
106    ce.printStackTrace();
107  }
108}

Declarative Metadata Sample Definition

The following is the definition of a profile in an organization with a custom app, custom object, record type, tab, and user permission:

1<?xml version="1.0" encoding="UTF-8"?>
2<Profile xmlns="http://soap.sforce.com/2006/04/metadata">
3    <applicationVisibilities>
4        <application>PubApps__Myriad_Publishing</application>
5        <default>false</default>
6        <visible>true</visible>
7    </applicationVisibilities>
8    <custom>true</custom>
9    <objectPermissions>
10        <object>TestWeblinks__c</object>
11    </objectPermissions>
12    <recordTypeVisibilities>
13        <default>true</default>
14        <recordType>TestWeblinks__c.My First Recordtype</recordType>
15        <visible>true</visible>
16    </recordTypeVisibilities>
17    <tabVisibilities>
18        <tab>Myriad Publications</tab>
19        <visibility>DefaultOn</visibility>
20    </tabVisibilities>
21    <userPermissions>
22        <enabled>true</enabled>
23        <name>APIEnabled</name>
24    </userpermissions>
25</Profile>

Usage

When you use the retrieve() call to get information about profiles in your organization, the returned .profile files only include security settings for the other metadata types referenced in the retrieve request (with the exception of user permissions, IP address ranges, and login hours, which are always retrieved). For example, the package.xml file below contains a types element that matches all custom objects, so the returned profiles contain object and field permissions for all custom objects in your organization, but do not include permissions for standard objects, such as Account, and standard fields.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>*</members>
5        <name>CustomObject</name>
6    </types>
7   <types>
8        <members>*</members>
9        <name>Profile</name>
10    </types>
11    <version>36.0</version>
12</Package>

The wildcard “*” on CustomObject does not match standard objects and this helps to avoid making unintended, high-impact profile changes. If you create a few custom objects in a Developer Edition organization, retrieve() the information, and subsequently deploy() the custom objects to your production organization, the profile and field-level security for all your standard objects, such as Account, and standard fields are not overwritten unless you explicitly create separate types elements for the standard objects or fields.

Metadata API intentionally makes it somewhat difficult to include standard fields in retrieve() calls in order to prevent unexpected profile changes. However, you can still retrieve and deploy profile permissions for custom and standard fields in standard objects, such as Account.

The next package.xml file allows you to return profile permissions for Account standard and custom fields. Note how the standard Account object is defined in a types element by specifying it as a member of a CustomObject type.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3    <types>
4        <members>Account</members>
5        <name>CustomObject</name>
6    </types>
7   <types>
8        <members>*</members>
9        <name>Profile</name>
10    </types>
11    <version>36.0</version>
12</Package>

The final package.xml file allows you to return profile permissions for the MyCustomField__c custom field in the Account object.

1<?xml version="1.0" encoding="UTF-8"?>
2<Package xmlns="http://soap.sforce.com/2006/04/metadata">
3   <types>
4        <members>Account.MyCustomField__c</members>
5        <name>CustomField</name>
6   </types>
7   <types>
8        <members>*</members>
9        <name>Profile</name>
10   </types>
11   <version>36.0</version>
12</Package>