Créer des attributs de numérotation automatique

Avec la version Dynamics 365 Customer Engagement (on-premises) version 9, vous pouvez ajouter un attribut de numérotation automatique pour une entité. Pour le moment, vous pouvez ajouter l’attribut par programme. Il n’existe aucune interface utilisateur pour ajouter ce type d’attribut. Cet article explique comment créer par programme un attribut de numérotation automatique et définir une valeur de départ pour les éléments séquentiels. En outre, cet article explique comment définir le numéro séquentiel de l’enregistrement suivant si vous devez réinitialiser la valeur de départ ultérieurement.

Vous pouvez créer un attribut de numérotation automatique de la même façon que vous créez un attribut de chaîne avec la classe StringAttributeMetadata à ceci près que vous utilisez la nouvelle propriété AutoNumberFormat. Utilisez la propriété AutoNumberFormat pour définir un modèle contenant des numéros séquentiels et des chaînes aléatoires en composant des espaces réservés, qui indique la longueur et le type de valeurs générées. Les chaînes aléatoires vous aident à éviter les doublons ou les collisions, surtout lorsque les clients hors connexion essaient de créer des numéros automatiques.

Lors de la création d’un attribut de numérotation automatique, les valeurs de la propriété StringAttributeMetadata.FormatName ou de la propriété StringAttributeMetadata.Format doivent être Text. Comme il s’agit des valeurs par défaut, vous ne définissez pas généralement cette propriété. Vous ne pouvez pas créer un attribut de numérotation automatique qui utilise un autre type de format spécial, par exemple Courrier électronique, Téléphone, Zone de texte, URL, ou tout autre format existant.

Le séquençage automatique des numéros est géré par SQL et est assuré d’être unique.

Dans l’ancien client Web, lors de l’ajout d’un contrôle sur un formulaire lié à un attribut de numérotation automatique, le contrôle est désactivé automatiquement et se comporte en lecture seule dans le formulaire où les utilisateurs finaux ne peuvent pas modifier le contrôle. Dans Unified Interface, les contrôles liés à un attribut de numérotation automatique doivent explicitement être définis comme désactivés. Si vous ne définissez pas la valeur d’attribut initiale sur le formulaire, la valeur est définie uniquement après avoir enregistré l’entité. La numérotation automatique peut être appliquée sur les valeurs de champ d’attribut sous forme d’affichages, de grilles ou autres.

Exemples

Les exemples suivants montrent comment créer un attribut de numérotation automatique nommé new_SerialNumber pour une entité personnalisée nommée new_Widget, dont la valeur se présente comme suit : WID-00001-AB7LSFG-20170913070240. Utilisation du service d’organisation avec les classes CreateAttributeRequest et StringAttributeMetadata des assemblys du 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);

Utiliser l’API web

Vous pouvez créer et mettre à jour les définitions d’entité à l’aide de l’API web.

Pour plus d’informations :, voir Créer et mettre à jour les définitions d’entité à l’aide de l’API Web > Créer des attributs.

Demander

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
}

Response

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)

Options AutoNumberFormat

Ces exemples montrent comment configurer la propriété AutoNumberFormat pour obtenir différents résultats :

Les espaces réservés de chaîne aléatoires sont facultatifs. Vous pouvez inclure plusieurs espaces réservés de chaîne aléatoires. Utilisez l’une des valeurs de format pour les espaces réservés de date et d’heure qui sont disponibles dans Chaînes de format de date et d’heure.

Longueur de chaîne

Le tableau indique la valeur de longueur de chaîne pour les espaces réservés aléatoires et séquentiels.

Pour les espaces réservés à valeur séquentielle, la valeur MIN_LENGTH est une longueur minimale. Si vous définissez la valeur sur 2, la valeur initiale est 01, et la 100ème valeur d’entité est 100. Le nombre continuera à incrémenter au-delà de la longueur minimale. La définition de la longueur des valeurs séquentielles permet de créer une longueur cohérente pour la valeur générée automatiquement en ajoutant des 0 supplémentaires à la valeur initiale. Elle ne limitera pas la valeur absolue. Les espaces réservés à valeur aléatoire auront toujours la même longueur.

Comme les valeurs séquentielles peuvent être plus grandes que la longueur minimale qui leur est allouée, vous ne devez pas modifier la propriété StringAttributeMetadata.MaxLength pour la faire correspondre à la longueur de la valeur mise en forme. Cela a peu d’intérêt et peut entraîner une erreur dans l’avenir si la valeur dépasse la valeur MaxLength. Pensez à laisser suffisamment d’espace pour une plage réaliste de valeurs séquentielles.

Mettre à jour les attributs de numérotation automatique

Si vous créez un attribut de numérotation automatique avec une configuration incorrecte ou si vous souhaitez modifier un attribut de numérotation automatique existant, vous pouvez mettre à jour la valeur AutoNumberFormat de l’attribut.

L’extrait de code suivant vous explique comment récupérer, modifier et mettre à jour l’attribut de numérotation automatique.

Pour modifier un attribut de numérotation automatique existant, vous devez récupérer l’attribut à l’aide de la classe 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);

Après avoir récupéré l’attribut de numérotation automatique, vous devez modifier et mettre à jour l’attribut.

//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);

Définir une valeur de départ

Par défaut, toutes les valeurs séquentielles de numérotation automatique commencent par 1000 et utilisent 0 comme préfixe selon la longueur. Ainsi, la longueur de la valeur est toujours la même. Si vous voulez modifier la valeur initiale, vous devez modifier la valeur de départ à l’aide de l’API ci-dessous pour définir le numéro suivant utilisé pour le segment séquentiel.

Par exemple, si vous n’avez pas utilisé de valeur de départ ou si vous définissez la valeur de départ sur un seul chiffre, votre premier nombre serait un seul chiffre avec un préfixe de zéros ajouté pour égaler la longueur du nombre. Une valeur de départ à un seul chiffre avec une longueur d’affichage de 5 entraînerait l’affichage de la valeur « 5 » comme « 00005 ». L’utilisation d’une valeur de départ vous permet de commencer avec une valeur initiale plus grande, donc si vous définissez votre valeur de départ sur « 10 000 », une valeur de 5 donnerait « 10 005 ».

Si vous souhaitez choisir une autre valeur de départ après avoir créé l’attribut de numérotation automatique, utilisez le message SetAutoNumberSeed. Utilisez la classe SetAutoNumberSeedRequest lorsque vous utilisez les assemblys du SDK et l’action SetAutoNumberSeed lorsque vous utilisez l’API web.

Le message AutoNumberSeed a les paramètres suivants :

Exemples

Les exemples suivants définissent la valeur de départ sur 10000 pour un attribut de numérotation automatique nommé new_SerialNumber pour une entité personnalisée nommée new_Widget.

Utilisation du service d’organisation avec la classe SetAutoNumberSeedRequest des assemblys du SDK :

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

Utilisation de l’action SetAutoNumberSeed de l’API web

Pour plus d’informations : Utiliser les actions de l’API Web > Actions non liées

Demander

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
} 

Response

HTTP/1.1 204 No Content
OData-Version: 4.0

Outils de la communauté

Gestionnaire de numéros automatique

Auto Number Manager pour XrmToolBox est un outil communautaire pour Dynamics 365 Customer Engagement (on-premises) qui fournit une interface utilisateur pour définir, mettre à jour et supprimer le format de numérotation automatique dans des attributs nouveaux ou existants. Lisez l’article Outils pour développeurs pour les outils développés par la communauté et anm.xrmtoolbox.com pour plus d’informations concernant Auto Number Manager.

Voir aussi

Modèles de métadonnées et de données
Personnaliser les métadonnées d’attribut d’entité