Crear atributos de numeración automática

Con la versión 9 de Dynamics 365 Customer Engagement (on-premises), puede agregar un atributo de numeración automática para cualquier entidad. Actualmente, puede agregar el atributo mediante programación. No hay una interfaz de usuario para agregar este tipo de atributo. En este artículo se explica cómo crear mediante programación un atributo de numeración automática y establecer un valor de inicialización para los elementos secuenciales. Además, en este artículo se muestra cómo establecer el número de secuencia para el siguiente registro si necesita restablecer la semilla en cualquier momento posterior.

Puede crear un atributo de numeración automática de la misma manera que crea un atributo de cadena mediante la clase StringAttributeMetadata , excepto que usa la nueva propiedad AutoNumberFormat . Use la propiedad AutoNumberFormat para definir un patrón que incluya números secuenciales y cadenas aleatorias mediante la composición de marcadores de posición, que indican la longitud y el tipo de valores que se generan. Las cadenas aleatorias le ayudan a evitar duplicados o colisiones, especialmente cuando los clientes sin conexión intentan crear números automáticos.

Al crear un atributo de numeración automática, los valores de la propiedad StringAttributeMetadata.FormatName o StringAttributeMetadata.Format deben ser Text. Dado que estos son los valores predeterminados, normalmente no establecerá esta propiedad. No puede crear un atributo de numeración automática que utilice cualquier otro tipo especial de formato, como Correo electrónico, Teléfono, Área de texto, URL o cualquier otro formato existente.

La secuenciación de números automáticos se administra mediante SQL y se garantiza que sea única.

En el cliente web heredado, al agregar un control en un formulario enlazado a un atributo de numeración automática, el control se deshabilita automáticamente y se comporta como de solo lectura en el formulario en el que los usuarios finales no pueden editar el control. En la interfaz unificada, los controles enlazados a un atributo de numeración automática deben establecerse explícitamente como deshabilitados. Si no establece el valor del atributo inicial en el formulario, el valor se establece solo después de guardar la entidad. La numeración automática se puede aplicar a los valores de campo de atributo en vistas, cuadrículas, etc.

Ejemplos

En los ejemplos siguientes se muestra cómo crear un nuevo atributo de numeración automática denominado new_SerialNumber para una entidad personalizada denominada new_Widget, que tendrá un valor similar al siguiente: WID-00001-AB7LSFG-20170913070240. Uso del servicio de organización con las clases CreateAttributeRequest y StringAttributeMetadata de los ensamblados del SDK:

CreateAttributeRequest widgetSerialNumberAttributeRequest = new CreateAttributeRequest
            {
                EntityName = "newWidget",
                Attribute = new StringAttributeMetadata
                {
                    //Define the format of the attribute
                    AutoNumberFormat = "WID-{SEQNUM:5}-{RANDSTRING:6}-{DATETIMEUTC:yyyyMMddhhmmss}",
                    LogicalName = "new_serialnumber",
                    SchemaName = "new_SerialNumber",
                    RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),
                    MaxLength = 100, // The MaxLength defined for the string attribute must be greater than the length of the AutoNumberFormat value, that is, it should be able to fit in the generated value.
                    DisplayName = new Label("Serial Number", 1033),
                    Description = new Label("Serial Number of the widget.", 1033)
                }
            };
            _serviceProxy.Execute(widgetSerialNumberAttributeRequest);

Usar API web

Puede crear y actualizar definiciones de entidad mediante la API web.

Más información: Crear y actualizar definiciones de entidades mediante la API Web > Crear atributos.

Solicitud

POST [Organization URI]/api/data/v9.1/EntityDefinitions(LogicalName='new_widget')/Attributes HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "AttributeType": "String",
 "AttributeTypeName": {
  "Value": "StringType"
 },
 "Description": {
  "@odata.type": "Microsoft.Dynamics.CRM.Label",
  "LocalizedLabels": [
   {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Serial Number of the widget.",
    "LanguageCode": 1033
   }
  ]
 },
 "DisplayName": {
  "@odata.type": "Microsoft.Dynamics.CRM.Label",
  "LocalizedLabels": [
   {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Serial Number",
    "LanguageCode": 1033
   }
  ]
 },
 "RequiredLevel": {
  "Value": "None",
  "CanBeChanged": true,
  "ManagedPropertyLogicalName": "canmodifyrequirementlevelsettings"
 },
 "SchemaName": "new_SerialNumber",
 "AutoNumberFormat": "WID-{SEQNUM:5}-{RANDSTRING:6}-{DATETIMEUTC:yyyyMMddhhmmss}",
 "@odata.type": "Microsoft.Dynamics.CRM.StringAttributeMetadata",
 "FormatName": {
  "Value": "Text"
 },
 "MaxLength": 100
}

Respuesta

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.1/EntityDefinitions(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)/Attributes(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)

Opciones de AutoNumberFormat

En estos ejemplos se muestra cómo se puede configurar la propiedad AutoNumberFormat para obtener resultados diferentes:

Los marcadores de posición de cadenas aleatorias son opcionales. Puede incluir más de un marcador de posición de cadena aleatorio. Utilice cualquiera de los valores de formato para los marcadores de posición de fecha y hora de las cadenas de formato de fecha y hora estándar.

Longitud de cadena

La tabla muestra el valor de longitud de cadena para los marcadores de posición aleatorios y secuenciales.

En el caso de los marcadores de posición de valor secuencial, el MIN_LENGTH es una longitud mínima. Si establece el valor en 2, el valor inicial será 01 y el valor de la entidad número 100 será 100. El número continuará incrementándose más allá de la longitud mínima. El valor de establecer la longitud de los valores secuenciales es establecer una longitud coherente para el valor generado automáticamente agregando 0 adicionales al valor inicial. No limitará el valor absoluto. Los marcadores de posición de valores aleatorios siempre tendrán la misma longitud.

Dado que los valores secuenciales pueden ser mayores que la longitud mínima asignada para ellos, no debe ajustar la propiedad StringAttributeMetadata.MaxLength para que coincida con la longitud del valor con formato. Hacer esto tiene poco valor y podría provocar un error en el futuro si el valor supera el valor de MaxLength . Asegúrese de dejar suficiente espacio para un rango realista de valores secuenciales.

Actualizar atributos de numeración automática

Si crea un atributo de numeración automática con una configuración incorrecta o desea modificar un atributo de numeración automática existente, puede actualizar el valor de AutoNumberFormat del atributo.

En el siguiente fragmento de código se explica cómo recuperar, modificar y actualizar el atributo de numeración automática.

Para modificar un atributo de numeración automática existente, debe recuperar el atributo mediante la clase RetrieveAttributeRequest .

// Create the retrieve request
RetrieveAttributeRequest attributeRequest = new RetrieveAttributeRequest
            {
                EntityLogicalName = entityName.ToLower(),
                LogicalName = "new_serialnumber",
                RetrieveAsIfPublished = true
            };
// Retrieve attribute response
RetrieveAttributeResponse attributeResponse = (RetrieveAttributeResponse)_serviceProxy.Execute(attributeRequest);

Después de recuperar el atributo de numeración automática, debe modificar y actualizar el atributo.

//Modify the retrieved auto-number attribute
AttributeMetadata retrievedAttributeMetadata = attributeResponse.AttributeMetadata;
retrievedAttributeMetadata.AutoNumberFormat = "CAR-{RANDSTRING:5}{SEQNUM:6}"; //Modify the existing attribute by writing the format as per your requirement 

// Update the auto-number attribute            
UpdateAttributeRequest updateRequest = new UpdateAttributeRequest
                        {
                            Attribute = retrievedAttributeMetadata,
                            EntityName = "newWidget",
                        };
// Execute the request
_serviceProxy.Execute(updateRequest);

Establecer un valor de inicialización

De forma predeterminada, todos los valores secuenciales de numeración automática comienzan con 1000 y usan 0 como prefijo en función de la longitud. De esta manera, la longitud del valor es siempre la misma. Si desea cambiar el valor inicial, debe cambiar el valor de inicialización inicial mediante la API a continuación para establecer el siguiente número que se usa para el segmento secuencial.

Por ejemplo, si no utilizó un valor de inicialización, o si estableció el valor de inicialización en un solo dígito, el primer número sería un solo dígito con un prefijo de ceros agregado para igualar la longitud del número. Una semilla de un solo dígito con una longitud de visualización de 5 daría como resultado mostrar "5" como "00005". El uso de un valor de inicialización le permite comenzar con un valor inicial mayor, por lo que si establece su semilla como "10000", un valor de 5 se mostraría como "10005".

Si desea elegir un valor inicial diferente después de crear el atributo de numeración automática, use el mensaje SetAutoNumberSeed . Use la clase SetAutoNumberSeedRequest cuando use los ensamblados del SDK y la acción SetAutoNumberSeed cuando use la API web.

El mensaje AutoNumberSeed tiene los siguientes parámetros:

Ejemplos

En los ejemplos siguientes se establece el valor de inicialización en 10000 para un atributo de numeración automática denominado new_SerialNumber para una entidad personalizada denominada new_Widget.

Usando el servicio de organización con la clase SetAutoNumberSeedRequest de ensamblados de SDK:

//Define the seed 
SetAutoNumberSeedRequest req = new SetAutoNumberSeedRequest();
req.EntityName = "newWidget";
req.AttributeName = "newSerialnumber";
req.Value = 10000;
_serviceProxy.Execute(req);

Uso de la acción SetAutoNumberSeed de la API web.

Más información: Use las acciones de API de web > Acciones sin enlazar

Solicitud

POST [Organization URI]/api/data/v9.1/SetAutoNumberSeed HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "EntityName": "new_Widget",
 "AttributeName": "new_Serialnumber",
 "Value": 10000
} 

Respuesta

HTTP/1.1 204 No Content
OData-Version: 4.0

Herramientas de la comunidad

Administrador de números automáticos

Auto Number Manager for XrmToolBox es una herramienta impulsada por la comunidad para Dynamics 365 Customer Engagement (on-premises) que proporciona una interfaz de usuario para establecer, actualizar y quitar el formato de número automático en atributos nuevos o existentes. Consulte el artículo Herramientas para desarrolladores para conocer las herramientas desarrolladas por la comunidad y anm.xrmtoolbox.com para obtener más información sobre el Administrador de números automáticos.

Véase también

Metadatos y modelos de datos
Personalización de metadatos de atributos de entidad