Les échanges avec d’autres plateformes

Comment une plateforme (votre logiciel, une autre application, QaTrax) dépose la trame de chaque version par le protocole REST, et comment les clés d’échange se gèrent à l’écran.

À quoi servent les échanges

Une plateforme dépose la trame de chaque version de son logiciel, c'est-à-dire ses fiches de prise en main et de configuration par rôle. Elle le fait par le protocole REST /echange/v1, sans que personne ait à synchroniser à la main. La campagne de formation du projet suit la version :

chaque personne garde son feuillet et ses réponses ;
les lignes ajoutées y apparaissent « nouveau » ;
les lignes modifiées reviennent « à revoir — modifié », avec le texte d'avant ;
le reste demeure acquis.

La trame d'un logiciel fait aussi vivre la formation de chaque entreprise qui l'utilise. Chaque entreprise garde ses personnes et leurs réponses.

Les clés d’échange

Sur la page du projet (un logiciel), la carte Échanges avec la plateforme dit combien de clés sont actives et quand elles ont servi ; son bouton Gérer les clés d’échange est réservé au responsable du projet (les autres membres y lisent pourquoi).

Sur la formation d’une entreprise, la même carte mène aux échanges de son logiciel (Ouvrir les échanges du logiciel …) : c’est là que se crée la clé.

Créer la clé : un libellé (par exemple « Guerway — instance de formation »), ses portées (déposer les trames, lire les campagnes…), et, si la plateforme signe ses trames, sa clé publique.
La clé est gardée chiffrée dans la base. Afficher la montre de nouveau, pour la recopier dans la plateforme.
Régénérer donne une clé neuve, et l'ancienne cesse aussitôt de valoir. Révoquer l'arrête.
La colonne Dernier usage dit quand la plateforme s'en est servie.

Une clé ne vaut que pour son projet. La formation d'une entreprise n'a pas de clé : elle reçoit la trame de son logiciel.

La source des médias

La trame donne l'adresse de ses films une seule fois, la source (par exemple https://medias.mostajs.dev/<projet>/), et chaque ligne le seul nom de son fichier. ValiTrax recompose l'adresse au moment d'afficher le feuillet.

Sur la page du logiciel, carte Échanges avec la plateforme, le champ Source des médias la remplace pour toutes ses campagnes, et pour la formation de chaque entreprise qui l'utilise.
Installer les films chez un client : recopier le dossier des fichiers tel quel, puis poser la nouvelle source (https://…/, terminée par une barre). Aucune réimportation : les lignes gardent leurs noms, aucune ne devient « modifiée », les réponses restent.
Laisser le champ vide revient à la source de la trame.

La première fois

Au premier dépôt, la campagne de formation déjà ouverte pour le projet est adoptée : elle devient vivante, et l'équipe garde tout ce qu'elle a déjà coché. Aucune campagne en double n'est créée.

Pour le développeur de la plateforme

La description complète est à l'adresse /echange/v1/openapi.json.
On dépose la trame par PUT /echange/v1/trames/formation/<version>, avec l'en-tête Authorization: Bearer <clé> et une trame mostajs-devtest/1 comme corps.
La réponse est un bilan : lignes nouvelles, modifiées, inchangées et retirées, feuillets rouverts, entreprises mises à jour.
La trame de recette se dépose signée, car le procès-verbal en dépend.
Les clients JavaScript sont fournis par @mostajs/recette/echange. Ceux d'autres langages suivront.