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).

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 :

Les dispositions (« layouts », lay_)

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

• 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).

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). 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.