Udostępnij za pośrednictwem

Introduction to entity attributes in Microsoft Dynamics 365

  • Artykuł

 

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.

In this topic

Valid operations on attributes

Types of attributes

Categorization data attributes

Collection data attributes

Date and time data attribute

Image data attributes

Quantity data attributes

Reference data attributes

String data attributes

Unique identifier data attributes

Virtual attributes

Logical attributes

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

  • Collection data attributes

  • Date and time data attribute

  • Image data attributes

  • Quantity data attributes

  • Reference data attributes

  • String data attributes

  • Unique identifier data attributes

  • Virtual attributes

Categorization data attributes

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

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.

StatusAttributeMetadata

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.

StateAttributeMetadata

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.

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

EntityNameAttributeMetadata

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.

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

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

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

  • 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

LookupType

These lookup attributes can be used to set references to a record of the type indicated by the 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.

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

Virtual attributes

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

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.

See Also

Introduction to entities in Microsoft Dynamics 365
Image attributes
Calculated and rollup attributes
Sample: Retrieve valid status transitions
Sample: Set and retrieve entity images

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright