Attribute metadata

Entities include a collection of attributes that represent the data that can be included within each record. Developers need to understand the different types of attributes and how to work with them.

More information: Introduction to entity attributes

Attribute names

Like entities, each attribute has a unique name defined when it is created. This name is presented in several ways:

Name Description
SchemaName Typically, a Pascal cased version of the logical name. i.e. AccountNumber
LogicalName All lower-case name. i.e. accountnumber

When you create a custom attribute, the name you choose will be prepended with the customization prefix value of the solution publisher associated with the solution that the attribute was created within.

You cannot change the names of an attribute after it is created.

Each attribute also has two properties that can display localized values. These are the values that are used to refer to the attributes in an app.

Name Description
DisplayName Typically, the same as the schema name, but can include spaces. i.e. Account Number
Description A short sentence describing the attribute or providing guidance to the user. i.e. Type an ID number or code for the account to quickly search and identify the account in system views.
In model-driven apps, this information will appear when users hover over the field for this attribute in a form.

These are the localizable values that are used to refer to the attributes in an app. These values can be changed at any time. To add or edit localized values see Common Data Service for Apps Customization Guide: Translate customized entity and field text into other languages.

Attribute types

The AttributeTypeName property describes the type of an attribute. This property contains a value of type AttributeTypeDisplayName which provides a label for each the different types of attributes that exist.

Note

Don't be confused by the AttributeType property. The values in this older property are mostly aligned with AttributeTypeName except that it shows ImageType attributes as Virtual. You should refer to the AttributeTypeName property rather than the AttributeType property.

In the following table:

  • These types are grouped by category for comparison.
  • For each AttributeTypeDisplayName value, the corresponding .NET assembly AttributeMetadata derived class is included where available. There is not a 1:1 relationship between these types and the AttributeTypeDisplayName label.
  • Those attribute types that can be created as custom attributes include the corresponding label displayed in the UI.
Category AttributeTypeDisplayName/
AttributeMetadata Type
Can Create/
Label
Description
Categorization BooleanType
BooleanAttributeMetadata
Yes
Two Options
Contains the selected option value from two options that usually indicate a true or false value.
More information: Option Sets
Categorization EntityNameType
EntityNameAttributeMetadata
No Contains an option value that corresponds to an entity in the system. For internal use only.
Categorization MultiSelectPicklistType
MultiSelectPicklistAttributeMetadata
Yes
MultiSelect Option Set
Contains multiple selected option values where multiple options can be selected.
More information:
Option Sets
Multi-Select Picklist attributes
Categorization PicklistType
PicklistAttributeMetadata
Yes
Option Set
Contains the selected option value where one option can be selected.
More information: Option Sets
Categorization StateType
StateAttributeMetadata
No Contains the option value that describes the status of an entity record.
More information: Option Sets
Categorization StatusType
StatusAttributeMetadata
No Contains the option value that describes the reason for the status of an entity record.
More information: Option Sets
Collection CalendarRulesType No Contains a collection of CalendarRules entity records.
There are no attributes that use this type. When generating a proxy, the code generation tool will create two simulated attributes that are not present in the metadata. These attributes represent a view of the calendar rules records associated in a one-to-many relationship to the entity record.
Collection PartyListType No Contains a collection of ActivityParty entity records.
More information: ActivityParty entity
Date and Time DateTimeType
DateTimeAttributeMetadata
Yes
Date and Time
Contains a date and time value.
All date and time attributes support values as early as 1/1/1753 12:00 AM.
Image ImageType
ImageAttributeMetadata
Yes
Image
Contains data to support retrieving image data for an entity record.
More information: Entity Images
Managed Property ManagedPropertyType
ManagedPropertyAttributeMetadata
No Contains data that describe whether the solution component stored in the entity record can be customized when included in a managed solution.
More information: Managed Properties
Quantity BigIntType
BigIntAttributeMetadata
No Contains a BigInt value. For internal use only.
Quantity DecimalType
DecimalAttributeMetadata
Yes
Decimal Number
Contains a Decimal value. The Precision property sets the level of precision.
Quantity DoubleType
DoubleAttributeMetadata
Yes
Floating Point Number
Contains a Double value. The Precision property sets the level of precision.
Quantity IntegerType
IntegerAttributeMetadata
Yes
Whole Number
Contains an Int value
Quantity MoneyType
MoneyAttributeMetadata
Yes
Currency
Contains a Decimal value. The PrecisionSource property determines where the level of precision is set.
0 : The Precision property
1 : The Organization.PricingDecimalPrecision attribute
2 : The TransactionCurrency.CurrencyPrecision attribute in the entity record
Reference CustomerType
LookupAttributeMetadata
Yes
Customer
Contains a reference to either an account or contact entity record.
Reference LookupType
LookupAttributeMetadata
Yes
Lookup
Contains a reference to an entity record. The logical names of the valid records are usually stored in the Targets property of the attribute.
Reference OwnerType
LookupAttributeMetadata
No Contains a reference to either a user or team entity record.
String MemoType
MemoAttributeMetadata
Yes
Multiple Lines of Text
Contains a string value intended to be displayed in a multi-line textbox.
String StringType
StringAttributeMetadata
Yes
Single Line of Text
Contains a string value intended to be displayed in a single-line textbox.
Unique identifier UniqueidentifierType
UniqueIdentifierAttributeMetadata
No Contains a GUID unique identifier value.
Virtual VirtualType No These attributes cannot be used in code and can generally be ignored.

Supported operations and form usage for attributes

Each attribute includes boolean properties that describe the kinds of operations it can participate in and how it can be in a form.

Property Description
IsRequiredForForm Whether the attribute must be included as a field in a form.
IsValidForCreate Whether the attribute value can be set in a create operation.
IsValidForForm Whether the attribute can be included as a field in a form.
IsValidForRead Whether the attribute value can be retrieved.
IsValidForUpdate Whether the attribute value can be set in an update operation.

If you try to set a value in a create or update operation for an attribute that is not valid for that operation, the value will be ignored. If you try to retrieve an attribute that is not valid for read, a null value will be returned.

Attribute requirement level

The RequiredLevel property is a Boolean managed property that describes if an attribute value is required.

This property can have the following values set:

Name Value UI Label Description
None 0 Optional No requirements are specified.
SystemRequired 1 System Required The attribute is required to have a value.
ApplicationRequired 2 Business Required The attribute is required by the business to have a value.
Recommended 3 Business Recommended It is recommended that the attribute has a value.

Common Data Service for Apps only enforces the SystemRequired option for attributes created by the system. Custom attributes cannot be set to use the SystemRequired option.

Model-driven apps will enforce the ApplicationRequired option and use a different presentation for the Recommended option. Creators of custom clients may use this information to require similar validation or presentation options.

Because this is a managed property, as a publisher of a managed solution you can decide whether consumers of your solution are able to change these settings on attributes in your solution.

More information: Managed Properties

Rollup and calculated attributes

Calculated and rollup attributes free the user from having to manually perform calculations and focus on their work. System administrators can define a field to contain the value of many common calculations without having to work with a developer. Developers can also leverage the platform capabilities to perform these calculations rather than within their own code.

More information:

Attribute format

The format values for attributes controls how it is displayed in model-driven apps. Developer of custom apps may use this information to create similar experiences.

Integer formats

Use the Format property with integer attributes to display alternate user experiences for this type.

Option Description
None Displays a text box to edit a number value
Duration Displays a drop-down list that contains time intervals. A user can select a value from the list or type an integer value that represents the number of minutes.
TimeZone Displays a drop-down list that contains a list of time zones.
Language Displays a drop-down list that contains a list of languages that have been enabled for the organization. If no other languages have been enabled, the base language will be the only option. The value saved is the LCID value for the language.

String formats

Use the FormatName property with string attributes to set values from the StringFormatName Class to control how the string attribute is formatted.

Name Description
Email The form field will validate the text value as an e-mail address and create a mailto link in the field.
PhoneNumber The form field will contain a link to initiate a phone call by using Skype.
PhoneticGuide For internal use only.
Text The form will display a text box.
TextArea The form will display a text area field.
TickerSymbol The form will display a link that will open to display a quote for the stock ticker symbol.
URL The form will display a link to open the URL.
VersionNumber For internal use only.

Date and time formats

The DateTimeBehavior property to controls the behavior for Date and Time attributes. There are three options:

Option Short Description
UserLocal Stores the date and time value as UTC value in the system.
DateOnly Stores the actual date value with the time value as 12:00 AM (00:00:00) in the system.
TimeZoneIndependent Stores the actual date and time values in the system regardless of the user time zone.

Use the Format property control how the value is to be displayed in a model-driven app regardless of the DateTimeBehavior.

Option Description
DateAndTime Display the full date and time
DateOnly Display just the date.

More information: Behavior and format of the date and time attribute

Auto-number attributes

You can add an auto-number attribute for any entity. Currently, you can add the attribute programmatically. There is no user interface to add this type of attribute. More information: Create auto-number attributes

Option sets

Those attributes which display a set of options can reference a set of options defined by the attribute or they can reference a separate set of options that can be shared by more than one attribute. This is particularly useful when values in one attribute also apply to other attributes. By referencing a common set of options, the options can be maintained in one place. Those option sets that can be shared are global option sets. Those defined within the attribute are local option sets.

Retrieve options data

The organization service provides request classes you can use to retrieve the options used by an attribute.

Use the organization service to retrieve options

Each of the attributes with options inherit from EnumAttributeMetadata and include an OptionSet Property. This property contains the OptionSetMetadata that includes the options within the Options property.

With the organization service you can use the following messages to retrieve information about optionsets:

Request Class Description
RetrieveAllOptionSetsRequest Retrieves data about all global optionsets
RetrieveAttributeRequest Retrieves data about an attribute including any local optionsets
RetrieveMetadataChangesRequest Retrieves metadata based on a query that can include local optionsets
More information: Retrieve and detect changes to metadata
RetrieveOptionSetRequest Retrieves data about a global option set.

More information:

Use the Web API to retrieve options

The Web API provides a RESTful style for querying option values. You can retreive local or global options by retrieving the attributes within an entity. The following example returns the OptionSetMetadata for the options included in the Account.AccountCategoryCode property.

GET <organization url>/api/data/v9.0/EntityDefinitions(LogicalName='account')/Attributes(LogicalName='accountcategorycode')/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet

With the Web API you can also use the RetrieveMetadataChanges Function.

More information: Query metadata using the Web API > Querying EntityMetadata attributes

Attribute mapping

When you create a new entity record in the context of an existing entity record, you can automatically transfer certain values from the existing entity record as default values for the new entity record. This streamlines data entry for people using model-driven apps. Application users see the mapped values and can edit them before saving the entity.

For developers creating custom clients, the same behavior can be achieved by using the InitializeFrom message (Organization service InitializeFromRequest Class or Web API InitializeFrom Function) to get the entity data with the configured default values set.

More information

See also

Common Data Service for Apps entities