Profile

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.

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

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

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

ProfileFieldLevelSecurity represents the field level security for users assigned to a profile.

Field Name Field Type Description
editable boolean Required. Indicates whether this field is editable (true) or not (false).
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.

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.

ProfileLoginIpRange

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.

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 the 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 based on their profiles.

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:
  • Hidden
  • DefaultOff
  • DefaultOn

For more information, see “Setting Tab Visibility” in the Salesforce online help.

Java Sample

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();
  }
}

Declarative Metadata Sample Definition

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>

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. 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>
© Copyright 2000–2012 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.