Schulintegration Prozess Layer

Der Schulintegration Prozess Layer ermöglicht Drittherstellern die Anbindung an CMI Schule.

Endpunkte

Der Prozess Layer beinhaltet folgende Controller mit Endpunkten:

Stammdaten

Es können allgemeine schulspezifische Stammdaten (wie z.B. Schuljahre, Schulstufen, Beziehungsarten, usw.) abgefragt werden * Die Schuljahre sind interessant wegen den Zeiträumen – die späteren Daten-Abfragen können mit einem Parameter zeitraum abgesetzt werden. * Die Anstellungsfunktionen und -gruppen können verwenden werden, sodass ein Endkunde in einer Auswahl auswählen/einschränken kann welche Personaldaten (gemäss Anstellungsfunktionen) sie erhalten wollen. Die Einschränkung/Filterung der gelieferten Daten ist dem Client des Prozesslayers überlassen.

Struktur

Ein CMI-Mandant kann mehrere Schulträger beinhalten.
Die möglichen Hierarchien sind: * Schulträger -> Schulkreis(e) -> Schuleinheit(en) -> Schulklassen * Schulträger -> Schuleinheit(en) -> Schulklassen

Die folgenden Daten-Abfragen beziehen sich immer auf genau 1 Schulträger (und optional auf 1 Schuleinheit).
Dieser Endpunkt ist benötigt für die Auswahl des Endkunden, von welchen Schuleinheit(en) nachfolgend Daten bezogen werden sollen.

Daten

Die Abfragen sind hierarchisch – mit der obersten Abfrage-Ebene (Selektion eines Schulträgers ist immer zwingend notwendig) wird komplett alles geliefert. Genauso wenn nur eine einzelne Schuleinheit abgefragt wird.

Endpunkte: * /Daten/schultraeger/:schultraegerGuid
/Daten/schultraeger/:schultraegerGuid/personal
/Daten/schultraeger/:schultraegerGuid/lernende
/Daten/schultraeger/:schultraegerGuid/schuleinheiten
/Daten/schultraeger/:schultraegerGuid/schuleinheiten/:schuleinheitGuid
/Daten/schultraeger/:schultraegerGuid/schuleinheiten/:schuleinheitGuid/personal
/Daten/schultraeger/:schultraegerGuid/schuleinheiten/:schuleinheitGuid/lernende
* /Daten/schultraeger/:schultraegerGuid/schuleinheiten/:schuleinheitGuid/schulklassen

Somit ist auch klar, dass z.B. das Personal bei einer Abfrage des gesamten Schulträgers wiederholt geliefert wird (sowohl auf Ebene Schulträger, wie auch auf Ebene Schuleinheit). Auf Ebene Schuleinheit wird aber nur das in der entsprechenden Schuleinheit involvierte Personal geliefert. Ebenso kann eine Lehrperson in mehreren Schuleinheiten geliefert werden (wenn Anstellungen in beiden Schuleinheiten vorliegen).

In den Endpunkten personal und lernende werden auch die ausführlichen Personendaten (Adressen, Bezugspersonen, uvm) geliefert. Wenn sonst auf eine Person referenziert wird (z.B. bei Klassenzuteilungen), dann wird dort lediglich eine Referenz auf die Person aufgeführt.

Die Daten werden basierend auf dem CMI Modell strukturiert geliefert. Jedes Objekt beinhaltet Objektdaten wie die GUID oder Typdefinition.

Die gelieferten Daten beinhalten:

/personal

• Personendaten
• Anstellungen
• Zuordnung Schulklassen
• Zuordnung Schulfächer
• Zuordnung Lernende
• SoPäMa Unterricht (bis Zuordnung zum Lernenden)

/lernende

• Personendaten
  • mit Beziehungen
  • mit SoPäMassnahmen

/schulklassen

• Lektionentafel (vorerst ohne Schulfächer)
• Klassendaten (mit Teilklassen; "Mischklassen" haben > 1 Teilklasse)
• Lehrpersonen (via Anstellung - Personaldossier - Person)
• Lernende (via Schullaufbahn - Lernendedossier - Person)
  • mit Lernendenzuteilungen (Lerncoach, SHP)
  • Schulfachzuteilungen
  • Absenzen

Filter 'Zeitraum'

Die Endpunkte in den Controllern Struktur und Daten liefern standardmässig Daten "per Heute".
Optional kann der Query Parameter zeitraum angegeben werden, um Daten in einem gewünschten Zeitbereich zu erhalten.

Format

Unterstützte Formate für den Parameter zeitraum sind:

• Stichtag
• Beispiel: 14.10.2026
• Datumsformat: dd.MM.yyyy
• Zeitraum
• Beispiel: 01.11.2026 - 31.01.2027
• Datumsformat: dd.MM.yyyy - dd.MM.yyyy

Datenfilterung

Ist der Query Parameter zeitraum angegeben, dann werden folgende Daten entsprechend gefiltert:

• Stammdaten
• werden nie gefiltert
• Struktur
• [ Schulträger | Schulkreis | Schuleinheit ]
• Daten
• [ Schulträger | Schuleinheit ]
  • werden nie gefiltert, da diese explizit via URL Parameter angegeben werden
• [ Personal ]
  • Personaldossier gemäss Beginn/Ende und muss Anstellung im Zeitraum enthalten
  • Personalanstellung
  • Anstellungspensum
  • Klassenzuteilung
  • Lernendenzuteilung
  • SoPäMaUnterricht
• [ Lernende ]
  • Lernendedossier gemäss Beginn/Ende und muss Schullaufbahn mit Klassenzuteilung(en) im Zeitraum enthalten
  • Liste aller Schullaufbahneinträge wird nicht gefiltert, da benötigt für Auslesen von Ein/Aus/Übertrittsdaten
  • Person: [ Beziehung | Medizinische Informationen ]
  • SoPäMassnahmen
• [ Schulklassendossiers | Fachklassendossiers | Sammelklassendossiers | ExterneSchulklassendossiers ]
  • Schuljahr des Dossiers muss im Zeitraum liegen
    Teilklasse(n) müssen Lernende oder Lehrpersonen zugewiesen haben (ohne Prüfung des Zeitraums)
  • Kantonale Lektionentafel
  • Klassenzuteilung Lehrperson
  • Klassenzuteilung Lernende
  • Schullaufbahn des Schuljahrs vom Dossier
    • Absenzen: nicht gefiltert - alle im Zeitraum der Schullaufbahn
    • Lernendenzuteilungen
    • Schulfachzuteilungen: nicht gefiltert - alle im Zeitraum der Schullaufbahn

Guids für Fremdsysteme

Als Referenz in einer Drittanwendung auf ein CMI Objekt empfiehlt sich die Guid.
Dabei wird folgendes empfohlen: - Personal: Personaldossier.Person.Guid
(Für eine Person kann es mehrere Personaldossiers geben) - Lernende: Lernendedossier.Person.Guid
(Für eine Person kann es mehrere Personaldossiers geben) - Schulklassen:
Je nach Bedarf kann im Fremdsystem 1 Schulklasse pro 'Teilklasse' (entspricht einer Schulklassenstufe) geführt werden. Oder es werden 'Mischklassen' unterstützt (entspricht in CMI einer Schulklasse mit mehreren Teilklassen) - Schulklassendossier.Guid | Schulklassendossier.Teilklasse.Guid
(in jedem Schuljahr wird ein neues Schulklassendossier für die 'Primar 1a' erstellt) - Schulklassendossier.Schulklassenplan.Guid | Schulklassendossier.Teilklasse.Teilklassenplan.Guid
(Die nächstjährige Schulklasse 'Primar 1a' wird die gleiche Planklassen Guid haben)

Objektdaten

Die Abfragen haben einen optionalen Query Parameter objektdaten = false.
Wird die Lieferung der Objektdaten aktiviert, dann werden zu jedem gelieferten Objekt noch angefügt: - TypedefinitionKey - Modificationdate - Creationdate

Diese Angaben könnten verwendet werden als Hinweis, ob ein Objekt Neuerungen (seit der letzten Abfrage) beinhaltet. Dabei ist zu beachten, dass auch Änderungen auf nicht im Prozesslayer gelieferten Eigenschaften zu neuen Änderungsdatum führen.

Die Angabe TypedefinitionKey ist interessant, wenn zusätzlich noch die generische CMI API verwendet wird. Es ist jedoch empfehlenswert, diese Angaben nur zu Entwicklungszwecken abzufragen, da die Typdefinition sich nicht ändert. Ebenso ist durch die Bezeichnung der Objekte gemäss Swagger klar um welche TypDefinition es sich handelt.

Generische CMI Api

Die generische API kann individuell konfiguriert werden, sodass z.B. Absenzen erstellt werden können. Da über den Schulintegration Prozesslayer alle Guids und Typdefinitionen der Objekte geliefert werden sind diese dem Dritthersteller bekannt. Mit diesen Angaben kann dann auch die generische CMI Api entsprechend ergänzend eingesetzt werden.