Introduction to entity attributes in Microsoft Dynamics 365
Updated: November 29, 2016
Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Entities include a set 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. The metadata for attributes describes the valid operations and behaviors of different types of attributes. Several types of attributes can be grouped by common behaviors.
The specific experience developers will have depends on their style of development. More information: Entity programming (early bound vs. late bound vs. developer extensions).
 Note |
|---|
This topic includes references to many metadata properties. To view the entity metadata for your organization, install the Metadata Browser solution described in Browse the metadata for your organization. You can also view the metadata for an uncustomized organization in the Excel file called EntityMetadata.xlsx included in the top-level folder of the SDK download. |
Each attribute has metadata that describes the operations it supports. You need to be aware of the operations that are valid for the attributes you work with.
AttributeMetadata property | Description |
|---|---|
True if this attribute value is valid to be set when a record is created, otherwise false. | |
True if this attribute value can be retrieved, otherwise false. | |
True if this attribute value is valid to be set when a record is updated, otherwise false. |
Attributes are defined in metadata and the AttributeMetadata.AttributeTypeName property contains the value describing the type. The static AttributeTypeDisplayName members provide the list of possible types.
| Note |
|---|
The older AttributeType property contains data that is mostly aligned with AttributeTypeName, except that it shows ImageType attributes as Virtual. You should use the AttributeTypeName property rather than the AttributeType property. |
The following section groups the types of attributes into the following categories so that you can more easily compare them:
Each of the five attributes in this group inherit from a common EnumAttributeMetadata base class and use a pre-defined set of valid values to group records into categories.
Set Picklist, Status, and State attributes using an OptionSetValue with a Value property set to an integer that represents a valid option within the metadata.
Set Boolean attributes using a Boolean value, but recognize that this is a categorization limited to just two options.
EntityName attributes use a string value that is constrained to be a valid entity logical name in the organization.
Custom Picklist and Boolean attributes can be defined as calculated attributes. More information: Calculated attributes.
Metadata Type | AttributeTypeName Value | Description |
|---|---|---|
PicklistType | Valid values are set in the OptionMetadata.Value for that attribute defined within the OptionSetMetadata.Options. Within the customization tools in the application these attributes are called Option Set fields. | |
StatusType | These system attributes are generally named StatusCode. Valid values are set in the StatusOptionMetadata.Value for that attribute defined within the OptionSetMetadata.Options. The StatusOptionMetadata.State property for each option describes the valid value for the corresponding StateCode value. Before you set the StatusCode you should verify that it is valid for the current StateCode value. Use the SetStateRequest message to set the StatusCode and StateCode attribute values when you need to change the state of the record. These attributes may have further restrictions on which values can be set. The StatusOptionMetadata.TransitionData property may contain information on which options are allowed when the EntityMetadata.EnforceTransitions value is true. More information: Define custom state model transitions. | |
StateType | These system attributes are generally named StatusCode. Valid values are set in the StateOptionMetadata.Value for that attribute defined within the OptionSetMetadata.Options. StateCode is not valid for update. After the record is created, the StateCode can only be set using the SetStateRequest message. The StateOptionMetadata.DefaultStatus property for each option describes the default StatusCode that will be used if not set as a parameter in the SetStateRequest. | |
BooleanType | Boolean attributes can be set directly using a Boolean value, but like the others they also have an OptionSet property with FalseOption and TrueOption properties that correspond to the Boolean options. Each of these properties define a set of localized labels that represent what true and false mean for the attribute. Within the customization tools in the application these attributes are called Two Options fields because the meaning for each option can be any mutually exclusive pair of options, not just true and false. For example, the options might be big and small. | |
EntityNameType | These system attributes are generally paired with a unique identifier or reference attribute that is valid for multiple types. The value of this attribute is a string value representing the logical name of an entity. If the corresponding reference attribute is an EntityReference, the value of this attribute is the same as the EntityReference.Name property value. |
These system attributes return collections of values.
AttributeTypeName Value | Description |
|---|---|
CalendarRulesType | There are no actual attributes that use the CalendarRulesType. When using the early binding style, the code generation tool will create the following two simulated attributes that are not present in the metadata. These attributes actually represent a view of the calendar rules records associated in a one-to-many relationship to the entity instance.
|
PartyListType | The following attributes allow for multiple EntityReference to be set for various types of activities. ActivityPointer.allparties |
Attributes with the metadata AttributeTypeName value of DateTimeType. Set these attributes using System.DateTime.
The DateTimeAttributeMetadata.Format property can be one of the following DateTimeFormat values:
DateAndTime: Display the date and time.
DateOnly: Display the date only
Custom Date and time attributes can be defined as calculated or rollup attributes. More information: Calculated and rollup attributes.
For those entities which support image attributes, the SchemaName of the entity image attribute is always EntityImage.
More information: Image attributes, Entity images and Sample: Set and retrieve entity images.
Attributes in this category use numerical data. Each of these attributes has a MaxValue and MinValue metadata property to set a range of valid values.
Custom Decimal, Integer, and Money attributes can be defined as calculated or rollup attributes. More information: Calculated and rollup attributes.
Metadata Type | AttributeTypeName Value | Description |
|---|---|---|
BigIntType | BigInt attributes are for internal use only. | |
DecimalType | Use decimal values. The Precision metadata property sets the precision to be used for the attribute. | |
DoubleType | Use double values. The Precision metadata property sets the precision to be used for the attribute. | |
IntegerType | Use int values. | |
MoneyType | Use Money which has a decimalValue property. Each Money attribute has a corresponding system calculated base currency money attribute that is used to calculate the value in the organization’s base currency when multiple currencies have been enabled for the organization. The IsBaseCurrency property identifies whether a money attribute represents the base currency. More information: Transaction Currency (currency) entity. Money attributes also have a PrecisionSource metadata property that can specify the level of precision that should be used. The integer value in this property determines whether:
|
These attributes are commonly referred to as lookup attributes and each of them contain an EntityReference value. The difference between these attributes is the kinds of entities they can associate to. The Targets metadata property contains a String[] of the valid entity logical names that represent valid targets for the lookup. Custom lookup attributes can only have a single type in the Targets property.
The PartyListType also represent a kind of reference data attribute, but since they contain a collection of references, they are included in the Collection data attributes.
Metadata Type | AttributeTypeName Value | Description |
|---|---|---|
CustomerType | These system lookup attributes can link to Account or Contact entity records. Contact.ParentCustomerId | |
LookupType | These lookup attributes can be used to set references to a record of the type indicated by the Targets metadata property. Some system lookups do not have a value set for the Targets property, but the intended entity should be apparent based on the entity relationship that is associated to the lookup. | |
OwnerType | These system lookups are always named OwnerId and each user-owned entity will have one. They can reference either SystemUser or Team records. |
There are two types of attributes that use string data.
Metadata Type | AttributeTypeName Value | Description |
|---|---|---|
StringType | An attribute for a string value to which a format can be applied. More information: StringAttributeMetadata formats. Custom String attributes can be defined as calculated attributes. More information: Calculated attributes. | |
MemoType | An attribute for a string value intended for notes. This attributes is equivalent to String attributes with the FormatName property value set to TextArea. |
Attributes with the metadata AttributeTypeName value of UniqueidentifierType contain nullable System.Guid values.
Each entity instance includes one attribute that represents the unique identifier for the record. This attribute has a schema name that follows the naming convention <entity schema name>+Id. For example, the Account entity the schema name for the attribute representing the unique identifier is named AccountId. This value is also available directly using the Entity.Id property. This attribute is always returned when you retrieve an entity, even if you do not include it in the ColumnSet of a query. This value is null for a newly instantiated entity. While it is valid to set a Guid value to define the unique identifier when you create a new record, for best performance we recommend that you leave it null and allow the system to assign a value when the record is created. After a record is saved this value becomes read-only.
Entities may include other unique identifier attributes depending on the capabilities of the entity. For example, entities that are enabled for business processes will contain unique identifier attributes for ProcessId and StageId to track the current business process associated with the record. Certain system relationships that might normally use an EntityReference value will use a unique identifier instead. For example the Account and Contact entities each have two unique identifier attributes (Address1_AddressId and Address2_AddressId) that correspond to CustomerAddress records created when an Account or Contact is created.
The metadata for an entity will include some attributes with the metadata AttributeTypeName value of VirtualType. These attributes cannot be used in code.
Logical attributes contain values which are stored in different database tables than other attributes in the entity. In most cases this internal implementation is not relevant to working with Microsoft Dynamics 365. When you use logical attributes as sources for a calculated field the values in the calculated field cannot be sorted. Use the AttributeMetadata.IsLogical property to detect if an attribute is a logical attribute.
The most common logical attributes are those which store address information in several special entities: CompetitorAddress, CustomerAddress, InternalAddress, LeadAddress, and PublisherAddress. There are 8 system entities that include a complete set of attributes for two addresses using logical attributes. Each of these attributes begin with “Address*”, such as Address1_City or Address2_Latitude.
Microsoft Dynamics 365
© 2016 Microsoft. All rights reserved. Copyright