Profile

Represents a user profile. A profile defines a user's permission to perform different functions within Salesforce. It 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:

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

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:

Field Name Field Type Description
applicationVisibilities ProfileApplicationVisibility[] Indicates which apps are visible to users assigned to this profile. In API version 29.0 and earlier, this field supports custom apps only. In API version 30.0 and later, this field supports both standard and custom apps.
classAccesses ProfileApexClassAccess[] Indicates which top-level Apex classes have methods that users assigned to this profile can execute.
custom boolean Indicates whether the profile is a custom (true) or standard (false) profile. Available in API version 30.0 and later.
customPermissions ProfileCustomPermissions[] Indicates which custom permissions are available to users assigned to this profile. Available in API version 31.0 and later.
description string The profile description. Limit: 255 characters. Available in API version 30.0 and later.
externalDataSourceAccesses ProfileExternalDataSourceAccess[] Indicates which data sources with identity type of Per User are available to users assigned to this profile. Available in API version 27.0 and later.
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.
loginHours ProfileLoginHours[] Indicates the hours within which a user with this profile may log in. If not specified, the profile doesn’t restrict a user’s login hours.

This field is available in API version 25.0 and later.

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, and so on). In API version 28.0 and later, this field is only retrieved when allowRead is true.
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. In API version 29.0 and later, this field is not retrieved or deployed for inactive record types.
tabVisibilities ProfileTabVisibility[] Indicates which record types are visible to a user assigned to this profile, and therefore which tabs within an app are visible.
userLicense string The User License for the profile. A user license determines the baseline of features that the user can access. Every user must have exactly one user license.

This field is available in API version 17.0 and later.

userPermissions ProfileUserPermission[] Specifies a user permission (such as “API Enabled”) and whether it’s enabled for this profile. This field retrieves only enabled user permissions. Available in API version 29.0 and later.

ProfileApplicationVisibility

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

Field Name Field Type Description
application string Required. The name of the app.
default boolean Required. Indicates whether the app is the default app (true) or not (false). Only one app per profile can be set to true.
visible boolean Required. Indicates whether this app is visible to users assigned to this profile (true) or not (false).

ProfileApexClassAccess

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).

ProfileCustomPermissions

ProfileCustomPermissions represents the custom permissions access for users assigned to a profile. 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.

ProfileExternalDataSourceAccess

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

Field Name 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.

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.

Field Name Field Type Description
editable boolean Required. Indicates whether this field is editable (true) or not (false).

In API version 30.0 and later, when deploying a new custom field, this field is false by default.

field string Required. Indicates the name of the field.
hidden boolean Indicates whether this field is hidden (true) or not (false). This field is available in API version 22.0 and earlier.

For portal profiles, this is set to true by default in API version 19.0 and later.

readable boolean Indicates whether this field is readable (true) or not (false). This field is available in API version 23.0 and later. It replaces the hidden field.

In API version 30.0 and later, when deploying a new custom field, this field is false by default.

For portal profiles, this is set to false by default.

ProfileLayoutAssignments

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.

ProfileLoginHours

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

Field Name Field Type Description
weekdayStart string Specifies the earliest time on that day that a user with this profile may log in. If a start time for a particular day is specified, an end time for that day must be specified as well. Start can’t be greater than end for a particular day.
  • Valid values for weekday: monday, tuesday, wednesday, thursday, friday, saturday, or sunday. For example, mondayStart indicates the beginning of the login period for Monday.
  • Valid values for Start: the number of minutes since midnight. Must be evenly divisible by 60 (full hours). For example, 300 is 5:00 a.m.
weekdayEnd string Specifies the time on that day by which a user with this profile must log out.
  • Valid values for weekday: monday, tuesday, wednesday, thursday, friday, saturday, or sunday. For example, mondayEnd indicates the close of the login period for Monday.
  • Valid values for End: the number of minutes since midnight. Must be evenly divisible by 60 (full hours). For example, 1020 is 5:00 p.m.

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.

Field Name Field Type Description
description string Use this field to identify the purpose of the range, such as which part of a network corresponds to this range. This field is available in API version 31.0 and later.
endAddress string Required. The end IP address for the range.
startAddress string Required. The start IP address for the range.

ProfileObjectPermissions

ProfileObjectPermissions represents a user's access to objects.
Note
In API version 18.0 and later, these permissions are disabled in new custom objects for any profiles in which “View All Data” or “Modify All Data” is disabled.
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.
Note
This field is not available for all objects. Refer to the profile in the user interface to determine which objects currently support these permissions. Profiles with "Modify All Data" ignore modifyAllRecords entries in Metadata API and don't return an error if "Modify All Data" is enabled on the profile.
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.
Note
This field is not available for all objects. Refer to the profile in the user interface to determine which objects currently support these permissions. Profiles with "View All Data" ignore viewAllRecords entries in the Metadata API and don't return an error if "View All Data" is enabled on the profile.

ProfileApexPageAccess

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

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.

Field Name Field Type Description
default boolean Required. Indicates whether the record type is the default for this pair of profile and object (true) or not (false). Only one default is allowed per object.
personAccountDefault boolean Indicates whether the record type is the default person account record type for this pair of profile and object (true) or not (false). Only one person account record type default is allowed per object. This field is only relevant for record types for account or contact objects.

A person account is an individual consumer with whom you do business, such as a financial services client, an online shopper, or a vacation traveler. Person accounts are applicable to organizations that operate on a business-to-consumer model as opposed to a business-to-business model.

For more information about person accounts, see “What is a Person Account?” in the Salesforce online help. Person accounts are not enabled by default in Salesforce. To request person accounts, contact salesforce.com.

recordType string Required. The record type name, for example Account.MyRecordType.
visible boolean Required. Indicates whether this record type is visible to users assigned to this profile (true) or not (false).

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.

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:
  • DefaultOff—The tab is available on the All Tabs page. Individual users can customize their display to make the tab visible in any app.
  • DefaultOn—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.
  • Hidden—The tab isn’t available on the All Tabs page or visible in any apps.

ProfileUserPermission

ProfileUserPermission represents an app or system permission for a profile. 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 permission name.

Java Sample

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

public void profileSample() {
  try {
    // Create an expense report record, tab and app...
    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();
  }
}

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:

<?xml version="1.0" encoding="UTF-8"?>
<Profile xmlns="http://soap.sforce.com/2006/04/metadata">
    <applicationVisibilities>
        <application>PubApps__Myriad_Publishing</application>
        <default>false</default>
        <visible>true</visible>
    </applicationVisibilities>
    <custom>true</custom>
    <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>
    <userPermissions>
        <enabled>true</enabled>
        <name>APIEnabled</name>
    </userpermissions>
</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.

<?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>32.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.

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>32.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>32.0</version>
</Package>
© Copyright 2000–2014 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.