Créer des attributs de numérotation automatique

Article
03/22/2023

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.

Note

Le paramétrage de la valeur de départ est facultatif. Il n’est pas nécessaire d’appeler la valeur de départ si vous n’effectuez pas de réinitialisation.

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.

Note

Les valeurs de numérotation automatique sont présélectionnées par la base de données quand l’enregistrement démarre. Si un enregistrement a démarré mais a été annulé, le numéro qui a été attribué n’est pas utilisé. Si, pendant ce temps, un autre enregistrement contient le numéro séquentiel suivant, il existe alors des écarts dans la numérotation automatique des enregistrements.

Note

Vous pouvez modifier un attribut de texte de format existant en format de numérotation automatique.

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(402fa40f-287c-e511-80d2-00155d2a68d2)/Attributes(f01bef16-287c-e511-80d2-00155d2a68d2)

Options AutoNumberFormat

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

Valeur AutoNumberFormat	Exemple de valeur
`CAR-{SEQNUM:3}-{RANDSTRING:6}`	`CAR-123-AB7LSF`
`CNR-{RANDSTRING:4}-{SEQNUM:4}`	`CNR-WXYZ-1000`
`{SEQNUM:6}-#-{RANDSTRING:3}`	`123456-#-R3V`
`KA-{SEQNUM:4}`	`KA-0001`
`{SEQNUM:10}`	`1234567890`
`QUO-{SEQNUM:3}#{RANDSTRING:3}#{RANDSTRING:5}`	`QUO-123#ABC#PQ2ST`
`QUO-{SEQNUM:7}{RANDSTRING:5}`	`QUO-0001000P9G3R`
`CAS-{SEQNUM:6}-{RANDSTRING:6}-{DATETIMEUTC:yyyyMMddhhmmss}`	`CAS-002000-S1P0H0-20170913091544`
`CAS-{SEQNUM:6}-{DATETIMEUTC:yyyyMMddhh}-{RANDSTRING:6}`	`CAS-002002-2017091309-HTZOUR`
`CAS-{SEQNUM:6}-{DATETIMEUTC:yyyyMM}-{RANDSTRING:6}-{DATETIMEUTC:hhmmss}`	`CAS-002000-201709-Z8M2Z6-110901`

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.

Espace réservé	Longueur de chaîne	Scénario de sortie
`{RANDSTRING:MIN_LENGTH}`	La valeur de MIN_LENGTH est comprise entre 1 et 6.	Lorsque vous enregistrez l’entité, l’attribut de numérotation automatique génère la chaîne aléatoire avec la longueur définie si la valeur est comprise entre 1 et 6. Si vous définissez la valeur MIN_LENGTH sur 7 ou plus, une erreur Argument non valide s’affiche.
`{SEQNUM:MIN_LENGTH}`	La valeur minimale de MIN_LENGTH est 1. Le nombre continue à incrémenter au-delà de la longueur minimale.	Lorsque vous enregistrez l’entité, l’attribut de numérotation automatique fonctionne correctement et continuera à fonctionner correctement pour les valeurs plus grandes de MIN_LENGTH.

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.

Note

Les valeurs d’espace réservé ne sont pas validées lorsque vous créez l’attribut. L’erreur apparaît uniquement lorsque vous essayez d’enregistrer une instance d’entité qui utilise une valeur AutoNumberFormat configurée de manière incorrecte. Par exemple, si vous spécifiez la longueur de la chaîne aléatoire sur une valeur supérieure à 6, la première personne qui crée une nouvelle instance d’entité obtient une erreur Argument non valide lorsqu’elle essaie d’enregistrer l’entité contenant le nouvel attribut de numérotation automatique.

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 :

Nom	Type	Description
EntityName	chaîne	Nom logique de l’entité contenant l’attribut dont vous souhaitez définir la valeur de départ.
AttributeName	chaîne	Nom logique de l’attribut dont vous souhaitez définir la valeur de départ.
active	int	Valeur de numérotation automatique suivante pour l’attribut.

Note

La définition d’une valeur de départ permet de ne changer que la valeur numérique actuelle pour l’attribut spécifié dans l’environnement actuel. Elle ne requiert pas une valeur de départ commune pour l’attribut. La valeur de départ n’est pas incluse dans une solution en cas d’installation dans différents environnements. Pour définir le numéro de départ après l’importation d’une solution, utilisez le message SetAutoNumberSeed dans l’environnement cible.

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.

Note

Les outils de la communauté ne sont pas un produit de Microsoft Dynamics et n’étendent pas le support aux outils de la communauté. Si vous avez des questions relatives à cet outil, contactez l’éditeur. Pour plus d’informations : XrmToolBox.

Voir aussi

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

Créer des attributs de numérotation automatique

Exemples

Utiliser l’API web

Demander

Response

Options AutoNumberFormat

Longueur de chaîne

Mettre à jour les attributs de numérotation automatique

Définir une valeur de départ

Exemples

Demander

Response

Outils de la communauté

Gestionnaire de numéros automatique

Voir aussi

Ressources supplémentaires