Export/Import — Champs custom par client

Vue d'ensemble

Le module Export/Import s'adapte automatiquement aux champs personnalisés de chaque client. Plutôt que d'imposer un fichier Excel uniforme à tous les tenants, le système lit la configuration _fieldcustom du client connecté pour ajuster dynamiquement les colonnes, les libellés et les listes déroulantes proposées dans les fichiers exportés et acceptés à l'import.

L'objectif est double :

• Coller à la réalité métier de chaque client (libellés maison, listes de valeurs spécifiques, champs métiers activés ou non).
• Garder la rétrocompatibilité avec les anciens fichiers Excel produits avant cette évolution.

Pourquoi cette feature

Avant cette intégration, les exports/imports ISI affichaient les noms de colonnes techniques bruts (tpuser, lbcontract, etc.) et utilisaient les listes par défaut de la plateforme. Les clients qui personnalisaient leurs champs via le module Champ Custom (libellés renommés, valeurs de listes adaptées, champs custom1/custom2 activés) se retrouvaient avec des fichiers incohérents avec leur configuration applicative.

Désormais, l'export et l'import respectent la même configuration que celle visible dans l'interface : un champ renommé "Type de contrat" dans l'application apparaît "Type de contrat" dans le fichier Excel, avec exactement les mêmes valeurs proposées en liste déroulante.

Comportements pris en charge

Colonnes cachées

Un champ marqué comme caché dans la configuration _fieldcustom du client est automatiquement exclu des fichiers d'export et ignoré à l'import. Exception : les colonnes clés (identifiants techniques) et les colonnes en lecture seule restent toujours présentes — elles sont nécessaires au bon fonctionnement de l'import.

Libellés dynamiques

Les en-têtes du fichier Excel utilisent en priorité :

1. Le libellé personnalisé saisi par le client (_fieldcustom.lbintit).
2. Sinon le libellé traduit par défaut (_term.lbterm).
3. En dernier recours, le nom technique de la colonne.

Cela vaut aussi bien pour les fichiers exportés que pour l'écran de prévisualisation à l'import.

Listes déroulantes adaptées

Quand un champ est de type liste, la liste de valeurs proposée dans Excel suit la liste personnalisée du client (idlist_custom) plutôt que la liste plateforme par défaut. Si le client a créé sa propre liste de catégories, c'est cette liste-là qui apparaît dans le menu déroulant Excel et qui est validée à l'import.

Champs custom1 / custom2

Les colonnes génériques custom1 et custom2, masquées par défaut, peuvent être activées par client et configurées comme listes déroulantes. Une fois configurées, elles deviennent visibles dans l'export et acceptées à l'import comme n'importe quelle autre colonne.

Listes multi-valeurs (listmult)

Les champs qui acceptent plusieurs valeurs (séparées par des virgules) sont gérés des deux côtés : à l'export les codes sont traduits en libellés concaténés, à l'import les libellés sont reconnus et reconvertis en codes. À noter : Excel ne permet pas de mettre une vraie liste déroulante multi-sélection, donc la cellule reste libre, mais la validation à l'import vérifie que toutes les valeurs saisies existent.

Tables concernées

À ce jour, l'intégration des champs custom est active sur les exports/imports des entités suivantes :

Les autres tables continuent à fonctionner avec les noms de colonnes et listes par défaut tant qu'elles n'ont pas été migrées.

Round-trip export → import

Pour permettre de réimporter un fichier qui a été exporté avec des libellés personnalisés, le système ajoute une feuille technique cachée nommée _column_mapping dans le fichier Excel. Cette feuille fait le lien entre les libellés affichés dans les en-têtes et les noms techniques des colonnes.

Conséquences pour l'utilisateur :

• Un fichier exporté aujourd'hui peut être modifié dans Excel puis réimporté tel quel — le système retrouve les colonnes même si les libellés sont en français personnalisé.
• Un fichier ancien (sans la feuille _column_mapping) reste compatible : si le système ne trouve pas la feuille, il considère que les en-têtes sont les noms techniques, comme avant.

Cas particuliers

• Mode queue (job en arrière-plan) : la résolution de la configuration utilise l'identifiant tenant (_id) explicitement passé au job, pas la session — ce qui garantit que l'import lancé par un utilisateur s'effectue bien avec la config de son entité, même si le job tourne plus tard.
• Configuration vide : si une table n'a pas encore son mapping getFieldMapping() rempli, le système retombe sur le comportement historique (libellés bruts, listes par défaut) sans erreur.
• Listes multi-sélection : pas de menu déroulant Excel natif, mais validation à l'import.

Ce que voit l'utilisateur

Liens utiles

• Configuration des champs custom : voir docs/form/champ-custom.md
• Vue d'ensemble Export/Import : voir docs/platform/export-import.md

Doc technique : .claude/technical-docs/platform/export-import-field-custom.md