Datenaustausch mit Sdui

Sdui bietet Schulen eine DSGVO-konforme Lösung in der digitalen Kommunikation und Organisation mit Lehrern, Schülern und Eltern an. DAVINCI kann Stundenplandaten mit Sdui abgleichen. Diese werden dann in der Sdui-App angezeigt. Die Übertragung kann manuell oder automatisiert erfolgen.

Der Workflow sieht grob wie folgt aus:

Die DAVINCI CONSOLE liest Daten direkt aus einer DAVINCI-Datei oder von einem DAVINCI-Server und überträgt diese in Ihre Sdui-Instanz
Mit dem PowerShell-Modul PSDaVinci können Sie den Workflow mit einem einzigen Befehl ausführen.
Dieser Vorgang kann über die Windows Aufgabenplanung automatisiert werden.

Voraussetzungen

Es werden PowerShell 7, das PowerShell-Modul PSDaVinci und natürlich eine Installation von DAVINCI benötigt.

PowerShell 7

Die Systemvoraussetzungen für eine erfolgreiche Ausführung der PowerShell-Skripte ist PowerShell 7. PowerShell 7 ist nicht Teil des Betriebssystems und muss separat installiert werden.

Öffnen Sie die Download-Webseite für PowerShell 7 auf GitHub in Ihrem Web-Browser.
Laden Sie das passende Installationpaket herunter. In der Regel wird dies das MSI-Paket für Windows 64bit sein (z.B. PowerShell-7.1.3-win-x64.msi).
Starten Sie das MSI-Paket auf Deinem Computer und folgen Sie den Anweisungen.

Die Ausführung von lokalen PowerShell-Skripten unter Windows Server 2019 ist standardmäßig erlaubt, unter Windows 10 jedoch nicht. In der Regel kann man mit der Ausführungsrichtlinie RemoteSigned gut leben.

Tippen Sie im Suchfeld der Windows-Taskleiste powershell 7 oder pwsh ein und starten Sie PowerShell als Administrator.
Tippen Sie Set-ExecutionPolicy RemoteSigned ein und bestätigen Sie.

Jetzt können Sie lokale PowerShell-Skripte problemlos starten.

Hinweis

Einen ausführlicheren Blog-Artikel zur Installation und Nutzung von PowerShell 7 finden Sie hier.

PSDaVinci

Hinweis

PSDaVinci ist ein PowerShell-Modul, welches den Workflow zwischen DAVINCI und Sdui orchestriert. PSDaVinci stellt die folgenden PowerShell-Befehle bereit: Initialize-DaVinciExport sdui legt ein Konfigurationsdatei an Start-DaVinciExport sdui Übertragung der Daten aus DAVINCI nach Sdui

Installieren Sie das PowerShell-Modul PSDaVinci:

Tippen Sie im Suchfeld der Windows-Taskleiste powershell 7 oder pwsh ein und starten Sie PowerShell.
Tippen Sie Install-Module PSDaVinci ein und bestätigen Sie mit der Eingabetaste.
Beantwortn Sie die anschließende Frage, ob Sie der PowerShell Gallery (PSGallery) vertrauen möchten mit Yes.

Das PowerShell-Modul wird nun installiert.

Hinweis

Die PowerShell Gallery ist ein öffentliches Repository für PowerShell-Skripte und -Module, das von Microsoft bereitgestellt wird. Da derartige Skripte theoretisch auch Unfug treiben können, wird bei jeder Installation eines PowerShell-Moduls explizit gefragt, ob man der Quelle trauen möchte. Da wir nett sind, kann man uns natürlich trauen. Im Zweifel kann man aber auch den Quellcode inspizieren.

Konfiguration

Legen Sie im Windows-Explorer ein neues Verzeichnis c:\davinci an (das Verzeichnis kann natürlich auch anders heißen).
Starten Sie PowerShell 7 über das Windows-Menü: Start > Windows Powershell > Windows Powershell
Wechseln Sie mit folgendem Befehl in das soeben angelegte Verzeichnis mit:

cd c:\davinci
Tippen Sie nun folgenden PowerShell-Befehl ein:

Initialize-DaVinciExport sdui davinci.json

Es wird jetzt eine Konfigurationsdatei davinci.json angelegt, die als Vorlage für die weitere Konfiguration dient.

Konfigurieren der json Datei

Die gesamte Konfiguration des Imports befindet sich in der Textdatei davinci.json. Öffnen Sie diese Datei in einem Texteditor und überschreiben die gewünschten Eigenschaften.

Die folgende Eigenschaft muss angepasst werden. Sie konfiguriert den individuellen Zugang zu Sdui:

Eigenschaft	Bedeutung
`daVinci.SduiExport.SduiPIN`	Admin-PIN aus Sdui

Die Admin-PIN für Sdui finden Sie in Sdui unter Administration > Stundenplan > Synchronisation.

Die folgenden Eigenschaften müssen beim Abgleich von einer lokalen DAVINCI-Datei überschrieben werden:

Eigenschaft	Bedeutung
`daVinci.SduiExport.SourceProvider`	Wert = `File`
`daVinci.SduiExport.SourceFileName`	Vollständiger Dateiname der DAVINCI-Datei

Die folgenden Eigenschaften müssen beim Abgleich von einer DAVINCI-Datei, die auf einem DAVINCI-Server gehostet wird auf alle Fälle überschrieben werden:

Eigenschaft	Bedeutung
`daVinci.SduiExport.SourceProvider`	Wert = `Server`
`daVinci.SduiExport.ServerName`	Servername des DAVINCI-Servers im lokalen Netzwerk. `DAVINCI Explorer > Server > Serverinformationen`
`daVinci.SduiExport.ServerPort`	Portnummer des DAVINCI-Servers im lokalen Netzwerk. (Standard ist 8100)`Systemsteuerung > DAVINCI Server > Netzwerk`
`daVinci.SduiExport.ServerUserName`	Ein DAVINCI-Benutzername.`DAVINCI Explorer > Benutzer`
`daVinci.SduiExport.ServerPassword`	Ein DAVINCI-Benutzerkennwort.`DAVINCI Explorer > Benutzer`
`daVinci.SduiExport.ServerFileID`	Die GUID der DAVINCI-Datei auf dem DAVINCI-Server.`DAVINCI Explorer > Plandatei > Start > Eigenschaften`

Es empfiehlt sich einen seperaten DAVINCI-Benutzer für diese Funktion anzulegen, er muss lediglich das Recht haben, sich an DAVINCI anmelden zu können.

Bitte schauen Sie hier,wenn Sie Fragen zur Einrichtung der Benutzer in DAVINCI haben.

Alle anderen Eigenschaften sind schon vorkonfiguriert, können aber natürlich jederzeit überschrieben werden.

Hinweise

Der Backslash (= umgedrehter Schrägstrich) in Dateipfaden muss in einer JSON-Datei stets gedoppelt werden, also \\ statt \.
Einige Zeilen in der json Datei sind mit einem "-" versehen. Diese Zeilen sind auskommentiert. Je nachdem, ob Du nun mit einer lokalen DAVINCI Datei oder mit einer Datei auf dem DAVINCI Server arbeitest, musst Du die "-" entsprechend setzen oder löschen. Bitte schauen dazu auch die nachfolgenden Beispiele an, dort sind für beide Beispiele die benötigten Zeilen enthalten und das "-" ist jeweils entfernt.

Beispiel für eine lokale DAVINCI Datei

Das Ergebnis für den Abgleich mit einer lokalen DAVINCI-Datei könnte wie folgt aussehen:

{
    "daVinci": {
        "SduiExport": {
            "SduiPIN": "abc-def-ghi",
            "SourceProvider": "File",
            "SourceFileName": "davinci\\beispiel.daVinci",
        }
    }
}

Beispiel für eine DAVINCI-Serverdatei

Das Ergebnis für den Abgleich mit einer DAVINCI-Datei, die auf einem DAVINCI-Server gehostet wird, könnte wie folgt aussehen:

{
    "daVinci": {
        "SduiExport": {
            "SduiPIN": "abc-def-ghi",
            "SourceProvider": "Server",
            "ServerName" : "localhost",
            "ServerPort" : "8100",
            "ServerUserName" : "admin",
            "ServerPassword" : "qwertz",
            "ServerFileID" : "{c24f1a9d-692c-47aa-9046-db444b9f0c8e}"
        }
    }
}

Testen

Starten Sie PowerShell 7 über das Windows-Menü: Start > Windows Powershell > Windows Powershell
Wechseln Sie mit folgendem Befehl in unser DAVINCI-Verzeichnis:

cd c:\davinci
Tippen Sie folgenden PowerShell-Befehl ein:

Start-DaVinciExport sdui davinci.json

Die Daten aus DAVINCI werden direkt nach Sdui übertragen.

Automation

Die Synchronisation zwischen DAVINCI und Sdui kann automatisiert werden. Eine vollständige Automatisierung gelingt am besten über die Windows-Aufgabenplanung. Die Aufgabenplanung ist Bestandteil von Windows und ermöglicht das Starten von Anwendungen einmalig oder wiederkehrend zu festgelegten Zeitpunkten.

Ein Beispiel

Wir wollen, dass der Abgleich zwischen DAVINCI und Sdui alle 10 Minuten gestartet wird. Ein Upload erfolgt nur dann, wenn es auch Änderungen in DAVINCI seit dem letzten Abgleich gegeben hat. Da dieser Prozess im Hintergrund läuft, soll die Ausgabe in einer Textdatei geloggt werden, so dass nachträglich geprüft werden kann, ob die Aktion erfolgreich war oder nicht. Dabei soll jeden Tag eine neue Textdatei angelegt werden. Die Konfigurationsdatei ist in unserem Beispiel unter c:\davinci\davinci.json gespeichert.

!!! warning wichtig: Damit ein Logfile angelegt wird, bitte vorher den Ordner logs unter c:\davinci anlegen!

Los geht's:

Starten Sie die Aufgabenplanung, indem Sie im Suchfeld der Windows-Taskleiste "Aufgabenplanung" eintippen.
Klicken Sie in der Aufgabenplanung in der rechten Aktionsleiste auf Aufgabe erstellen. Es öffnet sich ein Dialogfenster.
Tippen Sie auf der Registerkarte Allgemein einen Namen für Ihre neue Aufgabe ein und optional eine Beschreibung.
Wechseln Sie auf die Registerkarte Trigger und klicken Sie auf Neu. Jetzt müssen Sie definieren, wie oft der Abgleich ausgeführt werden soll. Wählen Sie Täglich aus und tragen Sie unter Wiederhole jede 10 Minuten ein. Bestätigen Sie mit OK.

Wechseln Sie nun auf die Registerkarte Aktionen und klicken Sie auf Neu. Jetzt müssen Sie definieren, was denn nun geschehen soll. Belassen Sie die Auswahl bei Programm starten und tragen Sie in die drei Eingabefelder folgende Angaben ein:

Feld	Eingabe
Programm/Skript	`pwsh.exe`
Argumente hinzufügen	`-command "& {Start-DaVinciExport sdui .\davinci.json *> .\logs\log-sdui-$(Get-Date -f yyyy-MM-dd).txt}"`
Starten in (optional)	`c:\davinci` Bitte prüfen Sie, ob das Verzeichnis "davinci" an der Stelle angelegt wurde und ggfs. passen Sie bitte den Pfad an. Bitte im davinci-Verzeichnis ein neues Verzeichnis "logs" erstellen!

Das Ganze sieht dann so aus. Klicke Sie anschließend wieder auf OK.

Alles sieht gut aus, Sie können mit OK abschließend bestätigen.

Die Aufgabenplanung erstellt jetzt die gewünschte Aufgabe.

Ein Sache ist aber noch wichtig. Standardmäßig wird Ihre Aufgabe nur dann ausgeführt, wenn Sie an Ihrem Computer aktiv angemeldet sind. Das ist aber nicht immer erwünscht. Möchte man die Aufgabe beispielsweise auf einem Windows-Server erstellen, dann soll diese ja auch dann ausgeführt werden, wenn kein Server-Administrator am Server angemeldet ist (Das ist ja der Standardfall). In diesem Fall müssen Sie die Konfiguration Ihrer Aufgabe anpassen:

Wählen Sie eine neue Aufgabe in der Windows-Aufgabenplanung aus und klicken Sie rechts unter Ausgewähltes Element auf Eigenschaften. Es öffnet sich ein Dialogfenster.
Wählen Sie unter Sicherheitsoptionen die Option Unabhängig von der Benutzeranmeldung ausführen aus und bestätigen Sie mit OK.
Sie werden jetzt aufgefordert, sich mit einem passenden Windows-Benutzerkonto zu authentifizieren. In der Regel sollte Ihr eigenes Windows-Benutzerkonto ausreichen.

Das Ergebnis:

Wir haben eine Aufgabe erstellt, die das PowerShell-Cmdlet zum Übertragen der Daten von DAVINCI nach Sdui alle 10 Minuten startet. Ein Upload erfolgt nur dann, wenn es auch Änderungen in DAVINCI seit dem letzten Abgleich gegeben hat. Die Ausgabe wird in eine Textdatei geloggt, so dass Sie stets kontrollieren können, ob der letzte Übertrag erfolgreich war oder nicht.