Zum Inhalt

Import aus Untis

Untis ist eine Stundenplan-Software. ENBREA kann Daten aus dem Untis-XML-Exportformat sowie aus dem Untis-DIF-Format (GPU012.TXT, GPU013.TXT und GPU014.TXT) einlesen. Diese Dateien müssen zunächst aus Untis heraus exportiert werden. Dies kann in Untis per Kommandozeile automatisiert werden.

Wie funktioniert der Import?

Der Workflow besteht grob aus drei Schritten:

  1. Zunächst müssen aus Untis heraus die folgenden Exportdateien generiert werden:

    • untis.xml: XML-Datei mit Stammdaten und Stundenplaninformationen
    • GPU012.TXT: CSV-Datei mit Absenzgründen
    • GPU013.TXT: CSV-Datei mit Absenzen
    • GPU014.TXT: CSV-Datei mit Vertretungsinformationen
  2. Das ECF Tool for Untis generiert aus diesen vier Ausgangsdateien ECF-Dateien.

  3. Das ECF Tool for ENBREA importiert die ECF-Dateien nach ENBREA.

Alle drei Schritte können per PowerShell komplett oder teilweise automatisiert werden:

  • Mit PSUntis haben wir ein PowerShell-Modul entwickelt, mit dem die benötigten Exportdateien aus Untis mit einem einzigen Befehl erzeugt werden können. Alternativ kannst man die Dateien natürlich auch direkt aus Untis heraus generieren.

  • Mit dem PowerShell-Modul PSEnbrea kann man die Schritte 2 und 3 mit einem einzigen Befehl ausführen.

Installieren

  1. Falls noch nicht geschehen, bitte auf dem Computer die .NET Core Laufzeitumgebung, PowerShell 7, das PowerShell-Modul PSEnbrea installieren und einen Zeitraum in ENBREA anlegen. Was genau man hierfür tun muss, steht im Kapitel Voraussetzungen.

  2. Im Windows-Explorer ein neues Verzeichnis c:\enbrea anlegen (das Verzeichnis kann natürlich auch anders heißen).

  3. PowerShell 7 über das Windows-Menü starten: Start > Windows Powershell > Windows Powershell

  4. Mit folgendem Befehl in das soeben angelegte Verzeichnis wechseln:

    cd c:\enbrea
    
  5. Nun folgenden PowerShell-Befehl eintippen:

    Initialize-EnbreaImport enbrea.json
    

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

  6. Bitte folgenden PowerShell-Befehl eintippen:

    Install-EcfTools enbrea,untis
    

    Es werden das ECF Tool for ENBREA und das ECF Tool for Untis installiert.

Konfigurieren

Die gesamte Konfiguration des Imports befindet sich in der Textdatei enbrea.json. Diese Datei in einem Texteditor öffnen und die gewünschten Eigenschaften überschreiben.

Die folgenden Eigenschaften müssen angepasst werden. Sie konfigurieren den individuellen Zugang zu ENBREA:

Eigenschaft Bedeutung
Enbrea.EcfImport.IdentityServiceUrl URL zum ENBREA Identity Service
Enbrea.EcfImport.IdentityUserName ENBREA Benutzername
Enbrea.EcfImport.IdentityPassword ENBREA Kennwort
Enbrea.EcfImport.SchoolServiceUrl URL zum ENBREA School Service
Enbrea.EcfImport.SchoolTermId ID des ENBREA-Zeitraums, in den importiert werden soll. Die ID des Zeitraums ist in der Adressleiste des Browsers sichtbar, während man an der ENBREA-Instanz angemeldet ist.

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

Bitte beachten

Der Backslash (= umgedrehter Schrägstrich) in Dateipfaden muss in einer JSON-Datei stets gedoppelt werden, also \\ statt \.

Das Ergebnis könnte wie folgt aussehen:

{
    "Untis" : {
        "EcfExport": {
            "TargetFolderName": "untis\\ecf-export",
            "SourceFolderName": "untis",
            "SourceFilesAsUtf8": false,
            "SourceFilesQuote": "\"",
            "SourceFilesSeperator": ","
        }   
    },
    "Enbrea" : {
        "EcfImport": 
        {
            "IdentityServiceUrl" : "https://enbrea.beispiel.de/identity",
            "IdentityUserName" : "importbenutzer",
            "IdentityPassword" : "qwertz",
            "SchoolServiceUrl" : "https://enbrea.beispiel.de/school",
            "SchoolTermId" : "9067eff1-6817-4e59-855c-9ace4e51f139",
            "Files" : [
                { "Name" : "CourseCategories", "KeyHeaders":"Code" },
                { "Name" : "CourseFlags", "KeyHeaders":"Code" },
                { "Name" : "CourseTypes", "KeyHeaders":"Code" },
                { "Name" : "EducationalAreas", "KeyHeaders":"Code" },
                { "Name" : "EventTypes", "KeyHeaders":"Code" },
                { "Name" : "ExamTypes", "KeyHeaders":"Code" },
                { "Name" : "FormsOfTeaching", "KeyHeaders":"Code" },
                { "Name" : "LessonProfiles", "KeyHeaders":"Code" },
                { "Name" : "LevelOfQualifications", "KeyHeaders":"Code" },
                { "Name" : "ResourceCategories", "KeyHeaders":"Code" },
                { "Name" : "ResourceFlags", "KeyHeaders":"Code" },
                { "Name" : "RoomAbsenceReasons", "KeyHeaders":"Code" },
                { "Name" : "RoomTypes", "KeyHeaders":"Code" },
                { "Name" : "SchoolClassAbsenceReasons", "KeyHeaders":"Id" },
                { "Name" : "SchoolClassFlags", "KeyHeaders":"Code" },
                { "Name" : "SchoolClassLevels", "KeyHeaders":"Code" },
                { "Name" : "SchoolClassProfils", "KeyHeaders":"Code" },
                { "Name" : "SchoolForms", "KeyHeaders":"Code" },
                { "Name" : "SchoolOrganisations", "KeyHeaders":"Code" },
                { "Name" : "SchoolTypes", "KeyHeaders":"Code" },
                { "Name" : "SubjectFocuses", "KeyHeaders":"Code" },
                { "Name" : "SubjectTypes", "KeyHeaders":"Code" },
                { "Name" : "TeacherAbsenceReasons", "KeyHeaders":"Id" },
                { "Name" : "TeacherAbsenceReasonDifferentiations", "KeyHeaders":"Code" },
                { "Name" : "TeacherTypes", "KeyHeaders":"Code" },
                { "Name" : "TimeAccountEntryReasons", "KeyHeaders":"Code" },
                { "Name" : "TimeAccountEntryReportings", "KeyHeaders":"Code" },
                { "Name" : "TimeAccountEntryTypes", "KeyHeaders":"Code" },
                { "Name" : "VacationTypes", "KeyHeaders":"Code" },
                { "Name" : "VocationalField", "KeyHeaders":"Code" },
                { "Name" : "EducationalPrograms", "KeyHeaders":"Code" },
                { "Name" : "TimeFrames", "KeyHeaders":"Code" },
                { "Name" : "Departments", "KeyHeaders":"Code" },
                { "Name" : "Rooms", "KeyHeaders":"Code" },
                { "Name" : "RoomAbsences", "KeyHeaders":"Id" },
                { "Name" : "Subjects", "KeyHeaders":"Code" },
                { "Name" : "EducationalContents", "KeyHeaders":"Code" },
                { "Name" : "EducationalMaterials", "KeyHeaders":"Code" },
                { "Name" : "SubjectLearningField", "KeyHeaders":"Code" },
                { "Name" : "Teachers", "KeyHeaders":"Code" },
                { "Name" : "TeacherAbsences", "KeyHeaders":"Id" },
                { "Name" : "Students", "KeyHeaders":"LastName;FirstName;Birthdate" },
                { "Name" : "StudentAbsences", "KeyHeaders":"Id" },
                { "Name" : "StudentSubjects", "KeyHeaders":"Id" }
                { "Name" : "SchoolClasses", "KeyHeaders":"Code" },
                { "Name" : "SchoolClassAbsences", "KeyHeaders":"Id" },
                { "Name" : "Courses", "KeyHeaders":"Id", "DeleteStrategy" : "DeleteRemaining" },
                { "Name" : "Announcements", "KeyHeaders":"Id", "DeleteStrategy" : "DeleteRemaining" },
                { "Name" : "ScheduledLessons", "KeyHeaders":"Id", "DeleteStrategy" : "DeleteRemaining" },
                { "Name" : "SubstituteLessons", "KeyHeaders":"Id", "DeleteStrategy" : "DeleteRemaining" },
                { "Name" : "LessonGaps", "KeyHeaders":"Id", "DeleteStrategy" : "DeleteRemaining" },
                { "Name" : "Vacations", "KeyHeaders":"Id", "DeleteStrategy" : "DeleteRemaining" }
            ]
        }
    }
}

Testen

Manuell aus Untis exportieren

  1. Bitte Untis starten und die gewünschte Untis-Datei oder Untis-Datenbank öffnen.

  2. Zunächst Datei > Import/Export > Untis wählen und dort die Schnittstelle XML-Import/Export. Ein Dialogfenster öffnet sich.

  3. Die Registerkarte Export wählen und unter Exportdatei den vollständigen Pfad zur Exportdatei untis.xml angeben. Die Datei untis.xml muss in dem Ordner abgelegt werden, der in der JSON-Konfigurationsdatei unter Untis.EcfExport.SourceFolderName definiert ist. In unserer Beispielkonfiguration würde der Pfad c:\enbrea\untis\untis.xml lauten.

  4. Auf Exportieren klicken und das Dialogfenster schließen.

  5. Nnun Datei > Import/Export > Export TXT Datei (CSV, DIF) wählen und dort nacheinander die Schnittstellen Absenzgründe, Absenzen und Vertretungen. Es öffnet sich jeweils ein Dialogfenster.

  6. In jedem Dialogfenster auf OK klicken und in den Ordner wechseln, der in der JSON-Konfigurationsdatei unter Untis.EcfExport.SourceFolderName definiert ist. In unserer Beispielkonfiguration würde der Ordner c:\enbrea\untis lauten. Der Dateiname ist schon richtig voreingestellt, er muss nicht geändert weden.

  7. Jeweils auf Speichern klicken.

Das Resultat sind die frisch exportieren Untis-Dateien untis.xml, GPU012.TXT, GPU013.TXT und GPU014.TXT .

Per PowerShell aus Untis exportieren

Wer es etwas komfortabler haben möchte, kann unser PowerShell-Modul PSUntis nutzen.

  1. PowerShell 7 über das Windows-Menü starten: Start > Windows Powershell > Windows Powershell

  2. Einmalig PSUntis wie folgt installieren:

    Install-Module PsUntis
    
  3. Die benötigten Dateien exportieren.

    Bei einer Einzelplatzversion von Untis lautet der Befehl (Beispiel):

    Start-UntisExport -File beispiel.gpn -OutputFolder c:\enbrea\untis\ -OutputType XML,GPU012,GPU013,GPU014
    

    Beim Einsatz von Untis MultiUser lautet der Befehl (Beispiel):

    Start-UntisExport -SchoolNo 12345 -SchoolYear 2020-2021 -User Administrator -Password (ConvertTo-SecureString 'qwertz' -AsPlainText -Force) -Date 2009-07-11 -OutputFolder c:\enbrea\untis\ -OutputType XML,GPU012,GPU013,GPU014
    

    Eine ausführliche Beschreibung der Parameter des Cmdlets Start-UntisExport findet man im GitHub-Wiki von PSUntis.

Das Resultat sind die frisch exportieren Untis-Dateien untis.xml, GPU012.TXT, GPU013.TXT und GPU014.TXT .

Bitte beachten

Beim Export von GPU-Dateien per PowerShell werden die Konfigurationsdaten (z.B. Trennzeichen) aus dem letzten manuellen Export übernommen.

Daten nach ENBREA übertragen

  1. PowerShell 7 über das Windows-Menü starten: Start > Windows Powershell > Windows Powershell

  2. Mit folgendem Befehl in unser ENBREA-Verzeichnis wechseln:

    cd c:\enbrea
    
  3. Folgenden PowerShell-Befehl eintippen:

    Start-EnbreaImport untis enbrea.json
    

Das soeben erstellten Untis-Dateien untis.xml, GPU012.TXT, GPU013.TXT und GPU014.TXT werden ins ECF-Format übersetzt und anschließend nach ENBREA übertragen.

Dateien vom Übertrag ausnehmen

Sollen einzelne Dateien aus UNTIS nicht mit nach ENBREA übernommen werden, z.B. die GPU013.txt (diese enthält Abwesenheitsgründe und Fehlzeiten der Lehrkräfte) die json Datei wie folgt einrichten:

    },
    "Untis" : {
        "EcfExport": {
            "Files": [
                { "Name": "Courses" },
                { "Name": "Departments" },
                { "Name": "LessonGaps" },
                { "Name": "Rooms" },
                { "Name": "ScheduledLessons" },
                { "Name": "SchoolClasses" },
                { "Name": "Students" },
                { "Name": "StudentSchoolClassAttendances" },
                { "Name": "Subjects" },
                { "Name": "SubstituteLessons" },
                { "Name": "Teachers" },
                { "Name": "Timeframes" },
                { "Name": "Vaccations" }
            ],
            "TargetFolderName": "untis\\ecf-export",
            "SourceFolderName": "untis"
        }   
    },
Die Dateien TeacherAbsenceReasons.csv und TeacherAbsences.csv werden nun nicht erzeugt.

Automation

Die Synchronisation zwischen Untis und ENBREA kann natürlich automatisiert werden. Tipps zur Automation per BATCH-Datei oder Windows-Aufgabenplanung findet man im Kapitel Automation.