Organisation
Tout ce que vous créez dans Sculdoc appartient à une organisation : dossiers, templates, versions, polices, images, documents rendus, manifestes, clés d'API et webhooks. Une organisation ne voit jamais les ressources d'une autre.
Un utilisateur peut appartenir à plusieurs organisations, avec un rôle dans chacune. Il travaille dans une organisation à la fois et en change par Changer d'organisation dans la barre latérale.
Rôles
| Rôle | Ce qu'il permet |
|---|---|
| Lecteur | Consulter les dossiers, les templates, leurs versions, leurs contrats, les rendus et les documents. |
| Éditeur | En plus : organiser les dossiers et les templates (créer, renommer, déplacer, dupliquer, supprimer), modifier les brouillons, déposer des images et des polices, publier, déprécier, archiver, revenir à une version, faire des rendus. |
| Administrateur | En plus : gérer les membres et les invitations, les clés d'API, les webhooks et les réglages de l'organisation. |
| Propriétaire | Les mêmes droits que l'administrateur. |
La page Membres (administrateurs) permet d'Inviter une personne, de Changer le rôle d'un membre ou de le Retirer. Un membre arrivé par son fournisseur d'identité reçoit un rôle calculé à chaque connexion à partir des informations du fournisseur ; si vous changez ce rôle à la main, il ne suit plus ces informations.
Un Administrateur de plateforme (équipe Sculdoc) règle en plus les quotas des organisations et les règles d'attribution des rôles par fournisseur d'identité.
Dossiers
Les templates se rangent dans une arborescence de Dossiers, propre à chaque organisation.
- Pour créer un dossier : Nouveau dossier, ou Nouveau sous-dossier depuis le menu d'un dossier.
- Pour déplacer un dossier ou un template : glissez-le sur un dossier de l'arbre, ou utilisez Déplacer.
- Seul un dossier vide peut être supprimé : déplacez d'abord ses templates et ses sous-dossiers.
- Tous les templates affiche l'ensemble ; la recherche porte sur tous les dossiers.
Les dossiers servent aussi à limiter une clé d'API : une clé portée à un dossier ne voit que les templates de ce dossier et de ses sous-dossiers (voir Clés d'API).
Template
Un template est le modèle d'un document. Il porte un Nom, un Identifiant (utilisé par les appels d'API, par exemple facture-client) et une Description.
Un template contient sa mise en page, ses textes, ses images, ses tableaux, sa logique (conditions, répétitions) et ses jeux d'exemple. Il ne contient jamais de code exécutable.
Depuis la fiche d'un template, vous pouvez le Dupliquer, le Déplacer, modifier son Nom et description, ou le Supprimer. Un template supprimé disparaît des listes, mais ses versions publiées et les manifestes de ses rendus sont conservés pour l'audit. Changer l'identifiant d'un template oblige à mettre à jour les applications qui l'appellent.
Versions
Un template évolue par versions numérotées : 1, 2, 3…
| Statut | Signification |
|---|---|
| Brouillon | Le contenu en cours de modification. Un template a au plus un brouillon ; c'est lui que l'éditeur modifie. |
| Publiée | Version figée, appelable par les applications. La plus haute version publiée est la Version courante (latest). |
| Dépréciée | Encore rendue pour les appels qui la nomment par son numéro, mais plus proposée par défaut. |
| Archivée | Ne peut plus être rendue. Elle reste consultable pour l'audit, avec ses manifestes. |
Points essentiels :
- Une version publiée est immuable : même numéro et mêmes données donnent le même document, aujourd'hui comme dans plusieurs années. Elle est close sur tout ce dont elle dépend (images, polices, sous-templates, version du moteur), identifiés par leur empreinte.
- Chaque publication exige un changelog qui explique ce qui change pour les utilisateurs du template.
- Revenir en arrière ne réécrit jamais l'historique : le contenu d'une ancienne version est republié comme une nouvelle version.
Le cycle de vie complet est décrit dans Publication et versions.
Jeu d'exemple
Un jeu d'exemple est un jeu de données nommé (par exemple facture ou client-particulier) enregistré avec le template. Il sert à :
- alimenter la preview de l'éditeur ;
- faire des rendus de test ;
- générer la documentation de la version et la comparaison visuelle de deux versions ;
- vérifier le contrat : à la publication, chaque jeu doit respecter le schéma des données.
Un template doit avoir au moins un jeu d'exemple pour être publié. Les jeux se gèrent dans l'onglet Données de l'éditeur (voir Jeux d'exemple).
Contrat de données
Le contrat de données décrit les données qu'une version attend : noms des champs, types (texte, nombre, date, liste…), champs obligatoires. Techniquement, c'est un JSON Schema.
- Il est dérivé automatiquement des variables utilisées par le template et des jeux d'exemple. Vous pouvez l'annoter (titre, description, exemple, obligatoire) dans l'onglet Contrat de l'éditeur.
- Il est vérifié à la publication, puis à chaque appel : des données hors contrat sont refusées avant le rendu, avec le chemin exact du champ en cause (par exemple
$.items[2].total). - Entre deux versions, un changement de contrat est compatible (les appels existants continuent de fonctionner) ou cassant (nouveau champ obligatoire, type changé, champ devenu obligatoire).
Le contrat de chaque version est consultable dans l'onglet Contrat de données de la page de la version.
Profils de sortie
Le profil de sortie détermine la nature du PDF produit.
| Profil | Valeur de l'API | Usage |
|---|---|---|
| PDF standard | standard |
Document courant. |
| PDF/A (archivage) | archive |
Conservation à long terme : polices embarquées, format normalisé (PDF/A-2b). |
| PDF/A + PDF/UA (accessible) | accessible |
Archivage et accessibilité : structure balisée et ordre de lecture pour les lecteurs d'écran (PDF/A-2a et PDF/UA-1). |
Le profil par défaut se règle dans les propriétés du Document (propriété Profil de sortie). Un rendu de test ou un appel d'API peut en demander un autre.
Rendus et manifestes
Un rendu produit un PDF à partir d'une version (ou du brouillon, pour un essai) et de données. Sculdoc valide les données, fait la mise en page avec son moteur, applique le profil de sortie, stocke le PDF et l'inscrit au journal.
Chaque rendu produit un manifeste : ce qui a produit le document (version, empreinte du contenu, empreinte des données, moteur, polices, post-traitement). Le PDF stocké fait foi.
Dans Rendus, chaque rendu montre son manifeste, permet de télécharger le document et propose un Re-rendu de contrôle : Sculdoc rend à nouveau la même version avec les mêmes données et indique si le résultat est identique au document stocké.
Les rendus d'un grand nombre de documents passent par des jobs (lots), décrits dans Clés d'API et intégration.