Editar

Compartilhar via

Introduction to entity attributes in Dynamics 365 Customer Engagement (on-premises)

  • Artigo

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