Nommage des documents

La clé primaire name

Tous les DocTypes de Frappe possèdent une clé primaire appelée name. C’est l’identifiant unique qui permet de retrouver les enregistrements et de les manipuler via l’ORM.

Méthodes de nommage

Vous pouvez configurer la façon dont les documents sont nommés lors de leur création. Le framework propose 9 méthodes de nommage (Naming Methods) :

1. Saisie par l’utilisateur (Set by user)

Le nom du document est saisi manuellement par l’utilisateur au moment de la création.

2. Auto-incrément (Autoincrement)

Le système génère un nom numérique séquentiel en incrémentant celui du dernier document créé.

Points importants :

• la numérotation commence à 1 ;
• sans garantie de continuité (not gap-safe) : les numéros des enregistrements supprimés ne sont pas réutilisés. Par exemple, si vous avez les documents 1, 2, 3, 4 et que vous supprimez 3, le document suivant sera nommé 5, et non 3 ;
• une fois cette méthode choisie, vous ne pouvez pas passer à un autre schéma de nommage, sauf si le DocType ne contient aucun document ;
• de même, vous ne pouvez pas passer d’un autre schéma à celui-ci, sauf si le DocType ne contient aucun document.

3. Par nom de champ (By fieldname)

Le nom du document est directement repris de la valeur d’un champ précis.

4. Par champ « Naming Series »

Le motif de nommage est dérivé d’un champ précis du document (en général naming_series).

Par exemple, si votre document possède un champ naming_series dont la valeur est PRE.#####, ce motif sert à générer le nom (p. ex. PRE00001). Cette valeur peut varier d’un document à l’autre : des documents d’un même DocType peuvent ainsi suivre des motifs différents.

5. Expression

Vous indiquez un motif de nommage standard qui sera incrémenté automatiquement.

Par exemple, avec le motif PRE-.##### :

• le premier document créé s’appellera PRE-00001 ;
• le deuxième PRE-00002 ;
• et ainsi de suite.

Cette méthode permet de configurer des schémas de nommage souples, combinant plusieurs valeurs de champs et variables. Les différentes parties sont séparées par un point ..

Exemple de motif :

EXAMPLE-.MM.-test-.{fieldname1}.-.{fieldname2}.-.#####

Ce format permet de combiner :

6. Expression (ancien style)

Il s’agit d’une méthode très souple pour configurer des schémas de nommage à partir de plusieurs valeurs de champs et variables. Le motif se saisit directement dans le champ Auto Name des paramètres du DocType.

Exemple de motif :

EXAMPLE-{MM}-test-{fieldname1}-{fieldname2}-{#####}

Ce format permet de combiner :

7. Aléatoire (Random)

Génère une chaîne alphanumérique aléatoire comme nom de document.

8. UUID

Utilise un identifiant unique universel généré aléatoirement (UUID v4) comme nom de document.

Exemple : 550e8400-e29b-41d4-a716-446655440000

9. Par script (By script)

Vous pouvez définir votre propre logique de nommage avec la méthode de contrôleur autoname dans le fichier Python de votre DocType. Vous avez ainsi un contrôle total sur le processus de nommage.

from frappe.model.naming import getseries

class Project(Document):
    def autoname(self):
    # select a project name based on customer
    prefix = f"P-{self.customer}"
    series = getseries(prefix, 3)
    self.name = f"{prefix}-{series}"

Par règle de nommage de document (Document Naming Rule)

Vous pouvez aussi créer des règles de nommage pour un DocType en créant des règles de nommage de document (Document Naming Rule).

Plusieurs règles peuvent être créées pour un même DocType et appliquées sélectivement selon des filtres.

Pour définir une Document Naming Rule, vous devez préciser :

1. le type de document (Document Type) auquel elle s’applique ;
2. la priorité de la règle (les règles de priorité la plus élevée s’appliquent en premier) ;
3. les conditions d’application de la règle ;
4. les règles de nommage proprement dites.

Numérotation

Vous pouvez définir différents préfixes de numérotation pour la règle selon les conditions définies, en indiquant un préfixe et un nombre de chiffres.

Par exemple, pour créer une numérotation distincte pour les tâches (ToDo) de haute priorité :

1. Préfixe : todo-high-
2. Chiffres : 3

Vous obtiendrez des noms comme todo-high-001, todo-high-002, etc.

Ordre de priorité du nommage

Lorsque plusieurs règles de nommage peuvent s’appliquer, le framework les hiérarchise dans cet ordre :

1. Document Naming Rule : définie dans la propriété autoname du DocType.
2. Méthode de contrôleur : logique définie dans la méthode autoname du script de contrôleur (elle prend le pas sur les paramètres du DocType si elle est définie).

Règles particulières

1. Les DocTypes enfants ne suivent pas les règles de nommage.
2. Les documents amendés (amended) portent un suffixe (-1, -2, etc.) ajouté au nom du document d’origine.

Pages liées

• Contrôleurs : la méthode autoname et les autres hooks de contrôleur.
• DocType enfant (table)