API-Anpassung: Endpunkt-Überschreibungen und Hooks

Wo Sie ihn finden

Modul Verwaltung, Bildschirm Import/Export, Abschnitt API tweaks, Schaltfläche API.

Der Bildschirm ist Premium-Konten vorbehalten und durch eine verstärkte Authentifizierung geschützt: Omniscol fragt das Passwort des Administrators erneut ab, bevor das Fenster geöffnet wird. Da jede Aktion auf diesem Bildschirm den technischen Vertrag Ihrer Integration berührt, erfolgt ihre Einrichtung in Abstimmung mit Omniscol.

Allgemeine Konfiguration

Hier definieren Sie HTTP-Header (Format schlüssel1:wert1;schlüssel2:wert2), die auf alle Hooks angewendet werden. Es ist der natürliche Ort, um ein Authentifizierungstoken an Ihren eigenen Server zu übermitteln (zum Beispiel ein Authorization: Bearer …, das Ihr Server erwartet). Für eine Überschreibung wird die Authentifizierung hingegen in den Endpunkt-eigenen Headern übermittelt (siehe unten).

Überschreibung eines Endpunkts

Eine Überschreibung definiert einen Endpunkt der Omniscol-API neu, so dass die Webanwendung an seiner Stelle eine andere URL aufruft. Drei Anwendungsfälle, vom mächtigsten zum einfachsten.

Live-Daten direkt aus Ihrem Informationssystem bereitstellen

Dies ist der mächtigste Anwendungsfall. Sie leiten einen Endpunkt im Lesezugriff auf eine externe URL um — typischerweise ein ETL, das das interne Informationssystem Ihrer Einrichtung anbindet. Die Webanwendung ruft die Daten dann live aus diesem System ab, statt aus der von Omniscol gehaltenen lokalen Kopie.

Konkret: Wenn die Umleitungs-URL eine absolute externe Adresse ist, ruft die Webanwendung sie direkt auf, ohne den Umweg über die Omniscol-Server, und verarbeitet die Antwort unverändert — genau so, als käme sie von Omniscol. Die einzige Bedingung ist, dass Ihr System im von Omniscol erwarteten Format für diesen Endpunkt antwortet (gleiche JSON-Struktur): Es gibt keine zwischengeschaltete Umcodierung. Für diesen Endpunkt wird die lokale Kopie von Omniscol nicht mehr abgefragt; die angezeigten Daten sind die lebendigen Daten Ihres Systems.

Beispiel: Der Fächerkatalog der Einrichtung, der direkt aus Ihrem Informationssystem bereitgestellt wird, so dass jede Aktualisierung auf Schulseite sofort in Omniscol sichtbar ist, ohne erneuten Import.

Die Authentifizierung an Ihr System wird hier in den Endpunkt-eigenen Headern übermittelt (zum Beispiel ein Authorization: Bearer …), die in der Zeile der Überschreibung eingetragen werden. Auch die HTTP-Methode kann pro Endpunkt vorgegeben werden.

Einen Endpunkt der Anwendung selbst auf eine lebendige externe Quelle umzuleiten, ist eine ebenso mächtige wie anspruchsvolle Möglichkeit: mit Ihrer IT-Abteilung und in Abstimmung mit Omniscol zu handhaben.

Ihren eigenen Server oder einen Proxy zwischenschalten

Sie können die Aufrufe auch über Ihren eigenen Server oder einen Proxy leiten — zum Beispiel, um die gemeinsame Nutzung von Ressourcen zwischen Ursprüngen (CORS) zu erlauben oder um eine hauseigene Logik zwischen der Webanwendung und Omniscol zwischenzuschalten.

Einen Endpunkt deaktivieren

Sie deaktivieren einen Endpunkt, indem Sie ihm keine Umleitungs-URL geben (Methode null).

Bemessen Sie die Wirkung auf die Oberfläche. Omniscol ist eine Single-Page-Webanwendung (SPA), deren Oberflächenelemente von den verfügbaren Endpunkten gesteuert werden: Schaltflächen, Tabs und Menüs erscheinen nur, wenn der Endpunkt, von dem sie abhängen, existiert. Einen Endpunkt zu deaktivieren entfernt daher dynamisch, bei der nächsten Anzeige, die davon abhängigen Oberflächenelemente — und wenn Sie alle Endpunkte eines Moduls deaktivieren, verschwindet das gesamte Modul aus der Navigation. Diese Elemente werden entfernt, nicht nur verborgen, und all dies geschieht ohne jeden Eingriff in den Code: Es genügt, die Konfiguration zu ändern und die Anwendung neu zu laden.

Die Tabelle listet pro Endpunkt auf: seinen Schlüssel (den internen Code des Vorgangs), seine ursprüngliche URL, die HTTP-Methode, die neue URL der Umleitung und spezifische Header. Ein Suchfeld ermöglicht es, den zu überschreibenden Endpunkt zu finden.

Hooks (ausgehende Aufrufe)

Ein Hook fordert Omniscol auf, eine HTTP-Anfrage an Ihre URL zu senden, nachdem ein Vorgang erfolgreich war. Es ist der Mechanismus, um ein externes System in Echtzeit auf dem Laufenden zu halten — eine Anzeigetafel, eine digitale Arbeitsumgebung, ein Personalverwaltungssystem, eine hauseigene Synchronisierung …

Ein Hook wird auf zwei Arten angebunden:

• an einen bestimmten Endpunkt (den Schlüssel des Vorgangs);
• an ein Sammelereignis, das auf einen Schlag eine Familie von Vorgängen abdeckt. Es gibt drei Sammelereignisse:
  • Änderung des Stundenplans (Erstellen, Verschieben oder Löschen von Unterrichtsstunden, Aktivierung eines Stundenplans sowie Abwesenheiten von Lehrkräften oder Klassen, sobald ein Datum betroffen ist);
  • Änderung einer Lehrkraft (Hinzufügen, Aktualisieren oder Löschen);
  • Änderung eines Fachs (benutzerdefinierte Fächer).

Für jeden Hook geben Sie die Rückruf-URL, die HTTP-Methode, das Kästchen „mit Daten“ (soll der ursprüngliche Anfragekörper beigefügt werden?) und eigene Header an.

Was Ihr Server empfängt

Der Aufruf wird als application/json gesendet und trägt zusätzlich zu Ihren Headern:

• den Körper der ursprünglichen Anfrage, wenn die Option „mit Daten“ aktiviert ist;
• einen Block mit Omniscol-Metadaten: die aufgerufene URL, den Code des Endpunkts, die Methode, die Parameter, das Authentifizierungstoken des Benutzers und die Kennung der Einrichtung;
• Nachverfolgungs-Header: X-OS-original-query, X-OS-original-endpoint, X-OS-auth und X-School.

Für das Ereignis Änderung des Stundenplans enthält der Aufruf, wenn die Option „mit Daten“ aktiv ist, zusätzlich ein Differenzial der Unterrichtsstunden (hinzugefügte, geänderte, gelöschte Unterrichtsstunden) — praktisch, um nur das weiterzugeben, was sich geändert hat.

Verhalten

Die Hooks starten im Hintergrund, nachdem der Vorgang des Benutzers gelungen ist: Sie verlangsamen die Oberfläche nicht und blockieren sie nicht bei einem Ausfall Ihres Servers. Ein ausgehender Aufruf, der nicht durchkommt, wird protokolliert, ohne die Arbeit in Omniscol zu unterbrechen. Jeder Aufruf hat eine kurze Ablauffrist (einige Sekunden): Ihr Server muss den Empfang schnell bestätigen und den Rest auf seiner Seite verarbeiten.

Gut zu wissen

• Die Omniscol-API stellt eine Teilmenge von Vorgängen bereit; eine Überschreibung oder ein Hook gilt nur für die tatsächlich bereitgestellten Endpunkte. Siehe Omniscol-API für die Liste und die Authentifizierung.
• Für eine Integration mit einer Softwarelösung (ERP, HR-System, digitale Arbeitsumgebung) ist die dedizierte Synchronisierung oft besser geeignet — siehe Synchronisierung mit externen Systemen. Intern wird dasselbe Hook-System verwendet.
• Damit ein KI-Agent Ihre Daten ohne Entwicklung abfragt, siehe MCP — einen externen KI-Agenten verbinden.