Represents a user profile. A profile defines a user's permission to perform different functions within Salesforce. For more information, see “User Profiles Overview” in the Salesforce online help. It extends the Metadata metadata type and inherits its fullName field.
The file suffix is .profile. There is one file for each profile, stored in the profiles folder in the corresponding package directory.
The contents of a profile returned by the Metadata API depends on the contents 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:
| Field Name | Field Type | Description |
|---|---|---|
| applicationVisibilities | ProfileApplicationVisibility[] | Indicates which applications are visible to users assigned to this profile. |
| classAccesses | ProfileApexClassAccess[] | Indicates which top-level Apex classes have methods that users assigned to this profile can execute. |
| fieldLevelSecurities | ProfileFieldLevelSecurity[] | Indicates which fields are visible to a user assigned to this profile, and the kind of access available (editable or hidden). This field is available in API version 22.0 and earlier. |
| fieldPermissions | ProfileFieldLevelSecurity[] | Indicates which fields are visible to a user assigned to this profile, and the kind of access available (editable or readable). This field is available in API version 23.0 and later. |
| fullName | string | The
name can only contain characters, letters, and the underscore (_)
character, must start with a letter, and cannot end with an underscore
or contain two consecutive underscore characters.
Inherited from the Metadata component, this field is not defined in the WSDL for this component. It must be specified when creating, updating, or deleting. See create() to see an example of this field specified for a call. |
| layoutAssignments | ProfileLayoutAssignments[] | Indicates which layout to use for this profile. |
| loginIpRanges | ProfileLoginIpRange[] | The list of IP address
ranges from which users with a particular profile can log in.
This field is available in API version 17.0 and later. |
| objectPermissions | ProfileObjectPermissions[] | Indicates which objects are accessible to a user assigned to this profile, and the kind of access available (create, read, edit, delete). |
| pageAccesses | ProfileApexPageAccess[] | Indicates which Visualforce pages that users assigned to this profile can execute. |
| recordTypeVisibilities | ProfileRecordTypeVisibility[] | Indicates the visibility of record types for users assigned to this profile. |
| tabVisibilities | ProfileTabVisibility[] | Indicates which record types are visible to a user assigned to this profile, and therefore which tabs within an application are visible. |
| userLicense | string | The User License for the profile. A user license entitles a user to different functionality
within Salesforce and
determines which profiles and permission sets are available to the
user.
This field is available in API version 17.0 and later. |
ProfileApplicationVisibility determines if an application is visible to a user assigned to this profile.
| Field Name | Field Type | Description |
|---|---|---|
| application | string | Required. The name of the application. |
| default | boolean | Required. Indicates whether the application is the default application (true) or not (false). Only one application per profile can be set to true. |
| visible | boolean | Required. Indicates whether this application is visible to users assigned to this profile (true) or not (false). |
ProfileApexClassAccess determines which top-level Apex classes have methods that users assigned to this profile can execute.
| Field Name | Field Type | Description |
|---|---|---|
| apexClass | string | Required. The Apex class name. |
| enabled | boolean | Required. Indicates whether users assigned to this profile can execute methods in the top-level class (true) or not (false). |
ProfileFieldLevelSecurity represents the field level security for users assigned to a profile.
ProfileLayoutAssignments determines which layout to use for a profile and a given entity.
| Field Name | Field Type | Description |
|---|---|---|
| layout | string | Required. Indicates the layout for this particular entity. |
| recordType | string | This field is optional. If the recordType of the record matches a layout assignment rule, it will use the specified layout. |
ProfileLoginIpRange IP defines an IP address ranges from which users with a particular profile can log in.
| Field Name | Field Type | Description |
|---|---|---|
| endAddress | string | Required. The end IP address for the range. |
| startAddress | string | Required. The start IP address for the range. |
| Field Name | Field Type | Description |
|---|---|---|
| allowCreate | boolean | Indicates whether the object referenced by the object field can be created by the users assigned to
this profile (true) or not (false). This field is named revokeCreate before version 14.0 and the logic is reversed. The field name change and the update from true to false and vice versa is automatically handled between versions and does not require any manual editing of existing XML component files.The field name change and the update from true to false and vice versa is automatically handled between versions and does not require any manual editing of existing XML component files. |
| allowDelete | boolean | Indicates whether the object referenced by the object field can be deleted by the users assigned to
this profile (true) or not (false). This field is named revokeDelete before version 14.0 and the logic is reversed. The field name change and the update from true to false and vice versa is automatically handled between versions and does not require any manual editing of existing XML component files. |
| allowEdit | boolean | Indicates whether the object referenced by the object field can be edited by the users assigned to this
profile (true) or not (false). This field is named revokeEdit before version 14.0 and the logic is reversed. The field name change and the update from true to false and vice versa is automatically handled between versions and does not require any manual editing of existing XML component files. |
| allowRead | boolean | Indicates whether the object referenced by the object field can be seen by the users assigned to this
profile (true) or not (false). This field is named revokeRead before version 14.0 and the logic is reversed. The field name change and the update from true to false and vice versa is automatically handled between versions and does not require any manual editing of existing XML component files. |
| modifyAllRecords | boolean | Indicates whether the object referenced by the object field can be read, edited, or deleted by the users assigned to this profile (true) or not (false), regardless of the sharing settings for the object. This is equivalent to the “Modify All Data” user permission limited to the individual object level. This is a new field in API version 15.0. |
| object | string | Required. The name of the object whose permissions are altered by this profile, for example, MyCustomObject__c. |
| viewAllRecords | boolean | Indicates whether the object referenced by the object field can be read by the users assigned to this profile (true) or not (false), regardless of the sharing settings for the object. This includes private records (records with no parent object). This is equivalent to the “View All Data” user permission limited to the individual object level. This is a new field in API version 15.0. |
ProfileApexPageAccess determines which Visualforce pages that users assigned to this profile can execute.
| Field Name | Field Type | Description |
|---|---|---|
| apexPage | string | Required. The Visualforce page name. |
| enabled | boolean | Required. Indicates whether users assigned to this profile can execute the Visualforce page (true) or not (false). |
ProfileRecordTypeVisibility represents the visibility of record types for this profile. Record types allow you to offer different business processes, picklist values, and page layouts to different users based on their profiles.
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.
| Field Name | Field Type | Description |
|---|---|---|
| tab | string | Required. The name of the tab. |
| visibility | TabVisibility (enumeration of type string) | Required. Indicates the visibility of the tab. Valid values
are:
For more information, see “Setting Tab Visibility” in the Salesforce online help. |
The following sample uses picklists, profiles, and record types:
public void profileSample() { try { // Create an expense report record, tab and application... CustomObject expenseRecord = new CustomObject(); expenseRecord.setFullName("ExpenseReport__c"); expenseRecord.setLabel("Expense Report"); expenseRecord.setPluralLabel("Expense Reports"); expenseRecord.setDeploymentStatus(DeploymentStatus.Deployed); expenseRecord.setSharingModel(SharingModel.ReadWrite); CustomField nameField = new CustomField(); nameField.setType(FieldType.AutoNumber); nameField.setLabel("Expense Report Number"); nameField.setDisplayFormat("ER-{0000}"); expenseRecord.setNameField(nameField); AsyncResult[] arsExpenseRecord = metadataConnection.create(new Metadata[] {expenseRecord}); Picklist expenseStatus = new Picklist(); PicklistValue unsubmitted = new PicklistValue(); unsubmitted.setFullName("Unsubmitted"); PicklistValue submitted = new PicklistValue(); submitted.setFullName("Submitted"); PicklistValue approved = new PicklistValue(); approved.setFullName("Approved"); PicklistValue rejected = new PicklistValue(); rejected.setFullName("Rejected"); expenseStatus.setPicklistValues(new PicklistValue[] { unsubmitted, submitted, approved, rejected} ); CustomField expenseStatusField = new CustomField(); expenseStatusField.setFullName( "ExpenseReport__c.ExpenseStatus__c" ); expenseStatusField.setLabel("Expense Report Status"); expenseStatusField.setType(FieldType.Picklist); expenseStatusField.setPicklist(expenseStatus); AsyncResult[] arsStatusField = metadataConnection.create(new Metadata[] {expenseStatusField}); CustomTab expenseTab = new CustomTab(); expenseTab.setFullName("ExpenseReport__c"); expenseTab.setMotif("Custom70: Handsaw"); expenseTab.setCustomObject(true); AsyncResult[] arsTab = metadataConnection.create(new Metadata[] {expenseTab}); CustomApplication application = new CustomApplication(); application.setFullName("ExpenseForce"); application.setTab(new String[] {expenseTab.getFullName()}); AsyncResult[] arsApp = metadataConnection.create(new Metadata[] {application}); // Employees and managers have the same app visibility... ProfileApplicationVisibility appVisibility = new ProfileApplicationVisibility(); appVisibility.setApplication("ExpenseForce"); appVisibility.setVisible(true); Profile employee = new Profile(); employee.setFullName("Employee"); employee.setApplicationVisibilities( new ProfileApplicationVisibility[] {appVisibility} ); AsyncResult[] arsProfileEmp = metadataConnection.create(new Metadata[] {employee}); Profile manager = new Profile(); manager.setFullName("Manager"); manager.setApplicationVisibilities( new ProfileApplicationVisibility[] {appVisibility} ); AsyncResult[] arsProfileMgr = metadataConnection.create(new Metadata[] {manager}); // But employees and managers have different access // to the state of the expense sheet RecordType edit = new RecordType(); edit.setFullName("ExpenseReport__c.Edit"); RecordTypePicklistValue editStatuses = new RecordTypePicklistValue(); editStatuses.setPicklist("ExpenseStatus__c"); editStatuses.setValues(new PicklistValue[] {unsubmitted, submitted}); edit.setPicklistValues(new RecordTypePicklistValue[] {editStatuses}); AsyncResult[] arsRecTypeEdit = metadataConnection.create(new Metadata[] {edit}); RecordType approve = new RecordType(); approve.setFullName("ExpenseReport__c.Approve"); RecordTypePicklistValue approveStatuses = new RecordTypePicklistValue(); approveStatuses.setPicklist("ExpenseStatus__c"); approveStatuses.setValues(new PicklistValue[] {approved, rejected}); approve.setPicklistValues(new RecordTypePicklistValue[] {approveStatuses}); AsyncResult[] arsRecTypeApp = metadataConnection.create(new Metadata[] {approve}); } catch (ConnectionException ce) { ce.printStackTrace(); } }
The following is the definition of the standard profile in an organization with one custom object, TestWeblinks__c and one record type, My First Recordtype:
<?xml version="1.0" encoding="UTF-8"?> <Profile xmlns="http://soap.sforce.com/2006/04/metadata"> <applicationVisibilities> <application>Myriad Publishing</application> <default>false</default> <visible>true</visible> </applicationVisibilities> <objectPermissions> <object>TestWeblinks__c</object> </objectPermissions> <recordTypeVisibilities> <default>true</default> <recordType>TestWeblinks__c.My First Recordtype</recordType> <visible>true</visible> </recordTypeVisibilities> <tabVisibilities> <tab>Myriad Publications</tab> <visibility>DefaultOn</visibility> </tabVisibilities> </Profile>
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. 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.
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="http://soap.sforce.com/2006/04/metadata"> <types> <members>*</members> <name>CustomObject</name> </types> <types> <members>*</members> <name>Profile</name> </types> <version>24.0</version> </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. For more information about profiles, see “User Profiles Overview” in the Salesforce online help.
The 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.
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="http://soap.sforce.com/2006/04/metadata"> <types> <members>Account</members> <name>CustomObject</name> </types> <types> <members>*</members> <name>Profile</name> </types> <version>24.0</version> </Package>
The final package.xml file allows you to return profile permissions for the MyCustomField__c custom field in the Account object.
<?xml version="1.0" encoding="UTF-8"?> <Package xmlns="http://soap.sforce.com/2006/04/metadata"> <types> <members>Account.MyCustomField__c</members> <name>CustomField</name> </types> <types> <members>*</members> <name>Profile</name> </types> <version>24.0</version> </Package>