Lehrplan: Integrationsmöglichkeiten (REST, CSV, ereignisbasiert)
Curriculum unterstützt verschiedene Arten der Integration, von denen einige als Teil der technischen Implementierung konfiguriert werden (E-Mail- und ADFS2-Integration), während andere für den Import von Daten zum Start der Nutzung (CSV) oder für den Aufbau vollautomatisierter Schnittstellen mit externen Systemen (SRS, HR, RIO, LMS, ...) verwendet werden.
Starten Sie Ihr Projekt über CSV-Import
Curriculum ermöglicht dem Administrator den Import von Daten mittels csv-Dateien. Der Administrator kann den Import über den Menüpunkt csv im Verwaltungsmenü starten:
- Wählen Sie den zu importierenden Typ aus
Wenn Sie den Typ auswählen, werden sofort die Einzelheiten des zu verwendenden csv-Formats angezeigt. - Geben Sie das verwendete Trennzeichen an (z. B. ; oder ,)
- Laden Sie die Datei hoch (legen Sie sie in der Dateibox ab)
- Klicken Sie auf Speichern, um den Import zu starten
Neue Elemente werden hinzugefügt, bestehende Elemente werden auf der Grundlage der importierten Daten geändert. Es werden nur Daten geändert, die über die csv angeboten werden. Daten, die bereits im Curriculum definiert sind und nicht über die csv bereitgestellt werden, werden nicht geändert. Das bedeutet, dass die Daten nicht automatisch gelöscht werden und die csv-Datei sowohl für den Import von "geänderten Personen" als auch von "neuen Personen" verwendet werden kann. Das Löschen von Personen wird nicht unterstützt, dies könnte durch das Setzen des Enddatums erreicht werden (logisches Löschen).
Blättern Sie bis zum Ende der Dokumentation, um ein Beispiel mit dem zu verwendenden csv-Header und einer Beispieldatenzeile zu erhalten.
Der csv-Import bietet Unterstützung für die folgenden Datenelemente:
- Aktivität - Die Lehr- und Prüfungsaktivitäten (z. B. Vorlesungen, Praktika, schriftliche Prüfung), die im Rahmen eines Moduls angeboten werden
- Beratung - Beratung durch Studienkommissionen.
- Beurteilung - Die Modulbeurteilung (Prüfung) im Falle einer Prüfungszusammenlegung
- Bewertung - Die Bewertung legt fest, wie ein Modul geprüft wird.
- Asset - Die Ressourcen, die in einem Objekt verwendet werden können.
- Zuordnung - Definieren Sie die Zuordnung von Personen zu Organisationseinheiten
- Award_qualification - Definieren Sie die Beziehungen zwischen einer Qualifikation und einer Studie/Spezifikation.
- Kostenaufteilung - Kostenaufteilungen definieren, wie die Kosten zwischen den Organisationseinheiten aufgeteilt werden.
- Beschreibung - Definieren Sie einen beschreibenden Text zu einem definierten Objekt, z.B. Studie, Gruppe, Modul, ...
- Feld - Definieren Sie benutzerdefinierte Felder, die Datenelemente zu Bildungsobjekten hinzufügen.
- Fakultät - Die Fakultät ist eine Gruppe von Universitätsabteilungen, die sich mit einem wichtigen Wissensgebiet befassen.
- Generierter Wert - Importieren Sie Werte, die in der "eindeutigen" Validierung für Objekte verwendet werden sollen. Z.B. alle historischen Studiencodes oder Modulcodes, die angegeben wurden.
- Element - Definieren Sie benutzerdefinierte Objekte, die komplexe Elemente zu Bildungsobjekten hinzufügen.
- Link - Links beschreiben die Beziehung zwischen zwei Objekten, z.B. Substitutionsregel, Voraussetzung, Mitvoraussetzung, ..
- Meeting - Definieren Sie Aktivitätssets (Meetings) für Aktivitäten.
- Methode - Die Modulmethoden definieren die von einem Modul angebotenen Lehrmethoden.
- Methodenschema - Definieren Sie das Modulmethodenschema (Bildung), das die Methodengruppierung und -auswahl spezifiziert.
- Modul - Definieren Sie das Modul, das ein Teil der Bildungsstruktur ist und die grundlegenden Modulinformationen definiert.
- Modulgruppe - Definieren Sie (Modul-)Gruppen, die ein Teil der Bildungsstruktur sind und die Bildungskomponenten innerhalb einer Studie definieren, die Gruppen und/oder Module enthalten.
- Zielsetzung - Definieren Sie die einem Modul zugewiesenen Ziele (Lernziele), einschließlich der Beziehung zur Bewertung und zum Fach.
- Angebot - Definieren Sie Angebote, d.h. die Zeiträume, in denen ein Bildungsobjekt (Studium, Modul-Gruppen-Modul) den Studierenden zur Verfügung steht.
- Organisation - Definieren Sie die organisatorischen Einheiten, die für die Zuweisung von Personal verwendet werden.
- Person - Definieren Sie die Personen/Benutzer, die Zugang zum System haben sollen.
- Qualifikation - Definieren Sie die Qualifikationen, die für die Zuordnung eines Abschlusses zu einem Studiengang verwendet werden.
- Referenz - Definieren Sie die Werte der Referenztabelle. Die Referenztabelle muss vorhanden sein!
- Relation - Definieren Sie Beziehungen für ein bestimmtes Objekt, z. B. Studium, Gruppe, Modul, ...
- Ressourcen - Definieren Sie die Ressourcen (Literatur, Software), die in einem Objekt verwendet werden können.
- Regel - Definieren Sie die Regel (Container), die verwendet wird, um festzulegen, wann bestimmte Anforderungen erfüllt sind, z. B. für den Abschluss.
- Spezifikation - Definieren Sie Spezifikationen, die die allgemeine, jahresunabhängige Struktur eines Objekts angeben.
- Studium - Definieren Sie Studien (Studiengänge), die das angebotene Programm und seine Struktur spezifizieren.
- Thema - Definieren Sie die Themen (Lernergebnisse / Fähigkeiten), die einer Studie oder einem Modul zugeordnet sind.
- Aufgabe - Definieren Sie die einer Personenzuweisung zugeordneten nichtpädagogischen Aufgaben.
- Wert - Der Wertimport kann verwendet werden, um einzelne Attribute und Werte zu einem bestimmten Objekt hinzuzufügen oder zu ändern. Er kann als zusätzliche Option betrachtet werden, um Werte auf Objektebene zu setzen, neben der Standardoption, Werte sofort zu setzen, wenn das gesamte Objekt importiert wird, ohne dass dadurch bereits definierte Beziehungen oder andere Daten zu diesem Objekt geändert werden. Falls bereits Änderungen an dem importierten Feld vorgenommen wurden, werden diese beibehalten.
Bericht über gesendete Mails
Die Integration mit dem Mailserver wird im Rahmen der technischen Implementierung durchgeführt. Das Skript-Menü des Administrators bietet die Funktion Testmail senden , um die korrekte Implementierung in einer Produktionsumgebung an eine selbst definierte Empfänger-E-Mail-Adresse technisch zu testen.
In Nicht-Produktionsumgebungen werden E-Mails nicht an die tatsächliche E-Mail-Adresse eines Benutzers, sondern an ein einzelnes (gemeinsames) Postfach gesendet, um zu verhindern, dass versehentlich E-Mails an tatsächliche Benutzer gesendet werden.
Wenn die E-Mail-Integration eingerichtet ist und Benachrichtigungen an die Benutzer aus den Prozessen gesendet werden sollen, können die gesendeten Benachrichtigungen (E-Mails) über das Administratormenü E-Mail eingesehen werden.
Der Bericht bietet einen Überblick über alle gesendeten Benachrichtigungen, einschließlich der Frage, ob sie erfolgreich gesendet wurden. Oben auf der Seite wird eine Anzeige eingeblendet, die Informationen über die verwendete Warteschlange liefert. Die Warteschlange wird verwendet, um die Anzahl der gesendeten E-Mails innerhalb von Zeitintervallen zu begrenzen, z. B. für die Integration mit office365, das Beschränkungen für E-Mails pro Minute, Stunde und/oder Tag haben kann.
Die Einzelheiten der gesendeten E-Mail (Benachrichtigung) können durch Anklicken der Benachrichtigung eingesehen werden, wobei der angezeigte Betreff und Textkörper die an den Empfänger gesendete Benachrichtigung enthält und der Spracheinstellung des Empfängers entspricht.
Integration über die Curriculum REST API
Die Curriculum-API ist eine REST/JSON-basierte API, die zum Aufbau einer automatisierten Integration verwendet wird. Die API ermöglicht sowohl das Lesen, Hinzufügen, Ändern und logische Löschen von Daten.
Die vollständige Curriculum-API-Referenz ist verfügbar unter: https://timeedit.readme.io
Verwenden Sie die Navigation auf der linken Seite und navigieren Sie zu den lehrplanbezogenen Informationen.
Der direkte Link zum Beispiel zum Dienst Person lautet: https://timeedit.readme.io/reference/saveperson_v2
Die Dienste können über die URL getestet werden.
Es werden bestimmte Optionen zur Steuerung der JSON-Nachricht unterstützt:
- erweitern. - Option zur Manipulation der REST-Ausgabe. In diesem Beispiel wird die Standardausgabe der Studie um detaillierte Informationen zur Modulgruppe (Gruppe) erweitert.
Besondere Fälle sind:- - überhaupt keine Erweiterung, so dass ein minimalistisches JSON-Ergebnis erzeugt wird.
- * - die Nachricht wird maximal erweitert, was zu einer sehr umfangreichen Nachricht führt. Diese Option sollte sehr vorsichtig verwendet werden, und wahrscheinlich nicht in einer Studie.
- System - definieren Sie die Verwendung der konfigurierten Einstellungen eines bestimmten externen Systems. Zum Beispiel ein (Test-)System, mit dem auch unveröffentlichte Informationen ausgetauscht werden können
Example: <base_url>/import/v2/study/MAABC123?year=2024&expand=group&system=SRS
Ein weiteres nützliches Tool für Testzwecke ist Postman. Die API kann in Postman importiert werden, um die definierten Dienste zu generieren und die verschiedenen Aufrufe zum Abrufen/Posten von Daten zu testen.
Auf Anfrage:
- ein Beispiel-Postman-Projekt kann mit Musteranfragen für (fast) alle Dienste und Anfragen bereitgestellt werden.
- eine Online-Erklärung/Schulung kann für die Entwickler der Universität angeboten werden, um Wissen zu teilen und technische Details zu vertiefen.
Lehrplan REST OOAPI v5
Neben der Standard Curriculum REST/JSON API gibt es auch Unterstützung für die OOAPI v5.
Die OOAPI v5 ist ein offener Standard, Informationen über den Standard finden Sie unter folgender Adresse: https://openonderwijsapi.nl/#/
Die ausführliche Definition aller Dienste finden Sie unter folgender Adresse: https://openonderwijsapi.nl/specification/v5/docs.html
Curriculum unterstützt vollständig die OOAPI V5, einschließlich der Konnektivität mit eduXchange und RIO über den SURF eduHub.
Wie die Standard-Curriculum-API kann auch die OOAPI v5 mit Postman getestet werden.
Ereignisbasierte Integration
Die genannten APIs werden verwendet, um die Daten in Curriculum aus einer externen Quelle zu verwalten oder um Informationen aus Curriculum über einen Anfrage-Antwort-Mechanismus abzurufen.
Neben dieser Integrationsarchitektur unterstützt Curriculum auch die Integrationsunterstützung, bei der Daten von Curriculum an externe Systeme gesendet (veröffentlicht) werden, basierend auf Ereignissen in den Curriculum-Prozessen.
In der Anleitung zur Prozesskonfiguration gibt es einen Abschnitt über Hooks. Hooks sind als benutzerkonfigurierbare Funktionen definiert, die von einem Prozess aus ausgeführt werden können.
Der in der Integration verwendete Hook ist der Hook mit dem Namen Daten exportieren.
Einmal ausgelöst, sendet der Datenexport-Haken Daten an das konfigurierte System für ein Bildungsobjekt.
Die unten gezeigte Hook-Konfiguration sendet lediglich die Daten an das SRS.
In der Prozesskonfiguration wird der Haken so definiert, dass er zu einem bestimmten Zeitpunkt ausgelöst wird.
Das Beispiel zeigt, dass der Export in dasSRS für das Modul ausgeführt werden sollte, sobald es genehmigt ist.
Die Konfiguration des Hooks erfordert die Angabe des Systems. Das ausgewählte System (Konfiguration: Externe Systeme) enthält alle relevanten Konnektivitätsinformationen (Endpunkt, Dienst, Authentifizierung).
Die Definition eines Systems ist ein zweistufiger Ansatz:
- Definieren Sie das externe System, den Endpunkt, den Dienst, die Authentifizierung, die Firewalls usw. in enger Zusammenarbeit zwischen der Integrationsabteilung des Kunden und TimeEdit
. Diese Definition ist serverbasiert, um den unbefugten Zugriff auf diese extrem anfälligen Daten zu sichern. - Konfigurieren Sie das System im Curriculum über den Menüpunkt Administrator -> Externe Systeme.
In der Beispielkonfiguration sind drei externe Systeme definiert.
Verwenden Sie die Schaltfläche Hinzufügen, um ein neues System zu definieren, oder klicken Sie auf ein bereits definiertes System, um das externe System zu konfigurieren.
Die folgenden Optionen können zur Konfiguration des Systems verwendet werden:
- Code - Eindeutiger Name des externen Systems, der zu Anzeigezwecken und als eindeutiger Bezeichner in der Systemkonfiguration zur technischen Definition des externen Systems verwendet wird (IP, Authentifizierung, ...)
- Beschreibung - Grund / Beschreibung der hinzugefügten Systemkonfiguration
- Standard - Zeigt an, ob es sich bei dieser Schnittstelle um die Standardschnittstelle handelt. In diesem Fall wird sie automatisch ausgewählt, wenn im Hook kein Empfangssystem definiert ist.
- Exportierbar - Indikator, ob diese Schnittstelle "fertige und genehmigte" Daten empfangen darf.
- Auch unveröffentlichte Daten anzeigen - Indikator, ob Daten, die (noch) nicht als veröffentlicht markiert sind, auch gesendet werden sollen. Diese Option ist besonders praktisch für Tests.
- Inclusive removed - Indikator, ob gelöschte Objekte auch in der Ausgabe erscheinen sollen. Dies wird z.B. bei der Integration mit CORE verwendet, um gelöschte Aktivitätsreihen eindeutig zu kennzeichnen.
- Spezifikation einschließen - Kennzeichen, wenn eine Spezifikation vor dem Senden des Datenobjekts gesendet werden soll. Dies wird für OOAPI verwendet, um sicherzustellen, dass die entsprechende Spezifikation gesendet wird, bevor das eigentliche Programm oder der Kurs gesendet wird.
- Zuerst gesendet an - Legen Sie fest, ob die Ausgabe zuerst an ein anderes System gesendet werden soll. Dies kann auch mit der Option "Kombinierte Haken" in der Hook-Konfiguration erreicht werden.
Die gesendete Ausgabe hat das exakte Format der Daten, die bei einem GET auf dieses Objekt über die REST-API abgerufen werden.
Dies ermöglicht die Entwicklung (und das Testen) Ihres Empfänger-Endpunkts, indem Sie einfach einen kleinen Schritt vorangestellt haben, der das Modul abruft und es an Ihren Empfänger weitergibt.
Und sobald der Empfänger in einem ausreichend guten Zustand ist, kann er direkt mit dem Lehrplan verbunden werden und Daten können vom Lehrplan gesendet werden.
Die Standard-REST-Nachricht, die über den Veröffentlichungsmechanismus gesendet wird, ist das komprimierte Nachrichtenformat (nicht erweitert). Dieses Nachrichtenformat wird standardmäßig verwendet, um eine leichtgewichtige Datenübertragung zu ermöglichen, die bei Bedarf erweitert/erweitert werden kann.
Die Option zur Konfiguration des benutzerdefinierten Typs wird hauptsächlich für die Manipulation der Attribute eines Objekts verwendet.
Es gibt eine Registerkarte mit der Bezeichnung Exporttypen, die die Konfiguration der exportrelevanten Informationen sowohl für das externe System als auch für das Objekt ermöglicht.
Das Beispiel zeigt die Konfiguration der SRS-Integration.
Die folgenden Optionen können zur Konfiguration des Systems verwendet werden:
- Strategie - die Genehmigungsstrategie, die vor dem Versand ausgeführt werden soll. Unterstützte Strategien sind:
- Automatisch - Die Daten werden wie konfiguriert an das externe System gesendet.
- Manuell - Die Daten sind als bereit für das externe System gekennzeichnet, werden aber manuell im externen System verarbeitet.
- Ignorieren - Die Daten sind als "gesendet" gekennzeichnet, werden aber nicht gesendet, da die Daten nur als Lehrplan betrachtet werden.
- Anfrage - die zu verwendende Curriculum-Anforderungsmethode:
- canonical:setStudy_v2 - verwendet das Standardformat der REST-API für Lehrpläne. Basierend auf dem Objekt ändert sich die Option in setGroup und setModule.
- rio:submitV5 - Verwendung des RIO-Datenformats und der spezifischen rio submit-Methodik
- te:sendObject - zum Senden von Daten von Curriculum zu Core unter Verwendung des im Curriculum konfigurierten Mappings
- Exclude pattern - Indikator, wenn diese Schnittstelle die Standardschnittstelle ist. In diesem Fall wird sie automatisch ausgewählt, wenn kein empfangendes System im Hook definiert ist.
- Felder erweitern - Option zur Manipulation der REST-Ausgabe. In diesem Beispiel wird die Standardausgabe der Studie um detaillierte Informationen zur Modulgruppe (Gruppe) erweitert.
Besondere Fälle sind:- - überhaupt keine Erweiterung, so dass ein minimalistisches JSON-Ergebnis erzeugt wird.
- * - die Nachricht wird maximal erweitert, was zu einer sehr umfangreichen Nachricht führt. Diese Option sollte sehr vorsichtig verwendet werden, und wahrscheinlich nicht in einer Studie.
Ad-hoc-Versand von ereignisbasierten Nachrichten
Durch die bereits erwähnte Konfiguration des Hooks in der Prozesskonfiguration wird das Ereignis (die Nachricht) automatisch gesendet, wenn der Prozessschritt ausgeführt wird.
Für Testzwecke oder das erneute Senden von Daten gibt es Unterstützung über die Registerkarte "Administrator" oder über die Hooks des Prozessmanagers. Der Prozessmanager wird in einem separaten Handbuch behandelt.
Die Registerkarte "Unterstützung durch den Administrator" befindet sich links unten auf der Verwaltungsseite:
Mit der Schaltfläche Export wird die Übertragung des aktuell ausgewählten Datenobjekts an das externe System durchgeführt.
Es wird ein Pop-up-Fenster angezeigt, das die relevanten Verarbeitungsinformationen für das Senden des Objekts an das ausgewählte externe System enthält.
Mit der Schaltfläche Hook wird die Übertragung des aktuell ausgewählten Datenobjekts an das externe System durchgeführt.
Es werden keine Informationen angezeigt, die entsprechenden Verarbeitungsinformationen können dem Protokoll entnommen werden (siehe unten).
Bericht über die Integration (Exporte)
Das Menü Verwaltung -> Exporte enthält Informationen über Informationen, die mit der Veröffentlichungsmethode (Hooks) gesendet werden.
Es gibt eine leichte Überschneidung mit der Funktion Verwaltung -> Anfrageprotokoll. Hier werden der ursprüngliche Aufruf und der HTTP-Anforderungsstatus angezeigt. Es handelt sich also um eine eher technische Informationsebene. Wenn also eine Nachricht gesendet und nicht im Menü "Exporte" wiedergefunden wird, kann es durchaus sein, dass die Zustellung der Nachricht aufgrund eines technischen Fehlers fehlgeschlagen ist (z. B. unautorisiert, unerreichbar, ...).
Im Menü "Exporte" werden die Nachricht und das Ergebnis ihrer Verarbeitung durch das Empfängersystem angezeigt. Die RIO-Integrationen werden als "Fire and Forget"-Integration auf der Grundlage der architektonischen Anforderungen von RIO eingerichtet. Das Anforderungsprotokoll meldet nur, wenn die Nachricht zugestellt wurde (an den Zwischenpartner). Das Verarbeitungsergebnis des empfangenden Systems wird über einen separaten Rückrufdienst von der empfangenden Partei gesendet. Das Menü Exporte kombiniert in diesem Fall die Anfrage und die Antwort (Callback) auf der Grundlage der Korrelations-ID.
Die Such- und Filteroptionen bieten verschiedene Möglichkeiten, die gewünschten Nachrichteninformationen zu finden, z. B. nur die fehlgeschlagenen Serviceanfragen auszuwählen.
Die Filteroptionen sind:
- Suchbegriff - Suche nach einem Text in der Nachricht.
- System - Filtern Sie Nachrichten, die an eines der konfigurierten externen Systeme gesendet werden.
- Status - Geben Sie die Art der anzuzeigenden Nachrichten an
- Abgeschlossen
- Fehlgeschlagen
- In Bearbeitung
- Warten auf Antwort - Erstellungszeitraum - Geben Sie das Zeitfenster an, in dem die Nachrichten gesucht/angezeigt werden sollen.
Ein Klick auf das Element in der Liste öffnet die detaillierten Informationen über die Anfrage und die Antwort des Dienstes.
Während das Anfrageprotokoll technische Statusinformationen (HTTP 400, 401, ...) enthält, bieten die Exporte die funktionale Fehlermeldung.
Bericht über die Integration (Anfrageprotokoll)
Der Administrator-Menüpunkt Request Log bietet einen Überblick über alle API-Service-Anfragen (eingehende und ausgehende) mit Curriculum. Es ermöglicht die Überprüfung und Untersuchung der Funktionsweise der Schnittstellen, indem es detaillierte Informationen zu den Aufrufen liefert.
Die Such- und Filteroptionen bieten verschiedene Möglichkeiten, die gewünschten Nachrichteninformationen zu finden, z. B. nur die fehlgeschlagenen Serviceanfragen auszuwählen.
Die Filteroptionen sind:
- Aktion - Auswahl von Nachrichten, die über einen bestimmten Endpunkt gesendet/empfangen werden. Je nach Konfiguration können die Aktionen variieren. Im Rahmen der Implementierung und Definition der Integrationen wird die Namensgebung festgelegt und mit dem (System-)Administrator ausgetauscht.
- Entität - Suche nach den Nachrichten eines bestimmten Objekts (Fakultät, Studium, Modulgruppe, Modul, Person, ...)
- Von - Legen Sie das Anfangsdatum fest, ab dem die Nachrichten gesucht werden sollen.
- To - Legen Sie das Enddatum fest, bis zu dem die Nachrichten gesucht werden sollen.
- Status - Geben Sie die Art der anzuzeigenden Meldungen an
- Alle
- Erfolg
- Fehler
Wenn Sie auf den Eintrag in der Liste klicken, werden die detaillierten Informationen über die Serviceanfrage und die ausgetauschten Informationen angezeigt.
By clicking on the </>JSON, </>XML button or (raw) link the detailed message information sent and received will be shown.
You can just copy the message to an editor of your choice that will render and display the JSON / XML in a readable structure to investigate either the message sent or the message received.
.png)