Un fichier YAML est une formation écrite en texte brut : son titre et ses réglages, puis chaque bloc dans l'ordre, corrigés compris. WeLearn en produit un lorsque vous sélectionnez Exporter, et le transforme de nouveau en formation lorsque vous sélectionnez Importer du YAML. Servez-vous-en pour :
- démarrer une nouvelle formation à partir d'une formation existante, puisqu'il n'existe aucun bouton pour dupliquer une formation entière ;
- conserver une copie d'une formation en dehors de WeLearn, par exemple dans un dépôt git à côté du contenu qu'elle enseigne ;
- écrire une formation dans un éditeur de texte, ou la faire écrire par un outil ou un assistant d'IA, et l'importer comme brouillon ;
- transmettre une formation à quelqu'un d'une autre organisation WeLearn.
Un import crée toujours un nouveau brouillon. Il ne modifie jamais une formation existante. Cette seule règle explique l'essentiel de cette page.
Un fichier transporte le contenu et les réglages, jamais l'historique
| Contenu dans le fichier | Absent du fichier |
|---|---|
| Titre, Description, Langue, difficulté, durée estimée | Les versions et l'étape de la formation (un import est toujours un brouillon) |
| Les thèmes, sous forme d'identifiants de cette organisation | Les auteurs et les crédits des personnes qui ont aidé |
| Les réglages de Lecture des évaluations : Tentatives, Affichage des résultats, Score de réussite | Les invitations, les liens d'invitation et les notes de relecture |
| Qui peut noter une relecture par les pairs (le réglage Relecteurs) | Le caractère obligatoire de la formation et sa période de certification |
| Chaque bloc, dans l'ordre, avec tout son texte | Les inscriptions, les résultats, les certificats, l'XP et les badges |
| Chaque corrigé : propositions correctes, bon ordre, paires, catégories, plages numériques, bon choix pour chaque trou, consignes aux relecteurs | L'édition en direct |
| Les liens vers les images téléversées dans le texte | Les images elles-mêmes |
La personne qui importe le fichier devient l'unique auteur du nouveau brouillon.
L'export télécharge la formation enregistrée, corrigés compris
Il existe deux boutons Exporter. Tous deux téléchargent un fichier nommé d'après le titre de la
formation, par exemple welearn-training-git-basics.yaml.
| Où | Ce qui est téléchargé | Qui voit le bouton |
|---|---|---|
| L'en-tête de l'éditeur | Le brouillon ou la révision que vous modifiez, tel qu'enregistré en dernier. Survolez Exporter pour afficher l'info-bulle du navigateur « Télécharger la version ENREGISTRÉE en YAML pour la réimporter, la versionner dans git ou la transmettre. Les modifications non enregistrées ne sont pas incluses. » | Toute personne qui peut modifier le brouillon |
| La page de la formation, à côté de Modifier et Archiver | La version affichée par cette page, quelle que soit son étape. Choisissez d'abord une version antérieure dans le sélecteur de version pour exporter celle-ci. Survolez Exporter pour afficher l'info-bulle du navigateur, qui se termine par « Le fichier contient les corrigés. » | Les auteurs de la formation ; les Managers et Administrateurs sur une formation ordinaire ; seuls les auteurs et les Administrateurs sur une formation obligatoire |
Avant d'exporter depuis l'éditeur, vérifiez que l'en-tête affiche Enregistré, ou sélectionnez Enregistrer. Sur la page d'une formation qui a une révision ouverte, Exporter télécharge la version publiée, pas la révision : exportez la révision depuis l'éditeur.
Le fichier commence par un bloc de commentaires, des lignes qui débutent par #, qui indique ce
qu'il est et ce qu'il laisse de côté. Lorsque la formation a des thèmes, ce commentaire liste
l'identifiant de chaque thème avec son nom. Lorsque le texte contient des images téléversées, il
avertit qu'elles ne sont pas dans le fichier.
Importer du YAML transforme un fichier en nouveau brouillon
Toute personne qui peut rédiger des formations peut en importer une.
- Ouvrez Mes formations › Créées et sélectionnez Importer du YAML (sur téléphone, l'icône de téléversement à côté de Nouvelle formation). La fenêtre Importer une formation depuis du YAML s'ouvre.
- Placez le YAML dans la grande zone de texte, de l'une de ces trois façons :
- collez-le ;
- sélectionnez Téléverser un fichier et choisissez un fichier
.yamlou.yml. Tout autre fichier est refusé avec Seuls les fichiers .yaml ou .yml sont pris en charge. ; - sélectionnez Charger le modèle pour remplir la zone avec le modèle annoté : chaque réglage et chaque type de bloc, avec sous chaque champ un commentaire qui indique ce qu'il accepte. Modifiez-le à partir de là.
- Sélectionnez Importer comme brouillon. Le bouton reste désactivé tant que la zone est vide.
En cas de succès, la fenêtre se ferme et le nouveau brouillon s'ouvre dans l'éditeur, sur Informations. Il figure aussi dans Mes formations › Créées, sous Brouillon. À partir de là, c'est un brouillon ordinaire : vérifiez-le dans Aperçu, corrigez ce que liste le panneau Préparation à la publication, et publiez-le comme décrit dans Publication, révisions et archivage.
L'import vérifie la forme du fichier, pas si la formation est prête à être publiée. Un brouillon peut entrer sans thème, sans langue, ou avec une banque de questions qui tire plus de questions qu'elle n'en contient. La vérification avant publication les détecte ensuite, avec les messages listés dans L'éditeur de formation.
Un import refusé nomme le champ en cause
Lorsque WeLearn refuse le fichier, rien n'est créé et un message rouge apparaît au-dessus des boutons. Il reste affiché jusqu'à ce que vous modifiiez le texte. Le message indique de quel type de problème il s'agit :
| Message | Ce qu'il signifie | Que faire |
|---|---|---|
| The request was invalid. | Le texte n'est pas du YAML valide. | Vérifiez l'indentation (des espaces, jamais de tabulations) et les guillemets ouverts mais jamais fermés. |
| Corps de requête invalide : champ 'x' inconnu. | Une clé que le format ne connaît pas, généralement une faute de frappe. | Comparez l'orthographe avec le modèle. Les clés sont sensibles à la casse. |
| Corps de requête invalide : valeur incorrecte pour le champ 'x'. | La clé est correcte mais sa valeur n'est pas du bon type, par exemple du texte là où un nombre est attendu, ou difficulty: Easy au lieu de EASY. |
Vérifiez dans le modèle ce que ce champ accepte. |
| Une liste telle que elements[2].title: must not be blank, passingThreshold: passingThreshold must be 0-100 (inclusive) | Le fichier a été lu, et ces champs enfreignent une règle. | Corrigez chacun d'eux. Les blocs sont comptés à partir de 0 : elements[2] est le troisième bloc. |
| L'import YAML ne reconnaît pas le type d'élément 'x'. | Un type de bloc qui n'existe pas. |
Utilisez l'un des neuf types du tableau ci-dessous. Le message en liste huit : PEER_REVIEW est accepté aussi. |
| Identifiants de thématique inconnus : … | Un identifiant de thème qui n'existe pas dans cette organisation. | Retirez-le, ou remplacez-le par l'identifiant d'un thème d'ici. |
| La langue demandée n'est pas prise en charge. | Une language autre que en ou fr. |
Utilisez en ou fr, ou supprimez la ligne. |
| Échec de l'import. Vérifiez votre YAML et réessayez. | WeLearn n'a donné aucun détail. | Comparez le fichier au modèle et réessayez. |
Les règles qu'un fichier doit respecter pour être importé :
- la formation a un
title(200 caractères au plus) et unedescription(2 000 au plus) ; - 100 blocs au plus ;
- chaque bloc a un
typeet untitle, et les champs de texte que son type exige (voir plus bas) ; - un quiz a au moins une question ; chaque question a un texte et au moins deux propositions, dont une ou plusieurs correctes ;
- un Ordonnancement a de 3 à 100 éléments ; une Association de 2 à 100 paires, les deux côtés remplis ;
- une Catégorisation a au moins une catégorie et un élément, et chaque élément désigne une catégorie par son identifiant ;
- un Numérique a à la fois
minetmax, etminn'est pas supérieur àmax; - un Texte à trous a au moins un trou ; chaque trou a au moins deux choix, dont exactement un correct ;
- chaque lien a un titre et une adresse complète en
http://ouhttps://; maxAttemptsva de 0 à 20, etpassingThresholdde 0 à 100.
Le fichier en termes simples
Le haut du fichier contient les réglages
Chaque ligne est une clé, deux-points, et une valeur. Les lignes qui commencent par # sont des
commentaires et sont ignorées.
| Clé | Équivalent dans l'éditeur | Valeurs | Si elle est absente |
|---|---|---|---|
title |
Titre | Texte, obligatoire | Refusé |
description |
Description | Texte, HTML simple autorisé, obligatoire | Refusé |
language |
Langue | en (Anglais) ou fr (Français) |
Aucune langue : le brouillon est importé, la publication en demande une |
difficulty |
Difficulté | EVERYONE, EASY, MEDIUM, HARD |
EVERYONE |
estimatedMinutes |
Durée estimée | Un nombre entier de minutes | 0 |
thematicIds |
Thèmes | Une liste d'identifiants de thèmes de cette organisation | Aucun thème : la publication en demande un |
maxAttempts |
Tentatives | De 1 à 20, ou 0 pour illimité (∞) | 1 |
delayedFeedback |
Affichage des résultats | false pour Immédiat, true pour À la fin |
Immédiat |
passingThreshold |
Score de réussite | De 0 à 100 ; 0 correspond à Aucun seuil | Aucun seuil |
reviewerUserIds, reviewerGroupIds |
Relecteurs, pour les relectures par les pairs | Listes d'identifiants de membres et de groupes de cette organisation | Les auteurs de la formation notent |
elements |
Les blocs | La liste des blocs, dans l'ordre | Aucun bloc |
L'éditeur propose 1, 2, 3, 5 ou ∞ tentatives, mais un fichier peut en demander n'importe quel
nombre jusqu'à 20, par exemple maxAttempts: 4 ; l'éditeur affiche alors ce nombre parmi ses
choix. Un fichier plus ancien peut porter retakeable au lieu de maxAttempts : il est toujours
lu, true comme 3 tentatives et false comme 1.
Chaque bloc commence par son type
type |
Bloc dans l'éditeur | Champs en plus de title |
|---|---|---|
COURSE |
Texte | content |
EXTERNAL_LINK |
Lien | description (facultatif), links, chacun avec title et url |
QUIZ |
Quiz | questions, servedQuestionCount (facultatif, pour une banque de questions) |
ORDERING |
Ordonnancement | prompt, items dans l'ordre correct, explanation (facultatif) |
MATCHING |
Association | prompt, pairs, chacune avec left et right |
CATEGORIZATION |
Catégorisation | prompt, buckets avec bucketId et name, items avec value et bucketId |
NUMERIC |
Numérique | prompt, min, max, explanation (facultatif). Pour Exact, donnez la même valeur à min et max |
CLOZE |
Texte à trous | richText, avec un marqueur {{blank:<blankId>}} par trou, et blanks, chacun avec blankId et propositions |
PEER_REVIEW |
Relecture par les pairs | prompt (la Consigne), reviewerGuidelines (facultatif) |
Le modèle obtenu avec Charger le modèle montre un exemple complet et commenté de chacun.
Un exemple annoté
Une formation avec un bloc Texte et un quiz d'une question :
title: "Git basics"
description: "<p>Commit and branch with confidence.</p>"
language: en # en ou fr
difficulty: EASY # EVERYONE, EASY, MEDIUM ou HARD
estimatedMinutes: 30
maxAttempts: 3 # 0 = illimité
delayedFeedback: false # false = Immédiat, true = À la fin
passingThreshold: 80 # 0 = Aucun seuil
elements:
- type: COURSE # un bloc Texte
title: "What a commit is"
content: "<p>A commit records a snapshot of your files.</p><ul><li>It has a message.</li><li>It points to its parent.</li></ul>"
- type: QUIZ
title: "Knowledge check"
questions:
- value: "Which command records your staged changes?"
explanation: "git commit turns what you staged into a new commit."
point: 1 # facultatif, 1 si absent
propositions:
- value: "git commit"
correct: true
- value: "git push"
correct: false
- value: "git status"
correct: falseIl s'importe tel quel. Le nouveau brouillon a ensuite besoin d'un thème avant de pouvoir être
publié, puisque l'exemple n'a pas de thematicIds.
Le texte est du HTML, écrit entre guillemets
Les blocs Texte, les descriptions, les consignes de relecture par les pairs et les textes à trous
sont en HTML : <p> pour les paragraphes, <strong>, <em> et <u> pour la mise en valeur,
<ul>, <ol> et <li> pour les listes, <br> pour un retour à la ligne. Pour voir comment
l'éditeur écrit une mise en forme plus riche, réalisez-la dans un brouillon et exportez-le.
Mettez chaque valeur de texte entre guillemets doubles, comme le fait le modèle. Sans eux, un
deux-points dans une phrase peut casser le fichier, et une valeur comme true ou 007 peut être
lue comme autre chose que du texte, ce qui modifie une réponse sans prévenir.
Les identifiants peuvent rester ou partir, sauf deux sortes
Un export écrit un identifiant sur tout : blocs, questions, propositions, éléments. Au sein d'un même
fichier, vous pouvez les laisser tels quels, les supprimer ou les mettre à null : WeLearn en crée
de nouveaux là où ils manquent. Un bloc que vous ajoutez à la main n'en a pas besoin.
Deux sortes d'identifiants doivent rester, parce que d'autres parties du fichier y renvoient :
- Catégorisation : le
bucketIdde chaque catégorie, auquel renvoie lebucketIdde chaque élément. C'est le corrigé. Tout identifiant au format 8-4-4-4-12 convient, par exemple11111111-1111-1111-1111-111111111111, tant que l'élément utilise le même. - Texte à trous : le
blankIdde chaque trou, qui doit aussi figurer dansrichTextsous la forme{{blank:<blankId>}}. Un marqueur sans trou correspondant, ou un trou sans marqueur, s'importe, mais la vérification avant publication refuse ensuite de publier.
Copier une formation, c'est un export suivi d'un import
- Exportez la formation avec Exporter : depuis sa page pour une version publiée, depuis l'éditeur pour un brouillon.
- Ouvrez le fichier et modifiez ce qui doit différer, au moins le
title, pour ne pas confondre les deux formations dans le Catalogue. - Dans Mes formations › Créées, sélectionnez Importer du YAML, puis Téléverser un fichier, puis Importer comme brouillon.
- Travaillez sur la copie dans l'éditeur, et publiez-la quand elle est prête.
La copie est une formation distincte dès le départ. Les apprenants de l'original y conservent leur progression et leurs résultats. Rien de ce que vous faites sur l'une n'atteint jamais l'autre.
Dans la même organisation
La copie conserve ses thèmes, ses relecteurs pour la relecture par les pairs et ses images, puisqu'ils existent tous ici. Elle n'a pas de crédits, et vous en êtes l'unique auteur. Pour y travailler avec les auteurs de l'original, invitez-les comme décrit dans Co-écrire et relire un brouillon.
Dans une autre organisation
Les identifiants de thèmes, de membres et de groupes appartiennent à l'organisation qui les a exportés.
| Dans le fichier | Avant d'importer ailleurs |
|---|---|
thematicIds |
Mettez-le à [] et choisissez les thèmes dans l'éditeur ensuite. Sinon l'import est refusé avec Identifiants de thématique inconnus. Le commentaire en haut du fichier nomme chaque thème, pour vous aider à trouver son équivalent. |
reviewerUserIds, reviewerGroupIds |
Mettez les deux à []. L'import ne les vérifie pas : des identifiants venus d'ailleurs laisseraient une relecture par les pairs que personne ici ne peut noter. Vides, ce sont les auteurs de la formation qui notent. |
| Images téléversées | Elles pointent toujours vers l'organisation d'origine et s'affichent cassées. Téléversez-les de nouveau dans l'éditeur. |
Qui peut faire quoi
| Action | Employé | Manager | Administrateur |
|---|---|---|---|
| Importer un fichier comme nouveau brouillon | Oui | Oui | Oui |
| Exporter une formation dont il est l'auteur, ou un brouillon qu'il est invité à modifier | Oui | Oui | Oui |
| Exporter une formation ordinaire dont il n'est pas l'auteur | Non | Oui | Oui |
| Exporter une formation obligatoire dont il n'est pas l'auteur | Non | Non | Oui, et c'est consigné |
Liste de contrôle
- Avant d'exporter depuis l'éditeur, l'en-tête affiche Enregistré.
- Le fichier est stocké là où seuls les auteurs peuvent le lire.
- Le titre dans le fichier indique qu'il s'agit d'une copie, si l'original reste en usage.
- Les thèmes, les relecteurs et les images sont traités, si le fichier part vers une autre organisation.
- Après l'import, le brouillon a une langue et au moins un thème.
- Vous avez joué chaque exercice dans Aperçu et obtenu 100 % avec votre propre corrigé.
- Le panneau Préparation à la publication affiche Tout est prêt. Cette formation peut être publiée.
Pièges
- Exporter depuis la page alors qu'une révision est ouverte vous donne la version publiée. Exportez depuis l'éditeur pour obtenir la révision.
- Copier un fichier d'une organisation à l'autre sans vider les identifiants est refusé pour les thèmes et laisse des relectures par les pairs que personne ne peut noter.
- Oublier
languagepasse à l'import puis bloque la publication avec Indiquez la langue dans laquelle la formation est rédigée. - Compter les blocs à partir de 1 dans un message d'erreur.
elements[0]est le premier bloc.
Pages liées
- Publication, révisions et archivage : modifier une formation sur place, et pourquoi l'archivage est irréversible.
- L'éditeur de formation : la vérification avant publication que traverse chaque brouillon importé.
- Créer des évaluations : ce que signifie chaque corrigé du fichier.
- Référence des blocs de contenu : copier des blocs isolés d'une formation à l'autre sans fichier.
- Rédiger avec un assistant d'IA : un assistant écrit le même format.