Compartir a través de

Introducción a los atributos de entidad de Dynamics 365 Customer Engagement (on-premises)

  • Artículo

Las entidades incluyen un conjunto de atributos que representan los datos que se pueden incluir en cada registro. Los programadores deben comprender los diferentes tipos de atributos y cómo trabajar con ellos. Los metadatos para los atributos describen las operaciones y los comportamientos válidos de diferentes tipos de atributos. Varios tipos de atributos se pueden agrupar por comportamientos comunes.

La experiencia específica que tendrán los programadores depende de su estilo de desarrollo. Más información: Programación de entidades (comparación de enlace en tiempo de compilación, enlace en tiempo de ejecución y extensiones para desarrolladores).

Nota

En este tema se incluyen referencias a muchas propiedades de metadatos. Para ver los metadatos de las entidades de su organización, instale la solución Explorador de metadatos que se describe en Exploración de los metadatos de su organización. También puede examinar la documentación de referencia para las entidades en la Referencia de entidad.

Operaciones válida en atributos

Cada atributo tiene metadatos que describen las operaciones que admite. Debe conocer las operaciones que son válidas para los atributos con los que trabaja.

Propiedad AttributeMetadata Descripción
IsValidForCreate True si este valor de atributo es válido para establecer cuando se crea un registro; si no, false.
IsValidForRead True si este valor de atributo se puede recuperar; si no, false.
IsValidForUpdate True si este valor de atributo es válido para establecer cuando se actualiza un registro; si no, false.

Tipos de atributos

Los atributos se definen en los metadatos y la propiedad AttributeMetadata .AttributeTypeName contiene el valor que describe el tipo. Los integrantes estáticos de AttributeTypeDisplayName proporcionan la lista de tipos posibles.

Nota

La antigua propiedad AttributeType contiene datos que están fundamentalmente alineados con AttributeTypeName, pero muestran atributos ImageType como Virtual. Debe usar la propiedad AttributeTypeName en lugar de la propiedad AttributeType.

La siguiente sección agrupa los tipos de atributos en las siguientes categorías para poder compararlas más fácilmente:

Atributos de datos de categorización

Cada uno de los seis atributos de este grupo se heredan de una clase base común de EnumAttributeMetadata y usan un conjunto predefinido de valores válidos para agrupar los registros en categorías.

Establezca atributos de lista desplegable, situación y estado mediante OptionSetValue con una propiedad de Value establecida en un entero que represente una opción válida en los metadatos.

Establezca atributos booleanos mediante un valor booleano, pero reconozca que se trata de una categorización limitada a solamente dos opciones.

Los atributos EntityName usan un valor de cadena que está limitado a un nombre lógico de entidad válido de la organización.

Los atributos de lista desplegable y booleanos personalizados se pueden definir como atributos calculados. Más información: Atributos calculados.

Tipo de metadatos Valor de AttributeTypeName Descripción
PicklistAttributeMetadata PicklistType Los valores válidos se definen en OptionMetadata.Value para el atributo definido en OptionSetMetadata.Options.
En las herramientas de personalización de la aplicación estos atributos se denominan campos de Conjunto de opciones.
MultiSelectPicklistAttributeMetadata MultiSelectPicklistType Nota: los atributos de lista desplegable de selección múltiple se agregaron con Dynamics 365 Customer Engagement (on-premises), versión 9.x.
Más información Atributos de lista desplegable de selección múltiple.
En las herramientas de personalización de la aplicación estos atributos se denominan campos de Conjunto de opciones de selección múltiple.
StatusAttributeMetadata StatusType Estos atributos del sistema normalmente se denominan StatusCode. Los valores válidos se definen en StatusOptionMetadata.Value para el atributo definido en OptionSetMetadata.Options.
La propiedad StatusOptionMetadata.State para cada opción describe el valor válido para el correspondiente valor de StateCode. Antes de configurar StatusCode debe comprobar que sea válido para el valor actual de StateCode. Use el mensaje de SetStateRequest para establecer los valores de atributo de StatusCode y de StateCode si necesita cambiar el estado del registro.
Estos atributos pueden tener otras restricciones en las que se pueden establecer valores. La propiedad StatusOptionMetadata.TransitionData puede contener información sobre qué opciones se admiten cuando EntityMetadata.EnforceTransitions es verdadero. Más información: Definir transiciones de modelo de estado personalizadas.
StateAttributeMetadata StateType Estos atributos del sistema normalmente se denominan StateCode. Los valores válidos se definen en StateOptionMetadata.Value para el atributo definido en OptionSetMetadata.Options.
StateCode no es válido para actualizar. Una vez creado el registro, StateCode solo se puede establecer usando el mensaje de SetStateRequest.
La propiedad StateOptionMetadata.DefaultStatus para cada opción describe el StatusCode predeterminado que se usará si no se establece como parámetro en la SetStateRequest.
BooleanAttributeMetadata BooleanType Los atributos booleanos se pueden configurar directamente con un valor booleano, pero como los otros también tienen una propiedad OptionSet con propiedades FalseOption y TrueOption que correspondan a las opciones booleanas. Cada una de esas propiedades define un conjunto de etiquetas localizadas que representa lo que suponen true y false para el atributo. Dentro de las herramientas de personalización en la aplicación estos atributos se denominan campos Dos opciones porque el significado de cada opción puede ser cualquier par mutuamente exclusivo de opciones, no sólo true y false. Por ejemplo, las opciones podrían ser grande y pequeño.
EntityNameAttributeMetadata EntityNameType Estos atributos del sistema se emparejan con un atributo de referencia o identificador único que es válido para varios tipos. El valor de este atributo es un valor de cadena que representa el nombre lógico de una entidad. Si el atributo de referencia correspondiente es un EntityReference, el valor de este atributo es el mismo que el valor de propiedad de EntityReference.Name.

Atributos de datos de colección

Estos atributos del sistema devuelven colecciones de valores.

Valor de AttributeTypeName Descripción
CalendarRulesType No hay atributos reales que usan CalendarRulesType. Cuando se usa el estilo de enlace anticipado, la herramienta de generación de código creará los dos atributos simulados siguientes que no están presentes en los metadatos. Estos atributos representan realmente una vista de registros de reglas de calendario asociados en una relación de uno a varios a la instancia de entidad.
- Calendar.CalendarRules relación: calendar_calendar_rules
- Service.CalendarRules relación: service_calendar_rules
PartyListType Los siguientes atributos permiten establecer varios EntityReference para varios tipos de actividades.
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

Atributo de datos de fecha y hora

Atributos con el valor de AttributeTypeName de metadatos de DateTimeType. Establezca estos atributos mediante System.DateTime.

La propiedad DateTimeAttributeMetadata.Format puede ser uno de los siguientes valores DateTimeFormat:

  • DateAndTime: Mostrar la fecha y hora.

  • DateOnly: Mostrar solo la fecha

    Los atributos de fecha y hora personalizados se pueden definir como atributos calculados o consolidados. Más información: Atributos calculados y consolidados.

Atributos de datos de imagen

Para las entidades, que admiten atributos de imagen, el atributo SchemaName de la entidad de imagen siempre es EntityImage.

Más información: Atributos de imagen, Imágenes de entidad y Ejemplo: establecer y recuperar imágenes de entidad.

Atributos de datos de cantidad

Los atributos en esta categoría usan datos numéricos. Cada uno de estos atributos tiene una propiedad de metadatos MaxValue y MinValue para establecer un intervalo de valores válidos.

Los atributos de decimal, entero o dinero personalizados se pueden definir como atributos calculados o consolidados. Más información: Atributos calculados y consolidados.

Tipo de metadatos Valor de AttributeTypeName Descripción
BigIntAttributeMetadata BigIntType Los atributos BigInt solo para uso interno.
DecimalAttributeMetadata DecimalType Use valores decimales.
La propiedad de metadatos Precision define la precisión que se usará para el atributo.
DoubleAttributeMetadata DoubleType Use valores dobles.
La propiedad de metadatos Precision define la precisión que se usará para el atributo.
IntegerAttributeMetadata IntegerType Use valores int.
MoneyAttributeMetadata MoneyType Use el Money que tiene una propiedad decimal``Value.
Cada atributo monetario tiene un correspondiente atributo monetario de divisa base calculado por el sistema que se usa para calcular el valor de la divisa base de la organización cuando varias divisas se han habilitado para la organización. La propiedad IsBaseCurrency identifica si un atributo monetario representa la divisa base. Más información: Entidad de divisa de transacciones (divisa).
Los atributos monetarios también tienen una propiedad de metadatos PrecisionSource que puede especificar el nivel de precisión que deben usarse. El valor de entero en esta propiedad determina si:
- 0: la precisión está determinada por la propiedad de metadatos Precision.
- 1: El valor Organization.PricingDecimalPrecision.
- 2: El TransactionCurrency.CurrencyPrecision asociado con el registro actual.

Atributos de datos de referencia

Estos atributos se llaman habitualmente atributos de búsqueda y cada uno de ellos contiene un valor de EntityReference. La diferencia entre estos atributos es la clase de entidades con la que pueden asociarse. La propiedad de metadatos Targets contiene una String[] de nombres lógicos de entidad válida que representa destinos válidos para la búsqueda. Los atributos de búsqueda personalizados sólo pueden tener un tipo en la propiedad Targets.

PartyListType también representa un tipo de atributo de datos de referencia, pero dado que contiene una colección de referencias, se incluye en los Atributos de datos de colección.

Tipo de metadatos Valor de AttributeTypeName Descripción
LookupAttributeMetadata CustomerType Estos atributos de búsqueda del sistema pueden vincularse con los registros de entidad de cuenta o de contacto.
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 Estos atributos de búsqueda se pueden usar para establecer referencias a un registro del tipo indicado mediante la propiedad de metadatos Targets.
Algunas búsquedas del sistema no tienen un valor establecido para la propiedad Targets, pero la entidad prevista debe estar aparentemente basada en la relación de entidad que está asociada a la búsqueda.
LookupAttributeMetadata OwnerType Estas búsquedas del sistema siempre se llaman OwnerId y cada entidad propiedad del usuario tendrá una. Pueden hacer referencia a registros SystemUser o del equipo.

Atributos de datos de cadena

Existen dos tipos de atributos que usan datos de cadena.

Tipo de metadatos Valor de AttributeTypeName Descripción
StringAttributeMetadata StringType Un atributo para un valor de cadena al que se puede aplicar un formato. Más información: Formatos de StringAttributeMetadata.
Los atributos de cadena personalizados se pueden definir como atributos calculados. Más información: Atributos calculados.
MemoAttributeMetadata MemoType Un atributo para un valor de cadena pensado para notas. Este atributo es equivalente a los atributos de cadena con el valor de propiedad FormatName establecido en TextArea.

Identificador único de atributos de datos.

Los atributos con el valor de AttributeTypeName de metadatos de UniqueidentifierType contienen valores System.Guid que acepta valores nulos.

Cada instancia de entidad incluye un atributo que representa el identificador único del registro. Este atributo tiene un nombre de esquema que sigue la convención de nomenclatura <entity schema name>+ID. Por ejemplo, la entidad Cuenta, el nombre de esquema para el atributo que representa el identificador único, se llama AccountId. Este valor también está disponible directamente utilizando la propiedad Entity.Id. Este atributo se devuelve siempre cuando se recupera una entidad, incluso si no se incluye en la ColumnSet de una consulta. Este valor es nulo para una entidad recién instanciada. Aunque es válido configurar un valor de Guid para definir el identificador único cuando se crea un nuevo registro, para conseguir el máximo rendimiento se recomienda dejarlo nulo y permitir que el sistema asigne un valor al crear el registro. Tras guardar un registro este valor se convierte en de solo lectura.

Las entidades pueden incluir otros atributos de identificador único en función de las capacidades de la entidad. Por ejemplo, las entidades que se habilitan para procesos de negocio contendrán atributos de identificador único para que ProcessId y StageId realice un seguimiento del proceso de negocio actual asociada al registro. Determinadas relaciones del sistema que normalmente usaría un valor de EntityReference usarán un identificador único en su lugar. Por ejemplo, las entidades de cuenta y contacto tienen dos atributos de identificador único (Address1_AddressId y Address2_AddressId) que corresponden a los registros de CustomerAddress creados cuando se crea una cuenta o un contacto.

Atributos virtuales

Los metadatos para una entidad incluirán algunos atributos con el valor de AttributeTypeName de metadatos de VirtualType. Estos atributos no se pueden usar en código.

Atributos lógicos

Los atributos lógicos contienen valores que se almacenan en tablas de base de datos diferentes que otros atributos de la entidad. En la mayoría de los casos, esta implementación interna no es relevante para trabajar con Dynamics 365 Customer Engagement (on-premises). Cuando usa atributos lógicos como orígenes de un campo calculado los valores del campo calculado no se pueden ordenar. Use la propiedad AttributeMetadata.IsLogical para detectar si un atributo es un atributo lógico.

Los atributos lógicos más habituales son los que almacenan la información de dirección en varias entidades especiales: CompetitorAddress, CustomerAddress, InternalAddress, LeadAddress y PublisherAddress. Existen ocho entidades del sistema que incluyen un conjunto completo de atributos para dos direcciones mediante atributos lógicos. Cada uno de estos atributos comienza con “Address*”, por ejemplo, Address1_City o Address2_Latitude.

Vea también

Introducción a entidades en Dynamics 365 Customer Engagement (on-premises)
Atributos de imagen
Atributos calculados y consolidados
Ejemplo: recuperar transiciones de estado válidas
Ejemplo: establecer y recuperar imágenes de entidad