> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.goodflag.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.goodflag.com/_mcp/server.

# Métadonnées

> Les trois niveaux, dataMapping, dispositions, usages

# Métadonnées

Les **métadonnées** attachent à un parapheur des informations métier **structurées**. Leur
grande force : elles sont **accessibles par de multiples fonctions**. On peut les utiliser
pour **personnaliser les messages**, pour composer le **texte de la signature visible**, et
plus généralement pour **piloter le cycle de vie** du parapheur en liaison avec vos
applications métier — en **amont** comme en **aval** de la signature. Elles permettent aussi
d'intégrer des caractéristiques utilisées pour **archiver** le parapheur et son dossier de
preuve **en cohérence avec un plan d'archivage**, et servent enfin à **indexer, filtrer et
rechercher** vos parapheurs.

**Pourquoi seulement seize emplacements ?** Ce n'est pas une limite arbitraire : les emplacements
`data1` … `data16` correspondent aux **clés analytiques fortes** de votre organisation — les axes
selon lesquels votre activité se pilote réellement. Numéro de client, SIREN, numéro de sécurité
sociale, numéro de département, type d'entité (client, fournisseur, partenaire, auditeur…), région
commerciale : des données **métier essentielles**, stables et partagées, et non des champs de
commodité propres à un dossier. Seize suffisent précisément parce qu'au-delà, on ne décrit plus
des axes d'analyse mais des détails de cas particulier.

Le dictionnaire est donc à concevoir comme un **référentiel d'entreprise** : ce que vous y
inscrivez engage toutes les applications qui s'adressent à votre tenant.

## Trois niveaux

* **Le dictionnaire (`dataMapping`)** — au niveau du tenant, définit la **signification** de
  chaque emplacement `data1` … `data16` (libellé, type, validation).
* **La disposition de métadonnées** (« layout », identifiant `lay_`) — une **sélection**
  d'emplacements assortie de leur configuration (valeur par défaut, obligatoire ou non,
  lecture seule…). C'est ce que `layoutId` désigne sur un parapheur. Une disposition **catégorise**
  un parapheur par une **combinaison** d'emplacements : celle qui fait sens pour piloter son cycle
  de vie. Un marché public ne se caractérise pas par les mêmes clés qu'un dossier RH, et c'est
  précisément ce que la disposition exprime. Un même emplacement peut donc être référencé par
  plusieurs dispositions : elles se partagent le dictionnaire sans se l'approprier.
* **Les valeurs** (`data1` … `data16`) — les valeurs effectives portées par un parapheur.

## Le dictionnaire des emplacements (`dataMapping`)

Le dictionnaire est **au niveau du tenant** et couvre les **16 emplacements** `data1` … `data16`.

À la livraison de votre tenant, ce dictionnaire est **vide** : aucun emplacement n'est nommé, et aucune disposition n'existe. Contrairement aux pages de consentement ou aux gabarits de message, qui vous arrivent préconfigurés, les métadonnées sont **entièrement les vôtres** — c'est vous qui décidez quelles clés de votre activité méritent une place, et sous quel libellé.

> ⚠️ **Le dictionnaire ne se renseigne que par l'API.** Le Portail permet de créer et de gérer
> les **dispositions**, mais **pas** de définir les emplacements eux-mêmes : nommer `data10`,
> lui donner un type et sa liste de valeurs passe obligatoirement par `PUT /api/tenants/{tenantId}/dataMapping`.
> C'est l'une de ces opérations réservées à l'API (voir *Positionnement & périmètre*), et la
> confusion coûte cher : on cherche longtemps dans l'interface un écran qui n'existe pas, ou pire,
> on croit qu'une disposition suffit à créer la métadonnée qu'elle prescrit.

* **Consulter** : `GET /api/tenants/{tenantId}/dataMapping`.
* **Mettre à jour** : `PUT /api/tenants/{tenantId}/dataMapping` — **remplacement complet** (le
  corps décrit l'ensemble des emplacements voulus ; un emplacement absent du corps est retiré).
  C'est une **opération d'administration du tenant** (rôle d'administration des métadonnées — voir
  la fondation [*Groupes, rôles & droits*](/wm/api-reference/concepts/groupes-roles-droits)).

**Attention** : le dictionnaire étant au niveau du tenant, ces 16 emplacements sont une
**ressource partagée** par toutes les applications qui s'adressent à lui. Deux conséquences
pratiques. D'abord, **inventoriez avant de réserver** : un emplacement déjà porteur d'une donnée
métier ne doit pas être réutilisé, sans quoi l'application qui s'en sert verrait sa donnée
écrasée, et toute logique branchée sur la présence de cet emplacement se déclencherait à
contretemps. Ensuite, le remplacement complet évoqué ci-dessus impose de **relire le dictionnaire,
d'y ajouter votre emplacement, puis de le renvoyer entier** — un corps ne contenant que votre
ajout effacerait tous les autres.

Chaque emplacement se définit par :

| Champ         | Rôle                                                                                     |
| ------------- | ---------------------------------------------------------------------------------------- |
| `name`        | Libellé de l'emplacement.                                                                |
| `description` | Description.                                                                             |
| `type`        | `text`, `textarea`, `checkbox` ou `select`.                                              |
| `pattern`     | Expression régulière de validation (ex. `^\d{4,8}$`).                                    |
| `options`     | Pour un `select` : liste de valeurs — avec `parentValue` pour des listes **en cascade**. |
| `parent`      | Emplacement parent (listes dépendantes, ex. *Région* → *Département*).                   |

## Les dispositions (« layouts », `lay_`)

`POST /api/tenants/{tenantId}/layouts` — une disposition nomme et configure les emplacements
retenus :

| Champ                   | Rôle                                                 |
| ----------------------- | ---------------------------------------------------- |
| `name`                  | Nom de la disposition.                               |
| `dataConfigurations[]`  | Configuration, emplacement par emplacement.          |
| `…[].slot`              | L'emplacement concerné (`data1` …).                  |
| `…[].default`           | Valeur par défaut.                                   |
| `…[].optional`          | Valeur obligatoire ou non.                           |
| `…[].readonly`          | Non modifiable.                                      |
| `…[].rememberLastValue` | Mémoriser la dernière valeur saisie par le créateur. |

* **Lister** : `GET /api/layouts` (pagination `itemsPerPage` / `pageIndex`) — indispensable pour
  inventorier l'existant, et pour rendre une création **idempotente** en cherchant d'abord une
  disposition du même `name`. Noter la dissymétrie des adresses : la **lecture** est globale, la
  **création** est portée par le tenant.

Une disposition se référence sur un parapheur par `layoutId` (voir la fondation
*Parapheurs*), et son usage peut être **cadré par groupe** (`layoutSelectionMode` /
`allowedLayouts`, voir la fondation [*Groupes, rôles & droits*](/wm/api-reference/concepts/groupes-roles-droits)).

Une disposition peut ne référencer **aucun** emplacement : elle est alors sans effet sur les
métadonnées du parapheur.

## Renseigner les valeurs

Les **valeurs** sont portées par le parapheur via les champs `data1` … `data16` (voir la
fondation [*Parapheurs*](/wm/guides/integration/creer-un-parapheur)). Elles doivent respecter la définition de l'emplacement
(type, `pattern`, `options`…) et la configuration de la disposition (obligatoire, lecture
seule…).

**Attention — les valeurs exigent `layoutId` dans la même requête.** Des valeurs `dataN` envoyées
**sans** `layoutId` sont **silencieusement ignorées** : la requête aboutit sans la moindre erreur,
le parapheur est bien créé, mais il ne porte **aucune métadonnée**. Rien ne signale la perte, et
tout ce qui en dépend se dégrade en silence — au premier chef la personnalisation des messages,
qui retombe sur les modèles par défaut. Envoyez donc toujours la disposition **et** les valeurs
**ensemble**, et vérifiez à la relecture du parapheur que les métadonnées y figurent.

## À quoi servent les métadonnées

* **Catégoriser** le parapheur par une combinaison de clés qui fait sens pour votre activité —
  c'est le rôle de la disposition, et le point de départ de tous les usages qui suivent.
* **Personnaliser les messages** adressés aux destinataires.
* **Alimenter le cartouche** de signature (`{{data1}}`… dans le gabarit — voir la fondation
  *Profils de signature*).
* **Piloter le cycle de vie** du parapheur en liaison avec vos applications métier, en amont
  et en aval de la signature.
* **Indexer, filtrer et rechercher** les parapheurs.
* Porter des caractéristiques d'**archivage** du parapheur et du dossier de preuve, en
  cohérence avec un plan d'archivage.