Où gérer les versions
La fiche d'un template (Templates, puis le template) liste ses versions dans l'onglet Versions : numéro, Statut, Changelog, Auteur, Date. La version la plus haute publiée porte le badge Version courante (latest).
Le menu Actions de chaque version propose ce que son statut et votre rôle permettent : Ouvrir, Comparer avec la version courante, Rendu de test, Publier, Revenir à cette version, Déprécier, Archiver, Abandonner le brouillon.
La page d'une version présente :
- Documentation : documentation générée de la version (contrat, jeux d'exemple avec aperçu, exemples d'appels, polices utilisées) ;
- Contrat de données : le JSON Schema des données attendues, validé à chaque appel ;
- Contenu : la description complète du document, en lecture seule.
Elle indique aussi l'Empreinte du contenu, le Moteur utilisé et, pour une version republiée, son Origine.
Publier le brouillon
- Sur la fiche du template, cliquez sur Publier le brouillon (ou sur Publier depuis la page du brouillon).
- Sculdoc fait une vérification à blanc : exactement les contrôles de la publication, sans rien publier.
- Lisez le résultat, rédigez le Changelog, puis cliquez sur Publier.
Ce que la vérification contrôle
Si l'un de ces points échoue, le dialogue affiche Le brouillon ne peut pas être publié en l'état avec la liste des problèmes, et le bouton Publier reste désactivé :
- le document est complet et valide ;
- le template a au moins un jeu d'exemple ;
- chaque sous-template est épinglé à une version publiée ;
- chaque image référencée existe ;
- le schéma des données couvre toutes les données lues par le template ;
- chaque jeu d'exemple respecte le schéma.
L'onglet Contrat de l'éditeur fait la même vérification en continu : corrigez-y les points signalés avant de publier (voir Contrat).
Avertissements
Les Avertissements de publication n'empêchent pas de publier mais méritent attention. Le cas le plus courant : une police demandée par le template n'existe ni dans votre organisation ni sur la plateforme, et elle est remplacée par une police de la plateforme (voir Polices).
Changements et contrat
Le dialogue résume les Changements par rapport à la version N (ajouts, modifications, déplacements, suppressions, réglages modifiés), ou indique Première publication de ce template. Si le contenu est identique à la dernière version, il le signale.
Les Changements cassants du contrat de données sont listés à part : un nouveau champ obligatoire, un type changé ou un champ devenu obligatoire font échouer les appels existants. Prévenez les équipes qui appellent le template avant de publier.
Changelog et numéro
Le Changelog est obligatoire et conservé avec la version : écrivez ce qui change pour les utilisateurs du template (« Ajout du numéro de TVA intracommunautaire », « Nouveau logo »). Les versions sont numérotées 1, 2, 3… dans l'ordre de publication ; un numéro n'est jamais réutilisé.
Après la publication, le brouillon devient la nouvelle version. Pour poursuivre les modifications, rouvrez l'éditeur : il propose de partir de la dernière version publiée.
Pour abandonner un brouillon sans le publier : Abandonner le brouillon. Les versions publiées ne changent pas.
Comparer deux versions
Ouvrez la comparaison par Comparer sur la fiche du template, Comparer avec la vN sur la page d'une version, ou Comparer avec la version courante dans le menu d'une version. Choisissez la Version de départ et la Version d'arrivée (le brouillon peut en faire partie).
| Onglet | Ce qu'il montre |
|---|---|
| Structure | Les éléments ajoutés, modifiés, déplacés ou supprimés, regroupés sous Corps du document ou sous chaque Gabarit de page « … », et les réglages modifiés. |
| Contrat de données | Chaque changement de champ (champ ajouté, champ supprimé, type changé, devenu obligatoire, devenu facultatif) avec sa compatibilité (Cassant ou Compatible) et le détail Avant → après. |
| Rendu | Les pages des deux versions côte à côte, rendues par le moteur avec un même Jeu d'exemple. |
Dans l'onglet Rendu, les différences entre les deux pages sont surlignées en rouge. Choisissez un jeu d'exemple commun aux deux versions, puis Rendre à nouveau si besoin. Seules les 20 premières pages sont comparées.
Déprécier et archiver
- Déprécier : la version reste utilisable par les appels qui la nomment par son numéro, mais n'est plus la version courante (latest). Utilisez-le pour annoncer son remplacement.
- Archiver : la version ne peut plus être rendue (un appel reçoit une erreur
410). Elle reste consultable pour l'audit, avec ses manifestes. Une version publiée ou dépréciée peut être archivée.
Ces deux actions sont confirmées par un dialogue, car elles touchent les applications qui appellent le template.
Revenir à une version
Pour revenir au contenu d'une version antérieure, ouvrez son menu et choisissez Revenir à cette version. Son contenu est republié comme une nouvelle version : l'historique n'est jamais réécrit.
- Le dialogue Revenir à la version N propose le changelog « Retour au contenu de la version N. » ; complétez-le si besoin.
- Cliquez sur Revenir à cette version.
Exemple : la version 4 pose problème ; revenir à la version 3 publie une version 5 identique à la 3, marquée Republication de la v3. Les applications qui appellent latest reçoivent la version 5 ; celles qui ont épinglé la version 4 la reçoivent toujours : changez leur numéro, ou archivez la version 4 pour la retirer.
Rendu de test
Un rendu de test vérifie une version (ou le brouillon) avec un jeu d'exemple, sans passer par une application.
- Sur la page d'une version, cliquez sur Rendu de test (ou utilisez le menu Actions de la version).
- Choisissez le Jeu d'exemple et le Profil de sortie : PDF standard, PDF/A (archivage) ou PDF/A + PDF/UA (accessible).
- Cliquez sur Rendu de test. Le résumé indique le nombre de pages, la taille et la durée ; Télécharger le PDF ou Voir le manifeste.
Le document est rendu par le moteur, stocké et inscrit au journal comme tout rendu. Une version archivée ne peut plus être rendue.
Journal des rendus
La section Rendus de la barre latérale liste tous les documents produits par votre organisation, depuis l'interface ou par l'API.
- Onglets Rendus et Jobs (lots de documents).
- Filtres : Template, Version, Période, Appelant (Utilisateur ou Clé d'API), Profil, Statut.
- Exporter en CSV télécharge le journal filtré.
La page d'un rendu montre son Manifeste (ce qui a produit le document : version, empreintes, moteur, polices, données), permet de télécharger le PDF et propose un Re-rendu de contrôle. Si le re-rendu est identique, le document est reproductible. Si les données du rendu n'ont pas été conservées, ce contrôle n'est possible que par l'API, en renvoyant les données.
La page d'un job montre sa progression, ses documents et les notifications envoyées.