cmi-schule-escola-transferservice

Dieser Service dient dem unidirektionalen Austausch von Klassen-, Schüler- und Lehrpersonendaten zwischen CMI Schule und Escola. Escola holt Daten bei CMI Schule 1.0 ab.
CMI Schule 2.0 wird noch nicht unterstützt.

Inhaltsverzeichnis

cmi-schul-escola-transferservice
Inhaltsverzeichnis
Allgemeines
- Aufgabe
- Strategische Einordnung
Technisches
Installation
Troubleshooting
Change Log / Breaking Changes

Allgemeines

Status: In Entwicklung
Fachliche Ansprechperson: Heinz Bigler
Technische Ansprechperson: Heinz Bigler
Nur für speziellen Kunde: Nein, aber der Kunde muss CMI Schule 1.0 haben.

Aufgabe

URL: https://escolatransfer.cmicloud.ch/ExchangeSoapService.svc

Der Service stellt folgende GET-Methoden zur Verfügung:

Methode: CMI_getSchoolclassDefinitions

Return Value: CMI_getSchoolclassDefinitionsResponseCMI_getSchoolclassDefinitionsResult
Parameter: int semesterYear, int semesterPart
Resultat: Alle Stammklassen gefiltert nach Schuljahr und Semester

Methode: CMI_getSchoolclass

Return Value: CMI_getSchoolclassResponseCMI_getSchoolclassResult
Parameter: int semesterYear, int semesterPart, String classKey
Resultat: Eine Stammklasse mit classKey = guid "xy" gefiltert nach Schuljahr und Semester und Zugriffsrechten.

Das Resultat enthält Klasseninformationen, die Personendaten der Schüler und ihren Kontaktpersonen und Lehrpersoneninformationen.

Methode: CMI_getTeachers

Return Value: CMI_getTeachersResponseCMI_getTeachersResult
Parameter: int semesterYear, int semesterPart
Resultat: Alle aktiven Lehrpersonen gefiltert nach Schuljahr und Semester und Zugriffsrechten

Methode: CMI_getStudyGroupDefinitions

Return Value: CMI_getStudyGroupDefinitionsResponseCMI_getStudyGroupDefinitionsResult
Parameter: int semesterYear, int semesterPart
Resultat: Alle Fachklassen gefiltert nach Schuljahr und Semester und Zugriffsrechten

Methode: CMI_getStudyGroup

Return Value: CMI_getStudyGroupResponseCMI_getStudyGroupResult
Parameter: int semesterYear, int semesterPart, String groupKey
Resultat: Eine Fachklasse mit groupKey = guid "xy" gefiltert nach Schuljahr und Semester und Zugriffsrechten

Strategische Einordnung

Der Service ist eine Schnittstelle für CMI Schule, die Kunden optional dazu nehmen können. Diese Schnittstelle ersetzt keine vorherige Schnittstelle. Es handelt sich um eine aktive Schnittstelle die verkauft wird.

Technisches

Eigenschaften

Die Komponente erfüllt folgende Eigenschaften:

Stateless: Ein Request, der von Escola an die Schnittstelle gesendet wird, ist in sich abgeschlossen. Es gibt keine Abhängigkeit zwischen den Datenlieferungen.
Mehrmandantenfähig: Ja, über Einträge im tenants.json
Proxyfähig: Vermutlich ja, die Anwendung verhält sich zustandlos.

Abhängigkeiten

Folgende Services verwendet die Komponente:

Service	Version	Anbindung	Protokoll	Standardports	Verfügbarkeit	Fehlertoleranzklasse
* CMI Server	>= 20.1	on request	http/s	CMI Server Owin Private Port	Muss	Reconnect
Escola	-	on request	https / SOAP	443	-	-
STS	>= 1.5	on request	https	443	** Muss	Reconnect

* Im CMI muss ein Benutzer angelegt werden, der als technischer User für die Schnittstelle dient. Mit diesem Benutzer werden Daten vom CMI abgefragt.
** Nur erforderlich für Mandanten, die einen STS einsetzen.

Fehlertoleranz

Escola kontaktiert die Schnittstelle von sich aus. Die Schnittstelle tritt nur als Server auf. Diese Schnittstelle hat bis auf die SOAP-Contract keine speziellen Abhängigkeiten zu Escola.

Wenn eine Anfrage von Escola an die Schnittstelle gesendet wird, wird die Schnittstelle die Anfrage an den CMI Server weiterleiten. Ggf. wird der STS kontaktiert um ein Access-Token zu erhalten. Ist der CMI Server oder der STS nicht erreichbar, schlägt die Anfrage fehl. Bei der nächsten Anfrage wird jedoch versucht, den CMI Server und/oder den STS erneut zu kontaktieren.

Sequenzdiagramm

Kommunikation ohne STS

Sequenzdiagramm

Kommunikation mit STS

Wenn der angefragte Mandant STS im Einsatz hat und die entsprechenden Einträge im tenants.json vorhanden sind, wird das Token beim STS geholt. Die restliche Kommunikation bleibt sich die gleiche.

Technologiestack

Folgende Technologien werden eingesetzt: * ASP.NET Core 8.0 * SoapCore 1.0.0

Installation

Diese Dokumentation geht davon aus, dass die Schnittstelle mit einem IIS betrieben wird. Für ASP.Net Core Anwendungen gibt es aber noch andere Betriebsformen. Siehe hierzu auch die Dokumenation von Microsoft.

Systemvoraussetzungen

Folgende Komponenten müssen auf dem System installiert/vorhanden sein:

Windows Server 2012 R2 or later
ASP.NET Core 8.0 Runtime (v8.0.0) - Windows Hosting Bundle Installer
IIS

Installationsanleitung

IIS

Die Binaries an geeigneter Stelle entspacken.
Einen IIS Application Pool anlegen. Achtung wg. .NET Core: Jede Instanz der Schnittstelle benötigt einen eigenen Application Pool. Dieser darf nicht mit einer anderen App geteilt werden. .NET CLR Version: No managed code.
Eine IIS Site oder IIS Application erstellen, die den Application Pool und das entpackte Verzeichnis verwendet.
Konfiguration in den Json-Dateien vornehmen. Mindestens minimale Konfiguration im tenants.json sind erforderlich.

CMI Server:

Einen technischen Benutzer im CMI einrichten, Mitgliedschaften auf die berechtigten Schulen setzen.
Berechtigungen: Schulverwaltung lesen
In CMI Schule > Stammdaten > Einstellungen > Lehreroffice
Für den erstellten technischen Benutzer einen Eintrag erfassen

Entwicklerhinweise

Clonen des Repositories
Einen technischen Benutzer im CMI ablegen (siehe auch Installationsanleitung)
Um den Client zu starten muss die Solution für "Multiple Startup projects ...." konfiguriert sein

Project	Action
CMI.Schule.Escola.Transfer.Service	Start
CMI.Schule.Escola.Transfer.Client	Start
4. Ggf. muss die Datei launchSettings.json für den Entwicklerrechner angepasst werden.

Konfigurationsmöglichkeiten

Globale Konfiguration: `appsettings.json`

{
  "AllowedHosts": "*",
  "Serilog": {
    "Using": [ "Serilog.Sinks.File"],
    "MinimumLevel": "Error",
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "PathFormat": "log-{Date}.txt",
          "RollingInterval": "Day",
          "RetainedFileCountLimit": 10
        }
      },
      { "Name": "Console" }
    ],
    "Enrich": [ "FromLogContext", "WithMachineName", "WithThreadId" ],
    "Properties": {
      "Application": "CMI.Schule.Escola.Transferservice"
    }
  },
  "GraphQlUrl": "/api/core/GraphQl/Execute",
  "SettingsUrl": "/api/schulverwaltung/Data/GetSettings?subkey=lehreroffice",
  "ServiceVersionUrl": "/api/core/ServerInfo/GetServiceInfo",
  "SchulverwaltungVersionUrl": "/api/schulverwaltung/Info/GetSchulverwaltungVersion",
  "Tenants.json": "tenants.json",
}

Attribut	Wert
AllowedHosts	Microsoftdokumentation
Serilog	Serilog Dokumentation
GraphQlUrl	Api - Pfad für den Aufruf von GraphQL (Datenabfrage)
SettingsUrl	Api - Pfad, um die relevanten Settings aus der STM - Tabelle auszulesen
ServiceVersionUrl	Api - Pfad, um die Version vom CMI Server auszulesen
SchulverwaltungVersionUrl	Api - Pfad, um die Version von CMI Schule auszulesen (Service unterstützt CMI Schule 2.0 noch nicht)
Tenants.json	Pfad zum File `tenants.json`, z.B. `"tenants.json"` oder `"C:\\Configs\\tenants.json"`

Mandantenkonfiguration: `tenants.json`

"apiKeys": [
  {
    "tenantId": "TENANT ID",
    "key": "API-KEY"
  }
],
"tenants": [
  {
    "id": "TENANT ID",
    "users": [
      {
        "username": "USERNAME",
        "password": "xyz"
      }
    ],
    "serverService": {
      "privateUrl": "PRIVATE URL"
    },
    "sts": {
      "enabled": false,
      "stsTokenEdnpoint": "TOKEN ENDPOINT",
      "secret": "STS SECRET",
      "apiServerId": "TENANT ID",
      "clientId": "CLIENT ID"
    },
    "SchulfunktionstypenToReturn": [
          "FUNKTIONSBEZEICHNUNG 1",
          "FUNKTIONSBEZEICHNUNG 2"
      ]
  }
]

ApiKeys

TenantId ID des Mandanten (unter Tenants konfiguriert)
Key API Key welcher für die Authentifizierung gebraucht wird (beliebig - möglichst lang und zufällig)

Tenants

Id ID des Mandanten

Users - username Technischer Benutzer - password Kennwort des technischen Benutzers bei BuiltIn Authentifizierung (nur benötigt bei BuiltIn Authentifizierung ohne STS, ansonsten weglassen). Übersteuert das in der Soap-Anfrage übermittelte ServiceAuthHeader.Password.

ServerService - PrivateUrl Url des Services inkl. private Owin-Port

STS (Nur falls STS vorhanden) - Enabled (true/false) Einstellung um STS zu aktivieren - StsTokenEndpoint STS Url inkl. Port - Secret Secret welches im STS-Konfig definiert ist (Wiki-Anleitung) - ApiServerId ID des Mandanten, die in den SERVEREINSTELLUNGEN des CMI Mandanten eingetragen wurden.

STS 3 (zusätzlicher Eintrag unter STS, falls STS 3 eingesetzt wird.) - ClientId Client ID der Escola API. Dieser Wert wird für STS3 benötigt.

SchulfunktionstypenToReturn - Liste mit Bezeichnungen. Lehrpersonen mit Profilen vom Typ "Andere Schulfunktion" mit den aufgeführten Bezeichnungen werden dann ebenfalls geliefert.

Ausführung in Entwicklungsumgebung: `launchSettings.json`

Diese Datei ist für die Ausführung der Schnittstelle mit der Entwicklungsumgebung relevant. Für den Produktivbetrieb ist sie nicht erforderlich.

{
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "cmi_schule_escola_transferservice": {
      "commandName": "Project",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      },
      "applicationUrl": "https://localhost:5001;http://localhost:5000"
    }
  },
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:51779",
      "sslPort": 44388
    }
  }
}

SOAP Request

Die Soap Anfragen an den Service beinhalten den folgenden ServiceAuthHeader:

    <soap:Header>
        <ServiceAuthHeader xmlns="http://www.cmiag.ch/xmlns/soap/2010/exchange-v1">
            <username>{{serviceauth_username}}</username>
            <password>{{serviceauth_password}}</password>
            <apiKey>{{serviceauth_apiKey}}</apiKey>
        </ServiceAuthHeader>
    </soap:Header>

Diese Angaben müssen mit der Konfiguration in tenants.json wie folgt übereinstimmen: - apiKey ApiKeys -> Key (die TenantId verweist dann auf den Konfigurationsabschnitt für den Mandanten) - username Muss im Mandant unter Users erfasst sein. - password Relevant nur bei BuiltIn Authentifizierung - dann entspricht das dem Kennwort des technischen Benutzers. Seit Version 2.0 kann dieses Kennwort jedoch in tenants.json übersteuert werden. Bei Einsatz eines STS kann (resp. muss) ein beliebiger, belangloser Wert eingetragen werden.

Troubleshooting

Mittels der Postman Collection kann ein POST-Request an die Schnittstelle gemacht werden, um zu schauen ob die Schnittstelle grundlegend reagiert.

<aspNetCore 
    processPath="dotnet"
    arguments=".\CMI.Schule.Escola.Transfer.Service.dll"
    stdoutLogEnabled="true"
    stdoutLogFile="E:\Custom_Deployments\multitenant_escola_transfer_service\log\stdoutLog"
    hostingModel="inprocess" />

Change Log

v.3.4

appsettings.json: Pfad zum File tenants.json kann konfiguriert werden

v.3.3

Konfiguration: Hot Reload

v.3.2

Logging, Instrumentation und Metrik via CMI.Infrastructure.Telemetry

v.3.1

Package Updates

v.3.0

Framework Update: ASP.NET Core 8.0

v.2.2

CMI.STS.Client: Aktualisiert auf v.116.0.4
Optimierung bei der Abfrage des STS Discovery Dokuments, erweitertes Log

v.2.1

Verstorbene Personen werden nur noch geliefert, falls das Todesdatum nach dem Stichdatum der Abfrage liegt. Dies betrifft Schulkinder, Lehrpersonen und Bezugspersonen.
Das Todesdatum wird als Element dateOfDeath im Format yyyy-mm-dd ausgeliefert.
Beziehungen werden nur ausgeliefert, falls sie zum Stichdatum der Abfrage gültig sind.

v.2.0

Framework Update: ASP.NET Core 6.0
CMI.STS.Client: Fix "Do not cache invalid discovery documents"
Erweiterung: Kennwort des technischen Benutzers bei BuiltIn Authentifizierung kann in tenants.json gesetzt werden (dann wird das in der Soap-Anfrage übermittelte ServiceAuthHeader.Password übersteuert)

cmi-schule-escola-transferservice

Inhaltsverzeichnis

Allgemeines

Aufgabe

Strategische Einordnung

Technisches

Eigenschaften

Abhängigkeiten

Fehlertoleranz

Sequenzdiagramm

Technologiestack

Installation

Systemvoraussetzungen

Installationsanleitung

Entwicklerhinweise

Konfigurationsmöglichkeiten

Globale Konfiguration: appsettings.json

Mandantenkonfiguration: tenants.json

ApiKeys

Tenants

Ausführung in Entwicklungsumgebung: launchSettings.json

SOAP Request

Troubleshooting

Change Log

v.3.4

v.3.3

v.3.2

v.3.1

v.3.0

v.2.2

v.2.1

v.2.0

Globale Konfiguration: `appsettings.json`

Mandantenkonfiguration: `tenants.json`

Ausführung in Entwicklungsumgebung: `launchSettings.json`