Introduction to entity attributes in Dynamics 365 Customer Engagement (on-premises)
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 browse the reference documentation for entities in the Entity Reference.
Valid operations on attributes
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 |
|---|---|
| IsValidForCreate | True if this attribute value is valid to be set when a record is created, otherwise false. |
| IsValidForRead | True if this attribute value can be retrieved, otherwise false. |
| IsValidForUpdate | True if this attribute value is valid to be set when a record is updated, otherwise false. |
Types of attributes
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:
Categorization data attributes
Each of the six 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 |
|---|---|---|
| PicklistAttributeMetadata | 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. |
| MultiSelectPicklistAttributeMetadata | MultiSelectPicklistType | Note: Multi-select picklist attributes were added with the Dynamics 365 Customer Engagement (on-premises) Version 9.x. More information Multi-Select Picklist attributes. Within the customization tools in the application these attributes are called Multi-Select Option Set fields. |
| StatusAttributeMetadata | StatusType | These system attributes are 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's 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. |
| StateAttributeMetadata | StateType | These system attributes are named StateCode. Valid values are set in the StateOptionMetadata.Value for that attribute defined within the OptionSetMetadata.Options.StateCode isn't 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. |
| BooleanAttributeMetadata | 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 defines 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 large and small. |
| EntityNameAttributeMetadata | EntityNameType | These system attributes are 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. |
Collection data attributes
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 aren't 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.- Calendar.CalendarRules relationship: calendar_calendar_rules- Service.CalendarRules relationship: service_calendar_rules |
| PartyListType | The following attributes allow for multiple EntityReference to be set for various types of activities. ActivityPointer.allparties Appointment.OptionalAttendees Appointment.Organizer Appointment.requiredattendees CampaignActivity.from CampaignActivity.Partners CampaignResponse.Customer CampaignResponse.from CampaignResponse.Partner Email.bcc Email.cc Email.from Email.to Fax.from Fax.to Letter.bcc Letter.cc Letter.from Letter.to PhoneCall.from PhoneCall.to RecurringAppointmentMaster.OptionalAttendees RecurringAppointmentMaster.Organizer RecurringAppointmentMaster.RequiredAttendees ServiceAppointment.Customers ServiceAppointment.Resources SocialActivity.From SocialActivity.Resources SocialActivity.To |
Date and time data attribute
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 onlyCustom Date and time attributes can be defined as calculated or rollup attributes. More information: Calculated and Rollup Attributes.
Image data 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.
Quantity data attributes
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 |
|---|---|---|
| BigIntAttributeMetadata | BigIntType | BigInt attributes are for internal use only. |
| DecimalAttributeMetadata | DecimalType | Use decimal values. The Precision metadata property sets the precision to be used for the attribute. |
| DoubleAttributeMetadata | DoubleType | Use double values. The Precision metadata property sets the precision to be used for the attribute. |
| IntegerAttributeMetadata | IntegerType | Use int values. |
| MoneyAttributeMetadata | MoneyType | Use Money which has a decimal``Value 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: - 0: The precision is determined by the Precision metadata property. - 1: The Organization.PricingDecimalPrecision value.- 2: The TransactionCurrency.CurrencyPrecision that is associated with the current record. |
Reference data attributes
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 |
|---|---|---|
| LookupAttributeMetadata | CustomerType | These system lookup attributes can link to Account or Contact entity records. Contact.ParentCustomerId Contract.BillingCustomerId Contract.CustomerId ContractDetail.CustomerId CustomerOpportunityRole.CustomerId CustomerRelationship.CustomerId CustomerRelationship.PartnerId Entitlement.CustomerId Incident.CustomerId Invoice.CustomerId Lead.CustomerId Opportunity.CustomerId Quote.CustomerId SalesOrder.CustomerId SocialActivity.PostAuthor SocialActivity.PostAuthorAccount SocialProfile.CustomerId |
| LookupAttributeMetadata | 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 don't 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. |
| LookupAttributeMetadata | OwnerType | These system lookups are always named OwnerId and each user-owned entity will have one. They can reference either SystemUser or Team records. |
String data attributes
There are two types of attributes that use string data.
| Metadata Type | AttributeTypeName Value | Description |
|---|---|---|
| StringAttributeMetadata | 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. |
| MemoAttributeMetadata | MemoType | An attribute for a string value intended for notes. This attribute is equivalent to String attributes with the FormatName property value set to TextArea. |
Unique identifier data attributes
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 don't 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.
Virtual attributes
The metadata for an entity will include some attributes with the metadata AttributeTypeName value of VirtualType. These attributes can't be used in code.
Logical attributes
Logical attributes contain values that are stored in different database tables than other attributes in the entity. In most cases this internal implementation isn't relevant to working with Dynamics 365 Customer Engagement (on-premises). When you use logical attributes as sources for a calculated field the values in the calculated field can't 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 eight system entities that include a complete set of attributes for two addresses using logical attributes. Each of these attributes begins with “Address*”, such as Address1_City or Address2_Latitude.
See also
Introduction to Entities in Dynamics 365 Customer Engagement (on-premises)
Image Attributes
Calculated and Rollup Attributes
Sample: Retrieve Valid Status Transitions
Sample: Set and retrieve entity images