Skip to content

Educauser Process Layer

Übersicht

Der Educauser Process Layer wurde für den Kanton Appenzell im Rahmen des NASA Projekts entwickelt und ermöglicht die Weiterverarbeitung von Schuldaten durch EducaX und AiAddress (Drittsysteme der Firma BKO Soft)

Context Diagram

Für eine detaillierte Übersicht siehe Architektur Für technische Details zur Systemarchitektur siehe C4 Modell

Konfiguration

Um den Betrieb sicherzustellen müssen folgende Einstellungen und KPF Anpassungen vorgenommen werden.

Detaillierte Konfigurationsanweisungen finden Sie in der Konfigurationsdokumentation

KPF

  • Ein Feld "customVoiceEnabled" (boolean) muss im KPF auf der Person angelegt worden sein.

Begründung: Wird von BKO Soft für die Integration in ihre Kommunikationslösungen benötigt.

Klassenplan und Teilklassenplan

  • Jede Schulklasse muss einem Schulklassenplan zugewiesen worden sein.
  • Jede Teilklasse muss einem Teilklassenplan zugwiesen worden sein.

Begründung: EducaX benötigt eine eindeutige Zuteilung einer Klasse in ein "Gefäss" das für jede Klasse einer Stufe gleich bleibt. In CMI entsprechen diese (Teil-)Klassengefässe den (Teil-)Klassenplänen.

Troubleshooting: Fehlende Daten im Export

Schuleinheit nicht sichtbar

Wenn eine Schuleinheit nicht im Export erscheint, prüfen Sie:

  • Die Schuleinheit muss aktiv sein (inaktiv[NO])
  • Der Zeitraum (VonBis) der Schuleinheit muss gültig sein
  • Die Schuleinheit muss einem aktiven Schulträger oder Schulkreis zugeordnet sein
  • Der übergeordnete Schulträger muss aktiv sein und einen gültigen Zeitraum haben
Schule nicht sichtbar

Wenn eine Schule (Schulträger) nicht im Export erscheint, prüfen Sie:

  • Der Schulträger muss aktiv sein (inaktiv[NO])
  • Der Zeitraum (VonBis) des Schulträgers muss gültig sein
  • Bei Schulkreisen: Der übergeordnete Schulträger muss ebenfalls aktiv sein und einen gültigen Zeitraum haben
Teilklasse nicht sichtbar

Wenn eine Teilklasse nicht im Export erscheint, prüfen Sie:

  • Die Teilklasse muss mindestens eine Klassenzuteilung eines Lernenden haben
  • Das zugehörige Schuljahr muss aktiv sein (vonBis[T])
  • Der Teilklassenplan muss korrekt zugewiesen sein
  • Die übergeordnete Schulklasse muss einen gültigen Schulklassenplan haben
  • Die Klassenzuteilungen der Lehrpersonen müssen einen gültigen Zeitraum haben (vonBis[T])

Entwickler-Hinweis: Die Sichtbarkeit wird durch die GraphQL-Queries in src\ProcessLayers\CMI.API.Process.Educauser\Repositories\GraphQl\Search*.txt ermittelt. Alle oben genannten Bedingungen müssen erfüllt sein, damit die Daten im Export erscheinen.

Schuljahrperioden

Die Schuljahrperioden spielen eine zentrale Rolle bei der Aggregation und Filterung von Daten in den Export-Endpunkten.

Endpunkt-Parameter

Die folgenden Endpunkte verwenden Datums-Filter für die Filterung:

  • GET /export/pks
  • Filtert Personen-Klassen-Semester Zuordnungen

  • Parameter:

    • created: Erstellungsdatum (Format: dd.MM.yyyy(-dd.MM.yyyy))
    • updated: Änderungsdatum (Format: dd.MM.yyyy(-dd.MM.yyyy))
    • expired: Ablaufdatum (Format: dd.MM.yyyy(-dd.MM.yyyy))
    • valid: Gültigkeitsdatum (Format: dd.MM.yyyy(-dd.MM.yyyy))

  • GET /export/schulklassen

  • Filtert Schulklassen
  • Parameter: Identisch zu /export/pks

Format-Beispiele:

  • Einzeldatum: 31.12.2023
  • Datumsbereich: 01.01.2023-31.12.2023
  • Ab Datum: 01.01.2023-
  • Bis Datum: -31.12.2023

Validierungen:

  • Erstellungsdatum muss vor Änderungsdatum liegen
  • Erstellungsdatum muss vor Ablaufdatum liegen
  • Änderungsdatum muss vor Ablaufdatum liegen
  • Bei Datumsbereichen muss das Von-Datum vor dem Bis-Datum liegen
  • Erstellungs- und Änderungsdatum dürfen nicht in der Zukunft liegen

Daten-Aggregation

Die Schuljahrperioden werden auf zwei Ebenen verwendet:

  1. Schuljahr-Ebene
  2. Jedes Schuljahr enthält mehrere Schuljahrperioden (z.B. Semester)

  3. Die Perioden haben jeweils einen eigenen Gültigkeitszeitraum (dauerVonBis)

  4. Klassen-Ebene

  5. Schulklassen und Teilklassen werden über ihre Schulklassen- und Teilklassenpläne mit Perioden verknüpft
  6. Der Mapper aggregiert Perioden aus zwei Quellen:
    • Perioden aus dem Teilklassenplan der Klasse
    • Perioden aus den Schulklassenplänen der Schuleinheit

Technischer Hinweis: Die Aggregation der Perioden erfolgt im PersonenKlassenSemesterResponseMapper. Dort werden Perioden aus beiden Quellen gesammelt und dedupliziert, um eine vollständige Liste der verfügbaren Perioden zu erhalten.

Troubleshooting

Wenn Daten in einer bestimmten Schuljahrperiode fehlen, prüfen Sie:

  1. Gültigkeitszeitraum
  2. Die dauerVonBis der Schuljahrperiode muss korrekt gesetzt sein

  3. Das übergeordnete Schuljahr muss aktiv sein (vonBis[T])

  4. Verknüpfungen

  5. Die Schulklasse muss einem gültigen Schulklassenplan zugeordnet sein
  6. Die Teilklasse muss einem gültigen Teilklassenplan zugeordnet sein
  7. Die Pläne müssen mit dem korrekten Schuljahr verknüpft sein

Gebiete mit Gebiettyp Schule

  • Personen müssen einem Gebiet mit dem Gebietstyp "Schule" zugewiesen worden sein.

Begründung: Die Daten des Export und AiAddress Endpunkt werden von BKO Soft für die Fakturierung weiterverarbeitet. Dazu muss die ID der Schulgemeinde bekannt sein an der die Person am 31.12. angemeldet war.

Berechnung der SGID

Die SGID (Schulgemeinde-ID) wird wie folgt ermittelt:

  1. Normale Berechnung:

  2. Die SGID wird aus dem Gebiet mit Gebietstyp "Schule" (Code 14) ermittelt

  3. Es wird das Gebiet verwendet, dem die Person am 31.12. des aktuellen Jahres zugewiesen ist
  4. Die SGID entspricht dem Code des Gebiets

Referenz zur Query:

19:26:src/ProcessLayers/CMI.API.Process.Educauser/Repositories/GraphQl/QueryPerson.txt gebiete(tentaQl: "Gebiet WHERE dauer[T] AND inaktiv[NO] AND gebietstyp CONTAINS(Gebietstyp WHERE code[14])") { items { code dauer { $FRAGMENT_QUERY_ZEITPUNKT$ } } }

  1. SGID = 0 tritt auf wenn:

  2. Die Person keinem Gebiet mit Gebietstyp "Schule" zugewiesen ist

  3. Die Gebietszuweisung nicht im relevanten Zeitraum gültig ist (nicht am 31.12. aktiv)
  4. Das Gebiet als inaktiv markiert ist

  5. Die Dauer (VonBis) des Gebiets nicht korrekt gesetzt ist

  6. Behebung einer SGID = 0:

a) Gebietszuweisung prüfen:

  • Person einem Gebiet mit Gebietstyp "Schule" zuweisen
  • Sicherstellen, dass das Gebiet aktiv ist (inaktiv[NO])

b) Gültigkeitszeitraum korrigieren:

  • Die Dauer der Gebietszuweisung muss den 31.12. des aktuellen Jahres einschließen
  • Das Feld dauer im Gebiet korrekt setzen (dauer[T])

c) Gebietstyp überprüfen:

  • Sicherstellen, dass der Gebietstyp den Code 14 hat
  • Query-Bedingung: gebietstyp CONTAINS(Gebietstyp WHERE code[14])

Wichtig: Die SGID ist essentiell für die Fakturierung durch BKO Soft. Eine SGID = 0 führt zu Problemen bei der Weiterverarbeitung der Daten.

Fehlende Daten von Organisationseinheiten

Wenn Daten einer Organisationseinheit nicht in der API erscheinen, überprüfen Sie folgende Punkte:

  1. Personalanstellung prüfen
  2. Die Organisationseinheit muss aktive Personalanstellungen haben
  3. Die Personalanstellungen müssen ein gültiges Personaldossier besitzen

  4. Das Personaldossier muss einer Person zugewiesen sein

  5. Gültigkeitszeitraum

  6. Der Zeitraum (VonBis) der Organisationseinheit muss gültig sein

  7. Die Personalanstellung muss im abgefragten Zeitraum gültig sein

  8. Adressdaten

  9. Wenn Adressdaten fehlen: Prüfen Sie, ob die Adressen als "inaktiv" markiert sind

  10. Nur aktive Adressen werden in der API angezeigt

  11. Berechtigungen

  12. Der API-Benutzer muss Leserechte auf die Organisationseinheit haben

  13. Der API-Benutzer muss Leserechte auf die verknüpften Personalanstellungen und Personaldossiers haben

  14. Gebietszuordnung

  15. Die Person muss einem Gebiet mit dem Gebietstyp "Schule" zugewiesen sein
  16. Die Gebietszuordnung muss im abgefragten Zeitraum gültig sein

Hinweis: Die Datenabfrage erfolgt über GraphQL und filtert Datensätze basierend auf den oben genannten Kriterien. Wenn eines dieser Kriterien nicht erfüllt ist, wird die Organisationseinheit oder deren Daten nicht in der API angezeigt.

Basierend auf den GraphQL-Queries und der Dokumentation, hier die Erklärung zur SGID-Berechnung im Export Controller:

API

Der Prozesslayer besteht aus 3 Controllern:

Für Entwicklerinformationen siehe EntwicklerInformationen Für Fehlerbehandlung siehe Fehlerbehandlung Für Testinformationen siehe Testing und Testprotokoll

AiAddress-Controller

Controller für die Integration mit AiAddress. Ein Tool der BKO Soft.

Ressource Beschreibung
GET /aiaddress/persons Liefert Personendaten
GET /aiaddress/addresses Liefert Addressen der Personen
GET /aiaddress/contacts Liefert Kontaktinformationen der Personen

Export-Controller

Controller für den Export von Schuldaten. Umfasst Schuleinheiten, Schuljahre, Schulklassen, Schulpersonal, Schüler und deren gesetzlichen Vertreter

Ressource Beschreibung
GET /export/personen Angehörige und Entitäten der Schulen bereit Details
GET /export/pks Informationen über die Zugehörigkeit einer Person zu einer Klasse Details
GET /export/plz Ortschaftsverzeichnis Details
GET /export/schulklassen Informationen über die Schulklassen, Teilklassen und die Schulstufe Details
GET /export/schuljahre Informationen über Schuljahr und Schuljahrperiode Details

Die Contracts der einzelnen Endpunkte hängen wie folgt zusammen:

Export-Controller

Integration-Controller

Controller für die Integration mit anderen Systemen.

Ressource Beschreibung
GET /integration/persons Liste aller Personen aus dem System
GET /integration/lernendedossiers Liste aller Lernendedossiers aus dem integrierten System
GET /export/integration/schulklassendossiers Liste aller Schulklassendossiers aus dem integrierten System

Weitere Dokumentation