Création d’attributs de numérotation automatique

Avec la version 9 de Dynamics 365 Customer Engagement (on-premises), vous pouvez ajouter un attribut de numéro automatique pour n’importe quelle entité. Actuellement, vous pouvez ajouter l’attribut par programmation. Il n’existe pas d’interface utilisateur pour ajouter ce type d’attribut. Cet article explique comment créer par programmation un attribut de numérotation automatique et définir une valeur de départ pour les éléments séquentiels. De plus, cet article montre comment définir le numéro de séquence pour l’enregistrement suivant si vous devez réinitialiser la graine à tout moment plus tard.

Vous pouvez créer un attribut de numérotation automatique de la même manière que vous créez un attribut de chaîne à l’aide de la classe StringAttributeMetadata , sauf que vous utilisez la nouvelle propriété AutoNumberFormat . Utilisez la propriété AutoNumberFormat pour définir un modèle qui inclut des nombres séquentiels et des chaînes aléatoires en composant des espaces réservés, qui indiquent la longueur et le type de valeurs générées. Les chaînes aléatoires vous aident à éviter les doublons ou les collisions, en particulier lorsque les clients hors ligne 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. Étant donné qu’il s’agit des valeurs par défaut, vous ne définirez généralement pas cette propriété. Vous ne pouvez pas créer un attribut de numérotation automatique qui utilise un autre type de format spécial, tel que E-mail, Téléphone, Zone de texte, URL ou tout autre format existant.

Le séquençage de numérotation automatique est géré par SQL et son caractère unique est garanti.

Dans le client Web hérité, lors de l’ajout d’un contrôle sur un formulaire lié à un attribut auto-number, le contrôle est automatiquement désactivé 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 auto-number doivent être explicitement définis comme désactivés. Si vous ne définissez pas la valeur d’attribut initiale sur le formulaire, la valeur n’est définie qu’après avoir enregistré l’entité. La numérotation automatique peut être appliquée aux valeurs de champ d’attribut dans les vues, les grilles, etc.

Exemples

Les exemples suivants montrent comment créer un nouvel attribut auto-number nommé new_SerialNumber pour une entité personnalisée nommée new_Widget, qui aura une valeur qui ressemble à ceci : WID-00001-AB7LSFG-20170913070240. Utilisation du service Organization avec les classes CreateAttributeRequest et StringAttributeMetadata des assemblys 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 des définitions d’entité à l’aide de l’API Web.

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

Requête

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
}

Réponse

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 vous pouvez configurer la propriété AutoNumberFormat pour obtenir des résultats différents :

Les éléments de substitution pour les chaînes de texte 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 MIN_LENGTH est une longueur minimale. Si vous définissez la valeur sur 2, la valeur initiale sera 01 et la valeur de la 100e entité sera 100. Le nombre continuera d’augmenter au-delà de la durée minimale. Définir la longueur des valeurs séquentielles permet d'établir une longueur cohérente pour la valeur générée automatiquement, en ajoutant des 0 supplémentaires à la valeur initiale. Il ne limitera pas la valeur absolue. Les espaces réservés aux valeurs aléatoires auront toujours la même longueur.

Étant donné que les valeurs séquentielles peuvent devenir plus grandes que la longueur minimale qui leur est allouée, vous ne devez pas ajuster la propriété StringAttributeMetadata.MaxLength pour qu’elle corresponde à la longueur de votre valeur mise en forme. Cette opération n’a que peu d’intérêt et peut entraîner une erreur à l’avenir si la valeur dépasse la valeur MaxLength . Assurez-vous de 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 auto-number.

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 auto-number, 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 en fonction de la longueur. De cette façon, la longueur de la valeur est toujours la même. Si vous souhaitez modifier la valeur initiale, vous devez modifier la valeur de départ initiale à l’aide de l’API ci-dessous pour définir le prochain numéro 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 numéro sera un chiffre unique avec un préfixe de zéros ajouté pour correspondre à la longueur du numéro. Une valeur de départ à un seul chiffre avec une longueur d’affichage de 5 entraînerait l’affichage de « 5 » sous la forme « 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 « 10000 », une valeur de 5 s’affichera comme « 10005 ».

Si vous souhaitez choisir une valeur de départ différente après avoir créé l’attribut de numérotation automatique, utilisez le message SetAutoNumberSeed . Utilisez la classe SetAutoNumberSeedRequest lors de l’utilisation des assemblys SDK et l’action SetAutoNumberSeed lors de l’utilisation de l’API Web.

Le message AutoNumberSeed comporte les paramètres suivants :

Exemples

Les exemples suivants définissent la valeur initiale 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

Requête

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
} 

Réponse

HTTP/1.1 204 No Content
OData-Version: 4.0

Outils de la communauté

Gestionnaire automatique de numéros

Le Gestionnaire automatique de numéros pour XrmToolBox est un outil communautaire pour Dynamics 365 Customer Engagement (sur site) qui fournit une interface utilisateur pour définir, mettre à jour et supprimer le format de numérotation automatique sur les attributs nouveaux ou existants. Consultez l’article Outils développeur pour les outils développés par la communauté et anm.xrmtoolbox.com pour plus d’informations sur le Gestionnaire de numéros automatiques.

Voir aussi

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