CustomField

Represents the metadata associated with a custom field. Use this metadata type to create, update, or delete custom field definitions. It extends the Metadata metadata type and inherits its fullName field. You can also use this metadata type to work with customizations of standard picklist fields, such as the Industry field for accounts.

You must specify the full name whenever you create or update a custom field. For example, a custom field on a custom object:

MyCustomObject__c.MyCustomField__c

Another example, a custom field on a standard object:

Account.MyAcctCustomField__c

Declarative Metadata File Suffix and Directory Location

Custom fields are defined as part of the custom object or standard object definition. See CustomObject for more information.

Note
Retrieving a component of this metadata type in a project makes the component appear in the Profile component as well.

Retrieving Custom Fields on Custom or Standard Objects

When you retrieve a custom or standard object, you return everything associated with the object. However, you can also retrieve only the custom fields for an object by explicitly naming the object and fields in package.xml. The following definition in package.xml will create the files objects/MyCustomObject__c.object and objects/Account.object__c.object, each containing one custom field definition.

<types>
  <members>MyCustomObject__c.MyCustomField__c</members>
  <members>Account.MyCustomAccountField__c</members>
  <name>CustomField</name>
</types>

Version

Custom fields are available in API version 10.0 and later.

Fields

Unless otherwise noted, all fields are createable, filterable, and nillable.

Field Name Field Type Description
caseSensitive boolean Indicates whether the field is case sensitive (true) or not (false).
defaultValue string If specified, represents the default value of the field.
deleteConstraint DeleteConstraint (enumeration of type string) Provides deletion options for lookup relationships. Valid values are:
SetNull
This is the default. If the lookup record is deleted, the lookup field is cleared.
Restrict
Prevents the record from being deleted if it’s in a lookup relationship.
Cascade
Deletes the lookup record as well as associated lookup fields.

For more information on lookup relationships, see “Overview of Object Relationships” in the Salesforce online help.
deprecated boolean Reserved for future use.
description string Description of the field.
displayFormat string The display format.
displayLocationInDecimal boolean Indicates how the value of a Geolocation custom field appears in the user interface. If true, the geolocation appears in decimal notation. If false, the geolocation appears as degrees, minutes, and seconds.
externalId boolean Indicates whether the field is an external ID field (true) or not (false).
formula string If specified, represents a formula on the field.
formulaTreatBlankAs TreatBlanksAs (enumeration of type string) Indicates how to treat blanks in a formula. Valid values are BlankAsBlank and BlankAsZero.
fullName string Inherited from Metadata, this field is not defined in the WSDL for this metadata type. It must be specified when creating, updating, or deleting. See create() to see an example of this field specified for a call.

This value cannot be null.
indexed boolean Indicates if the field is indexed. If this field is unique or the externalId is set true, the isIndexed value is set to true. This field has been deprecated as of version 14.0 and is only provided for backward compatibility.
inlineHelpText string Represents the content of field-level help. For more information, see “Defining Field-Level Help” in the Salesforce online help.
reparentableMasterDetail boolean Indicates whether the child records in a master-detail relationship on a custom object can be reparented to different parent records. The default value is false.

This field is available in API version 25.0 and later.
label string Label for the field. You cannot update the label for standard picklist fields, such as the Industry field for accounts.
length int Length of the field.
maskChar EncryptedFieldMaskChar (enumeration of type string) For encrypted fields, specifies the character to be used as a mask. Valid values are enumerated in EncryptedFieldMaskChar.

For more information on encrypted fields, see “About Encrypted Custom Fields” in the Salesforce online help.
maskType EncryptedFieldMaskType (enumeration of type string) For encrypted text fields, specifies the format of the masked and unmasked characters in the field. Valid values are enumerated in EncryptedFieldMaskType For more information on encrypted fields, see “About Encrypted Custom Fields” in the Salesforce online help.
picklist Picklist If specified, the field is a picklist, and this field enumerates the picklist values and labels.
populateExistingRows boolean Indicates whether existing rows will be populated (true) or not (false).
precision int The precision for number values. Precision is the number of digits in a number. For example, the number 256.99 has a precision of 5.
referenceTo string If specified, indicates a reference this field has to another object.
relationshipLabel string Label for the relationship.
relationshipName string If specified, indicates the value for one-to-many relationships. For example, in the object MyObject that had a relationship to YourObject, the relationship name might be YourObjects.
relationshipOrder int This field is valid for all master-detail relationships, but the value is only non-zero for junction objects. A junction object has two master-detail relationships, and is analogous to an association table in a many-to-many relationship. Junction objects must define one parent object as primary (0), the other as secondary (1). The definition of primary or secondary affects delete behavior and inheritance of look and feel, and record ownership for junction objects. For more information, see the Salesforce online help.

0 or 1 are the only valid values, and 0 is always the value for objects that are not junction objects.
required boolean Indicates whether the field requires a value on creation (true) or not (false).
scale int The scale for the field. Scale is the number of digits to the right of the decimal point in a number. For example, the number 256.99 has a scale of 2.
startingNumber int If specified, indicates the starting number for the field.
stripMarkup boolean Set to true to remove markup, or false to preserve markup. Used when converting a rich text area to a long text area.
summarizedField string Represents the field on the detail row that is being summarized. This field cannot be null unless the summaryOperation value is count.
summaryFilterItems FilterItem[] Represents the set of filter conditions for this field if it is a summary field. This field will be summed on the child if the filter conditions are met.
summaryForeignKey string Represents the master-detail field on the child that defines the relationship between the parent and the child.
summaryOperation SummaryOperations (enumeration of type string) Represents the sum operation to be performed. Valid values are enumerated in SummaryOperations.
trackFeedHistory boolean Indicates whether the field is enabled for feed tracking (true) or not (false). To set this field to true, the enableFeeds field on the associated CustomObject must also be true. For more information, see “Customizing Chatter Feed Tracking” in the Salesforce online help.

This field is available in API version 18.0 and later.
trackHistory boolean Indicates whether history tracking is enabled for the field (true) or not (false). For more information, see “Tracking Field History” in the Salesforce online help.
trueValueIndexed boolean This is only relevant for a checkbox field. If set, true values are built into the index. This field has been deprecated as of version 14.0 and is only provided for backward compatibility.
type FieldType Required. Indicates the field type for the field. Valid values are enumerated in FieldType.
unique boolean Indicates whether the field is unique (true) or not (false).
visibleLines int Indicates the number of lines displayed for the field.
writeRequiresMasterRead boolean Sets the minimum sharing access level required on the master record to create, edit, or delete child records. This field applies only to master-detail or junction object custom field types.
  • true - Allows users with “Read” access to the master record permission to create, edit, or delete child records. This setting makes sharing less restrictive.
  • false - Allows users with “Read/Write” access to the master record permission to create, edit, or delete child records. This setting is more restrictive than true, and is the default value.

For junction objects, the most restrictive access from the two parents is enforced. For example, if you set to true on both master-detail fields, but users have “Read” access to one master record and “Read/Write” access to the other master record, users won't be able to create, edit, or delete child records.

Custom fields use additional data types. For more information, see Metadata Field Types.

EncryptedFieldMaskChar

This field type is used in maskChar. It is a string with two valid values: asterisk or X. For more information on encrypted fields, see About Encrypted Custom Fields in the Salesforce online help.

EncryptedFieldMaskType

This field type is used in maskType. Valid values are:

all
All characters in the field are hidden. This option is equivalent to the Mask All Characters option in Salesforce.
creditCard
The first 12 characters are hidden and the last four display. This option is equivalent to the Credit Card Number option in Salesforce.
ssn
The first five characters are hidden and the last four display. This option is equivalent to the Social Security Number option in Salesforce.
lastFour
All characters are hidden but the last four display. This option is equivalent to the Last Four Characters Clear option in Salesforce.
sin
All characters are hidden but the last four display. This option is equivalent to the Social Insurance Number option in Salesforce.
nino
All characters are hidden. Salesforce automatically inserts spaces after each pair of characters if the field contains nine characters. This option is equivalent to the National Insurance Number option in Salesforce.

For more information on encrypted fields, see About Encrypted Custom Fields in the Salesforce online help.

FilterItem

Represents one entry in a set of filter criteria.

Field Field Type Description
field string Represents the field specified in the filter.
operation FilterOperation (enumeration of type string) Represents the filter operation for this filter item. Valid values are enumerated in FilterOperation.
value string Represents the value of the filter item being operated upon, for example, if the filter is my_number_field__c > 1, the value of value is 1.
valueField string Specifies if the final column in the filter contains a field or a field value.

Approval processes don't support valueField entries in filter criteria.

FilterOperation

This is an enumeration of type string that lists different filter operations. Valid values are:

SummaryOperations

Represents the type of a summaryOperation. Valid values are:

Declarative Metadata Sample Definition 

<?xml version="1.0" encoding="UTF-8"?>
<CustomObject xmlns="http://soap.sforce.com/2006/04/metadata">
....
<fields>
        <fullName>Comments__c</fullName>
        <description>add your comments about this object here</description>
        <inlineHelpText>This field contains comments made about this object</inlineHelpText>
        <label>Comments</label>
        <length>32000</length>
        <type>LongTextArea</type>
        <visibleLines>30</visibleLines>
    </fields>
....
</CustomObject>
See Also:
CustomObject
Picklist (Including Dependent Picklist)
Metadata
NamedFilter
© Copyright 2000–2013 salesforce.com, inc. All rights reserved.
Various trademarks held by their respective owners.