---
title: "Export/Import — Champs custom par client"
module: platform
type: functional
status: active
updated: 2026-05-22
---

# 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 :

| Table | idpart | Domaine |
|---|---|---|
| `users` | 1200 | Utilisateurs |
| `customer` | 1300 | Clients/Entités |
| `customer_addr` | 1304 | Adresses clients |

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

| Étape | Avant | Après |
|---|---|---|
| Téléchargement du modèle | En-têtes techniques (`tpuser`) | Libellés métier (`Type d'utilisateur`) |
| Listes déroulantes | Valeurs plateforme par défaut | Valeurs configurées dans Champ Custom |
| Colonnes affichées | Toutes les colonnes plateforme | Uniquement celles non cachées par le client |
| Réimport d'un export | Incertain si libellés modifiés | Reconnaissance automatique via la feuille de mapping |

## 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](../../.claude/technical-docs/platform/export-import-field-custom.md)