Diese Anleitung richtet sich an die Administration von Moodle und an Trainer. Das Plugin ergänzt Moodle um die Aktivität „Virtualbadge“. Sie verknüpft einen Kurs mit einer Vorlage in Virtualbadge.io. Erfüllen Teilnehmer die Bedingung, stellt Moodle den Nachweis im Hintergrund aus und zeigt den Link in der Aktivität. Design, Felder und E-Mail der Vorlage legen Sie weiter in Virtualbadge.io fest, zum Beispiel im Designer.
Die Bezeichnungen des Plugins sind in Version 1.1.4 englisch, auch in einem deutschsprachigen Moodle. Diese Anleitung nennt sie deshalb auf Englisch, die Menüs von Moodle selbst auf Deutsch. Die Bilder zeigen Moodle mit englischer Oberfläche und Musterdaten.
| Punkt | Anforderung |
|---|---|
| Moodle | Version 4.5 bis 5.3 mit PostgreSQL, MariaDB oder MySQL |
| Betrieb | Der Cron von Moodle läuft mindestens einmal pro Minute |
| Netz | Ausgehende Verbindung per HTTPS zu api.virtualbadge.io, Port 443. Eingehende Freigaben in der Firewall sind nicht nötig |
| Virtualbadge.io | Organisation mit API-Zugriff, mindestens eine aktive Vorlage, genug Credits |
| Kurs | Kursabschluss eingerichtet oder ein bewerteter Test, je nach Auslöser |
Schritt 1: Plugin in Moodle installieren
Die ZIP-Datei des Plugins erhalten Sie von Virtualbadge.io. Fehlt sie Ihnen noch, schreiben Sie uns über die Kontaktseite.
Melden Sie sich in Moodle als Administrator an und öffnen Sie „Website-Administration“, dann „Plugins“ und „Plugins installieren“. Laden Sie die ZIP-Datei hoch und starten Sie die Installation. Bestätigen Sie die Prüfung des Plugins und danach die Aktualisierung der Datenbank.
Ist die Installation über die Oberfläche auf Ihrem Server abgeschaltet, entpackt Ihre IT den Ordner „virtualbadge“ aus der ZIP-Datei in das Verzeichnis „mod“ von Moodle, ab Moodle 5.1 in „public/mod“, und startet die Aktualisierung.
Ein Update läuft genauso ab: neue ZIP-Datei hochladen, Datenbank aktualisieren. Einstellungen und ausgestellte Nachweise bleiben erhalten.
Schritt 2: API-Schlüssel in Moodle hinterlegen
Den Schlüssel erzeugen Sie in Virtualbadge.io: Öffnen Sie „Einstellungen“ und „Integrationen“ und klicken Sie unter „API Zugriff“ auf „Token generieren“. In Virtualbadge.io heißt der Schlüssel Token, im Plugin „API key“. Die Stelle zeigt die Anleitung zur REST-API.
In Moodle öffnen Sie „Website-Administration“, „Plugins“, „Aktivitäten“ und dort „Virtualbadge“. Tragen Sie den Token unter „API key“ ein und speichern Sie. Moodle speichert den Schlüssel verschlüsselt und zeigt danach nur noch „(Set and encrypted)“.
Die „API address“ bleibt bei https://api.virtualbadge.io. „Calls per hour“ begrenzt die Aufrufe pro Stunde, voreingestellt sind 200. Tragen Sie hier den Wert ein, der für Ihre Organisation mit Virtualbadge.io vereinbart ist. „Date format“ legt fest, wie Datumsangaben in den Feldern der Vorlage erscheinen. Voreingestellt ist „DD.MM.YYYY“, also Tag, Monat, Jahr.
Behandeln Sie den Schlüssel wie ein Passwort. Er hat die Rechte Ihrer Organisation in Virtualbadge.io. Könnte er in falsche Hände geraten sein, erzeugen Sie in Virtualbadge.io einen neuen Token und tragen ihn in Moodle ein.
Schritt 3: Aktivität „Virtualbadge“ im Kurs anlegen
Öffnen Sie den Kurs und schalten Sie das Bearbeiten ein. Klicken Sie an der gewünschten Stelle auf „Aktivität oder Material anlegen“ und wählen Sie „Virtualbadge“.
Geben Sie der Aktivität einen Namen, zum Beispiel „Zertifikat Datenschutz-Unterweisung“. Unter diesem Namen sehen Ihre Teilnehmer die Aktivität im Kurs. Ein eigener Abschnitt, etwa „Bescheinigungen“, hält den Kurs übersichtlich.
Meldet das Formular, dass kein API-Schlüssel hinterlegt ist, fehlt noch Schritt 2.
Schritt 4: Vorlage wählen und Felder zuordnen
Wählen Sie im Abschnitt „Certificate or badge“ unter „Template“ die Vorlage. Die Liste zeigt die aktiven Vorlagen Ihrer Organisation. Haben Sie eine Vorlage gerade erst angelegt oder geändert, aktualisiert „Reload templates“ die Liste. Ihre Eingaben im Formular bleiben dabei erhalten.
Für jedes Feld der Vorlage erscheint eine Zeile „Field“ mit dem Namen des Feldes. Dort wählen Sie, woher der Wert kommt. Die Tabelle nennt die Quellen. Name und E-Mail-Adresse der Person sendet das Plugin immer mit, sie brauchen keine Zuordnung.
Trägt ein Feld der Vorlage denselben Namen wie ein Feld in Moodle, ist die Quelle schon vorbelegt. Datumsangaben sendet Moodle im eingestellten Datumsformat.
| Quelle | Beispiele | Wert |
|---|---|---|
| „Fixed text“ | „9 Unterrichtseinheiten“ oder „Hamburg“ | Für alle gleich. Platzhalter wie {course} oder {coursestartdate} sind möglich |
| „Participant“ | Vorname, Nachname, Ort, Institution, eigene Profilfelder wie eine Personalnummer | Je Person aus dem Profil |
| „Course and completion“ | Kursname, Kurs-ID, Kursbeginn, Kursende, eigene Kursfelder, Abschlussdatum, Kursnote in Prozent, Punkte | Aus den Kurseinstellungen, den Bewertungen oder dem Abschluss |
| „Grade items“ | Jede Bewertung des Kurses, zum Beispiel der Abschlusstest in Punkten oder in Prozent | Ergebnis der Person in diesem Test oder dieser Aufgabe |
Ist ein zugeordneter Wert in Moodle leer, zum Beispiel ein fehlendes Kursende, stellt Moodle nichts aus. Die Statusliste nennt dann das fehlende Feld. Füllen Sie Kurseinstellungen und eigene Kursfelder aus, bevor die ersten Teilnehmer den Kurs abschließen.
Schritt 5: Auslöser festlegen
Unter „Issue on“ legen Sie fest, wann Moodle ausstellt. Vier Auslöser stehen zur Wahl, die Tabelle zeigt, was sie tun.
„Email from Virtualbadge“ ist eingeschaltet, solange Sie nichts ändern: Virtualbadge.io sendet dann bei jeder Ausstellung eine E-Mail mit dem Link. Ohne Haken sehen Ihre Teilnehmer den Link nur in Moodle. Text und Absender der E-Mail legen Sie in Virtualbadge.io fest.
Speichern Sie die Aktivität. In den Einstellungen zum Aktivitätsabschluss können Sie zusätzlich die Bedingung „Certificate issued“ wählen: Die Aktivität gilt dann als abgeschlossen, sobald der Nachweis ausgestellt ist.
| Auslöser | Verhalten | Passt zu |
|---|---|---|
| „Course completion“ | Sobald Moodle den Kurs für die Person als abgeschlossen markiert. Der Kursabschluss muss im Kurs eingerichtet sein | Online-Pflichtschulung |
| „Course completion, after release by a trainer“ | Die Statusliste zeigt, wer den Kurs abgeschlossen hat. Ausgestellt wird erst nach „Release“ oder „Release all“. Der Nachweis trägt das Datum des Kursabschlusses | Zertifikat, das ein Trainer vorher prüft |
| „Minimum grade“ | Sobald die gewählte Bewertung den Prozentwert erreicht. Unter „Grade“ wählen Sie „Course total“ oder einen einzelnen Test | Badge für den bestandenen Wissenstest |
| „Manual release by a trainer“ | Nur nach „Release“ in der Statusliste, unabhängig vom Kursabschluss. Der Nachweis trägt das Datum der Freigabe | Präsenzveranstaltung |
Mehrere Aktivitäten in einem Kurs sind möglich, zum Beispiel ein Badge direkt nach dem Test und ein Zertifikat nach der Freigabe. Ein Beispiel finden Sie unter Pflichtschulung mit Badge und Zertifikat.
Schritt 6: Mit einer Testperson prüfen
Schreiben Sie ein Testkonto als Teilnehmer in den Kurs ein und erfüllen Sie damit die Bedingung: Kurs abschließen, Test bestehen oder freigeben lassen. Nur wer im Kurs Nachweise erhalten darf, löst eine Ausstellung aus. In der Voreinstellung sind das die Teilnehmer. Schließt ein Trainer den Kurs zur Probe ab, passiert deshalb nichts.
Moodle stellt im Hintergrund aus. Zuerst steht in der Aktivität „Your certificate is being created. The link will appear here shortly.“ Meist wechselt der Status nach 30 bis 60 Sekunden auf „Issued“. Die Testperson sieht dann „Open certificate“ mit Download und Teilen und den Link „Validation page“ zur öffentlichen Validierungsseite.
Jede Ausstellung verbraucht einen Credit, auch im Test.
Für einen Probelauf ohne echte Nachweise eignen sich eine Testinstanz von Moodle und eine Sandbox-Organisation in Virtualbadge.io mit eigenem Token. Nachweise aus der Sandbox sind als Test gekennzeichnet.
Schritt 7: Statusliste nutzen: freigeben, erneut senden, neu ausstellen
Trainer sehen in der Aktivität unter „Participants“ alle Teilnehmer mit ihrem Status. Je nach Auslöser geben Sie dort mit „Release“ einzeln frei, mit „Release all“ für alle, die den Kurs abgeschlossen haben, oder über die Kästchen vor den Namen für eine Auswahl.
Haben Sie die Aktivität in einen laufenden Kurs gelegt, zeigt die Liste, wie viele Teilnehmer die Bedingung schon erfüllen. Mit „Issue to … participants“ erhalten sie ihren Nachweis nachträglich. Bei mehr als 50 Personen arbeitet Moodle die Ausstellungen im Hintergrund ab.
Kam die E-Mail nicht an, hilft „Send email again“. Stimmen Name oder Kursdaten nicht, korrigieren Sie sie in Moodle und wählen dann „Issue again“: Es entsteht ein neuer Nachweis mit den aktuellen Daten, der alte wird in Virtualbadge.io ungültig. Alle Status und Aktionen stehen unter Statusliste: Status und Aktionen.
Gehen Sie diese Anleitung mit Ihren eigenen Daten durch.
Ergebnis prüfen
- Im Formular der Aktivität erscheinen die Vorlagen Ihrer Organisation: Die Verbindung steht.
- Die Testperson sieht in der Aktivität „Open certificate“ und „Validation page“.
- Die Statusliste zeigt für die Testperson „Issued“.
- Die Person erscheint in Virtualbadge.io in der Teilnehmerliste der Vorlage.
Mehr dazu: Integration für MoodleIntegrationen
Beispiel: Pflichtschulung mit Badge und Zertifikat
Die Bilder dieser Anleitung stammen aus einem Demo-Kurs: einer Datenschutz-Unterweisung mit einer Textseite und einem Test mit 5 Fragen und 20 Punkten, bestanden ab 16 Punkten. Der Kurs gilt als abgeschlossen, wenn die Seite angesehen und der Test bestanden ist. Zwei Aktivitäten vergeben ein Badge und ein Zertifikat.
| Einstellung | Badge | Zertifikat |
|---|---|---|
| Vorlage in Virtualbadge.io | Felder für Kurs, Punkte und Höchstpunktzahl | Felder für Personalnummer, Datum, Kurs, Kurs-ID, Unterrichtseinheiten, Trainer und Gültigkeit |
| Quellen in Moodle | „Course name“, „Course total (points)“ und „Maximum course total (points)“ | Ein Profilfeld, „Completion date“, „Course name“, „Course ID number“ und drei eigene Kursfelder |
| Auslöser | „Minimum grade“ mit 80 Prozent | „Course completion, after release by a trainer“ |
| Ergebnis | Direkt nach dem Test, zum Beispiel mit 18 von 20 Punkten | Nach „Release“, mit dem Datum des Kursabschlusses |
Sollen auf dem Nachweis die Punkte der Fragen stehen, setzen Sie die Höchstnote des Tests auf die Summe der Fragenpunkte. Sonst rechnet Moodle die Punkte auf die Höchstnote um.
Statusliste: Status und Aktionen
Die Liste unter „Participants“ zeigt je Person den Status und die Schaltflächen, die dazu passen. Die Tabellen erklären beides.
| Status | Bedeutung |
|---|---|
| „Not issued“ | Bedingung noch nicht erfüllt |
| „Queued“ | Wird in Kürze gesendet |
| „Being created“ | In Virtualbadge.io angelegt, das Dokument wird erzeugt. Wechselt meist nach 30 bis 60 Sekunden auf „Issued“ |
| „Issued“ | Ausgestellt |
| „Retrying“ | Virtualbadge.io war kurz nicht erreichbar oder das Limit der Aufrufe ist erreicht. Moodle versucht es von selbst erneut |
| „Error“ | Nicht ausgestellt. Der Grund steht daneben |
| „Revoked“ | In Virtualbadge.io widerrufen oder ersetzt |
| „Deleted in Virtualbadge“ | In Virtualbadge.io gelöscht. Der Link funktioniert nicht mehr |
| Schaltfläche | Wann | Wirkung |
|---|---|---|
| „Release“ | Manuelle Freigabe, oder der Kurs ist abgeschlossen und der Auslöser sieht eine Freigabe vor | Stellt den Nachweis aus |
| „Release all“ | Mehrere Personen haben den Kurs abgeschlossen. Die Schaltfläche nennt ihre Zahl | Stellt für alle aus, die den Kurs abgeschlossen haben |
| „Release selected“ oder „Issue to selected“ | Kästchen vor den Namen sind markiert | Stellt nur für die markierten Personen aus |
| „Retry issuing“ | Status „Error“ | Neuer Versuch, zum Beispiel nachdem ein fehlendes Kursende eingetragen ist |
| „Send email again“ | Status „Issued“ | Virtualbadge.io sendet die E-Mail noch einmal an die ursprüngliche Adresse. Kein neuer Nachweis, kein Credit, höchstens zehnmal |
| „Issue again“ | Status „Issued“ | Neuer Nachweis mit den aktuellen Daten aus Moodle, der alte wird ungültig. Verbraucht einen Credit |
| „Issue new certificate“ | Status „Deleted in Virtualbadge“ | Neuer Nachweis mit den aktuellen Daten. Verbraucht einen Credit |
„Issue again“ setzt geänderte Daten voraus. Sind Name, E-Mail-Adresse und alle Feldwerte gleich geblieben, bleibt der bisherige Nachweis gültig und es wird kein Credit verbraucht. Hat sich die E-Mail-Adresse geändert, tragen Sie die neue Adresse im Profil ein und wählen „Issue again“. „Send email again“ nutzt immer die ursprüngliche Adresse.
Moodle gleicht ausgestellte Nachweise etwa einmal am Tag mit Virtualbadge.io ab. Wird ein Nachweis dort widerrufen oder ersetzt, zeigt die Statusliste das an. Einen ersetzten Nachweis übernimmt Moodle mit seinem neuen Link.
Wenn kein Nachweis ausgestellt wird
Erfüllt eine Person die Bedingung und erhält trotzdem keinen Nachweis, steht der Grund im Kurs unter „Berichte“ und „Logdaten“, beim Ereignis „Certificate not issued“.
| Grund | Was Sie tun |
|---|---|
| Keine E-Mail-Adresse | E-Mail-Adresse im Profil eintragen, dann freigeben oder nachträglich ausstellen |
| Bewertung unter der Mindestnote | Ausgestellt wird erst ab der Mindestnote. Nach einem besseren Ergebnis stellt Moodle von selbst aus |
| Nicht eingeschrieben, darf keine Nachweise erhalten oder hat keinen Zugriff auf die Aktivität | Rolle der Person prüfen. Prüfen Sie auch, ob die Aktivität sichtbar ist und keine Voraussetzung hat, die die Person nicht erfüllt |
Für die Administration zeigt „Website-Administration“, „Berichte“, „Systemstatus“ die Prüfung „Virtualbadge certificates“: fehlgeschlagene und wiederholte Ausstellungen aus allen Kursen, mit dem letzten Fehler und einem Link zur Statusliste.
Meldet die Aktivität, dass die Vorlage Felder ohne Zuordnung hat, wurden in Virtualbadge.io Felder ergänzt oder umbenannt. Bis zur Zuordnung stellt die Aktivität nichts aus. Öffnen Sie über „Edit settings“ das Formular, klicken Sie auf „Reload templates“, ordnen Sie die neuen Felder zu und speichern Sie. Offene Ausstellungen holen Sie danach mit „Retry issuing“ nach.
Datenschutz und Betrieb
Für eine Ausstellung sendet das Plugin Name, E-Mail-Adresse, Abschlussdatum, die Werte der zugeordneten Felder und eine technische Moodle-Referenz an Virtualbadge.io. Die Übermittlung ist über die Datenschutz-Schnittstelle von Moodle dokumentiert.
Moodle baut die Verbindung immer selbst auf. Der Kursabschluss wartet nicht auf Virtualbadge.io: Ist der Dienst kurz nicht erreichbar, wiederholt Moodle den Versuch bis zu zehnmal von selbst. Die Referenz je Ausstellung verhindert doppelte Nachweise.
Ein Nachweis braucht zwei bis drei Aufrufe. Mit 200 Aufrufen pro Stunde entstehen etwa 70 bis 100 Nachweise pro Stunde. Ist das Limit erreicht, wartet das Plugin und sendet weiter, sobald wieder Aufrufe frei sind.
Wer in Moodle Daten löscht, einen Kurs zurücksetzt oder das Plugin deinstalliert, widerruft damit keine Nachweise. Sie bleiben gültig, bis Sie sie in Virtualbadge.io widerrufen.
Häufige Fragen
Mit welchen Versionen von Moodle arbeitet das Plugin?
Mit Moodle 4.5 bis 5.3, auf PostgreSQL, MariaDB oder MySQL. Diese Anleitung beschreibt Version 1.1.4 des Plugins.
Verbraucht jede Ausstellung einen Credit?
Ja. Jede Ausstellung und jede Neuausstellung über „Issue again“ oder „Issue new certificate“ verbraucht einen Credit. Die E-Mail erneut zu senden verbraucht keinen.
Kann ein Kurs ein Badge und ein Zertifikat vergeben?
Ja. Legen Sie zwei Aktivitäten an, jede mit eigener Vorlage und eigenem Auslöser: zum Beispiel ein Badge ab 80 Prozent im Abschlusstest und ein Zertifikat nach dem Kursabschluss.
Erhalten Teilnehmer, die den Kurs schon abgeschlossen haben, nachträglich einen Nachweis?
Ja. Die Statusliste zeigt, wie viele Personen die Bedingung schon erfüllen. Mit „Issue to … participants“ stellen Sie ihnen nachträglich aus.
Was passiert, wenn Virtualbadge.io kurz nicht erreichbar ist?
Der Kursabschluss in Moodle läuft normal weiter. Die Statusliste zeigt „Retrying“, Moodle versucht es bis zu zehnmal von selbst und stellt nichts doppelt aus.
Was geschieht mit den Nachweisen, wenn ich den Kurs zurücksetze?
Beim Zurücksetzen löscht die Option „Delete issue records“ nur die Einträge in Moodle. Die Nachweise bleiben in Virtualbadge.io gültig. Was danach ausgestellt wird, sind neue Nachweise.
Können mehrere Organisationen über eine Moodle-Site ausstellen?
Ja. In den Einstellungen des Plugins hinterlegen Sie unter „Organisations“ weitere Organisationen mit eigenem Schlüssel, zum Beispiel für einen Partner, und ordnen sie unter „Course categories“ einzelnen Kursbereichen zu. Kurse ohne Zuordnung nutzen die Hauptorganisation.