Jobs zum Kopieren von Dateien vom SFTP auf das LMS

In diesem Artikel wird der Kopierprozess von Dateien vom SFTP-Server auf das LMS erläutert. Es wird beschrieben, wie Probleme im Zusammenhang mit „verspätet eingegangenen oder nicht importierten Dateien“ behoben werden können, und es wird erklärt, wie der Prozess für einen neuen Kunden während des Onboardings eingerichtet wird.

Es werden drei Zielgruppen angesprochen: Kunden (was man liefern und was man zuerst überprüfen muss), Support-Mitarbeiter (wie man ein Störungs-Ticket diagnostiziert und löst) sowie das Projekt- bzw. Onboarding-Team (wie man die Konfiguration des Prozesses für einen neuen Kunden vornimmt).

1. So funktioniert der Dateiverarbeitungsprozess

Es gibt drei Schritte, die von mindestens zwei Cron-Jobs ausgeführt werden. Eine Datei muss zunächst bereitgestellt werden, bevor sie kopiert werden kann, und sie muss kopiert werden, bevor sie ausgeführt werden kann.

Die vorgesehene zeitliche Abfolge ist:

Die Lücken („Puffer“) zwischen den einzelnen Schritten sind bewusst vorgesehen: Sie gleichen eine verspätete Lieferung oder eine langsame Übertragung aus, sodass die nächste Stufe niemals auf eine fehlende oder unvollständig geschriebene Datei zugreift.

2. Zeitzonen und Zeitumstellung (das Kernkonzept)

Das Problem tritt auf, wenn verschiedene Schritte unterschiedlichen Zeitreferenzen folgen. Wenn der Kopier-Job in UTC (das ganze Jahr über unverändert) ausgeführt wird, die Lieferung und/oder Ausführung jedoch nach Ortszeit erfolgt (die sich bei jeder Zeitumstellung um eine Stunde verschiebt), ändert sich der zeitliche Abstand zwischen den Stufen zweimal im Jahr um eine Stunde – obwohl niemand die Zeitplanung geändert hat.

Funktionsbeispiel:

In Ortszeit betrachtet sieht die vorgesehene Zeitplanung wie folgt aus: Lieferung um 02:00 Uhr, Kopieren um 04:00 Uhr, Ausführung um 06:00 Uhr (2 Stunden + 2 Stunden Puffer). Wenn der Kopier-Job an die UTC-Zeit gebunden ist, während die anderen der Ortszeit folgen, verschiebt sich die tatsächliche Ortszeit des Kopier-Jobs bei einer Zeitumstellung um eine Stunde, während die anderen unverändert bleiben, sodass der gleiche Zeitplan wie folgt aussehen kann:

Die beide Zeilen entsprechen den beiden Zeitumstellungen auf Sommer- bzw. Winterzeit im Laufe des Jahres (Uhren vor- bzw. zurückstellen). Die genaue Richtung hängt von der Basiszeitzone des Servers und davon ab, wann der Zeitplan ursprünglich festgelegt wurde. Überprüfen Sie dies daher anhand Ihrer eigenen Protokolle, anstatt anzunehmen, welche Zeile angewendet wird.

Warum dies zu „verspäteten“ Dateien führt: In der zweiten Zeile ist das Kopieren erst eine Stunde vor der Ausführung fertig, sodass jede zusätzliche Verzögerung bei der Lieferung oder beim Kopieren selbst dazu führen kann, dass die Datei den Ausführungszeitpunkt verpasst – während in der anderen Jahreshälfte dieselbe Verzögerung durch den zweistündigen Puffer problemlos aufgefangen wurde.

3. Für den Kunden

3.1 Verantwortlichkeiten des Kunden

• Übermitteln Sie die Datei bis zum vereinbarten Termin (Zeitpunkt X) an den SFTP-Server, und zwar in das vereinbarte Verzeichnis mit dem vereinbarten Dateinamenmuster und dem vereinbarten Format.

• Stellen Sie sicher, dass der Upload auf den SFTP-Server abgeschlossen ist, bevor der Kopier-Job ausgeführt wird – siehe den Tipp zum sicheren Upload weiter unten.

• Verwenden Sie die vereinbarte Zeitreferenz (wir empfehlen UTC End-to-End). Wenn Sie Ihren Upload in Ortszeit planen, beachten Sie bitte, dass sich der Puffer für den Kopiervorgang bei jeder Zeitumstellung um eine Stunde verschiebt. Laden Sie Ihre Daten daher so früh wie möglich hoch, ohne dabei die Sicherheit zu gefährden.

3.2 Der Zeitplan (ausfüllen und dem Kunden zur Verfügung stellen)

Unser Schritt Kopieren wird nach <UTC> ausgeführt und ändert sich aufgrund der Zeitumstellung nicht.

3.3 Dateibeispiele

CSV-Beispiel

File name : <import_YYYYMMDD.csv>

Delivered : by <02:00 UTC>

Format    : <UTF-8, comma-delimited, header row required>

Sample    :

XML-Beispiel

<!-- File name: <mapping_YYYYMMDD.xml> -->
<!-- Delivered: by <02:00 UTC> -->
<!-- Format: <UTF-8, well-formed, valid against schema name/version> -->
<attributeMapping isReference="false">
       <mapping sourceField="ID" clixField="EXT_ID_CSV"/>
       <mapping sourceField="Login" clixField="LOGIN"/>
       <mapping sourceField="Firstname" clixField="FIRSTNAME"/>
       <mapping sourceField="Lastname" clixField="LASTNAME"/>
</attributeMapping> 

3.4 Wenn Ihr Import verspätet oder fehlerhaft erscheint

1. Vergewissern Sie sich, dass sich Ihre Datei unter dem richtigen Namen, im richtigen Verzeichnis und im richtigen Format auf dem SFTP-Server befindet.

2. Vergewissern Sie sich, dass der Upload abgeschlossen ist (keine 0 Byte, keine laufende Übertragung).

3. Bitte bestätigen Sie, dass die Lieferung vor Ablauf der Frist und in der vereinbarten Zeitzone erfolgt ist.

4. Wenn alle vorangehend genannten Angaben korrekt sind, erstellen Sie bitte ein Support-Ticket mit folgenden Angaben: dem Dateinamen, dem genauen Zeitpunkt des Uploads und der Zeitzone sowie einem Screenshot oder einer Liste, aus der die Datei auf dem SFTP-Server ersichtlich ist.

4. Verantwortlichkeiten der Scheer IMC Support-Mitarbeiter (Bearbeitung von Incidents)

4.1 Erste Reaktion – Sammeln Sie folgende Fakten zu einem fehlgeschlagenen Durchlauf

• Dateiname und Zeitstempel auf dem SFTP-Server (als der Upload tatsächlich abgeschlossen war)

• Zeitstempel für den Start und das Ende des Kopier-Jobs (Protokoll des Kopier-Jobs)

• Zeitstempel der Durchführung des Ausführungs-Jobs (Protokoll des Ausführungs-Jobs)

• Ob die Datei vorhanden, fehlend oder unvollständig war, als der Ausführungs-Job lief

Schon diese vier Fakten allein lassen in der Regel auf den fehlerhaften Schritt schließen.

4.2 Diagnoseablauf

 War die Datei vorhanden und vollständig, als der Ausführungs-Job (Z) lief?
 
  FEHLEND       -> Kopier-Job wurde nicht rechtzeitig abgeschlossen      -> 4.3 Kopier-Schritt
                   (überprüfen Sie zuerst, ob die Lieferung erfolgt ist  -> 4.3 Lieferungs-Schritt)
  UNVOLLSTÄNDIG -> Kopiervorgang wurde gestartet, bevor der Upload
                   abgeschlossen war oder der Kopiervorgang
                   wurde unterbrochen                                    -> 4.3 Kopier-Schritt
                                                                                (unvollständige Datei)
  VORHANDEN aber
  FALSCH
  VERARBEITET   -> Problem mit Format / Kodierung / Schema               -> 4.3 Ausführungs-Schritt
  VORHANDEN und
  NUR VERSPÄTET -> a buffer was eaten: check DST (Sec 2)
                   and copy duration                                     -> 4.3 Kopier-Schritt

4.3 Schrittweise Überprüfungen

Lieferung (Schritt 1 – Kundenseite)

• Vergleichen Sie den Zeitstempel der Datei auf dem SFTP-Server mit dem vereinbarten Lieferzeitpunkt X (geben Sie dabei eindeutig an, ob es sich bei X um UTC oder die Ortszeit handelt – siehe Abschnitt 2).

• Vergewissern Sie sich, dass sich die Datei im erwarteten Verzeichnis befindet und das erwartete Namensmuster aufweist. Groß- und Kleinschreibung, ein falscher Unterordner, ein zusätzliches Präfix oder Suffix oder eine falsche Dateiendung führen dazu, dass der Kopier-Job die Datei nicht erkennt (“see nothing”).

• Achten Sie auf Uploads mit einer Größe von null Byte oder unvollständige Uploads (eine fehlgeschlagene Kundenübertragung).

• Wenn Lieferungen regelmäßig verspätet sind, handelt es sich dabei um ein Problem im Zusammenhang mit der SLA bzw. der Kundenkommunikation und nicht um einen technischen Fehler.

Kopieren (Schritt 2 – Job, der vom Scheer IMC Plattform-Team gesteuert wird)

Ist der Job überhaupt gelaufen?

• Stellen Sie sicher, dass der Cron-Eintrag im Crontab vom <Service-Account> vorhanden ist, nicht auskommentiert ist und korrekt geschrieben ist (<crontab -l -u service-account>).

• Überprüfen Sie, ob der Cron-Daemon bzw. -Service läuft (<SYSTEMCTL status cron/crond> oder das entsprechende Befehlsäquivalent auf Ihrer Plattform).

• Überprüfen Sie, ob im Cron-/Systemprotokoll vermerkt ist, dass der Job zum Zeitpunkt Y aufgerufen wurde (<journalctl / /var/log/syslog> – Der Pfad variiert je nach Plattform).

• Vergewissern Sie sich, dass die Felder in der Zeitplanung tatsächlich das bedeuten, was Sie davon erwarten (Minute, Stunde, Tag des Monats, Monat, Wochentag). Eine häufige Falle ist ein Job, der nur an bestimmten Wochentagen ausgeführt wird, sodass Lieferungen am Wochenende unberücksichtigt bleiben.

Ist der Job gelaufen, aber fehlgeschlagen, oder hat er gar nichts bewirkt?

• Überprüfen Sie den Exit-Status und eventuelle Fehler im Protokoll des Jobs (<path/to/copy-job.log> – erfassen Sie dort stdout und stderr).

• SFTP-Verbindung / Authentifizierung: Kann der Service Account derzeit eine Verbindung zum SFTP-Host herstellen und sich dort anmelden? Führen Sie einen manuellen Test mit demselben Schlüsseln bzw. denselben Anmeldedaten durch, die der Job verwendet (<sftp -i key user@sftp-host>). Achten Sie auf abgelaufene Kennwörter, rotierte SSH-Schlüssel sowie geänderte Host Keys bzw. „known_hosts“, die automatische Anmeldungen unbemerkt unterbrechen können.

• Datei zum Zeitpunkt des Kopierens nicht gefunden – der Job wurde ausgeführt, aber die Datei war noch nicht vorhanden → Problem mit dem Zeitablauf bei der Lieferung (Schritt 1).

• Zielprobleme seitens des LMS – Zielverzeichnis fehlt, falsche Berechtigungen, Festplatte voll / Kontingent überschritten oder eine schreibgeschützte Einbindung (eine volle Festplatte führt zu unvollständigen Dateien oder Dateien mit einer Größe von null Byte).

• Falscher Quell- bzw. Zielpfad nach einer Umgebungsänderung (z. B. ein während der Migration umbenannter Ordner).

Lief der Job pünktlich, hat aber zu lange gedauert?

• Vergleichen Sie die Zeitstempel für den Beginn und das Ende des Kopiervorgangs. Falls das Kopieren selbst nun deutlich länger dauert, prüfen Sie die Zunahme der Dateigröße, die Anzahl der Dateien pro Durchlauf, die Auslastung des SFTP-Servers sowie den Netzwerkdurchsatz und die Latenz. Dies ist ein starker Hinweis auf das Muster „mit der Zeit schlimmer werdend“.

• Prüfen Sie, ob sich Durchläufe überschneiden (ein langsamer Durchlauf läuft noch, wenn der nächste beginnt). Ziehen Sie eine Sperrdatei oder einen Single-Instance-Guard in Betracht.

Fragmentierte / unvollständige Datei (Wettlauf mit dem Upload)

• Wenn der Kopiervorgang beginnt, während der Kunde noch am Hochladen ist, wird eine unvollständige Datei kopiert, und der Ausführungs-Job verarbeitet anschließend eine beschädigte Datei.

• Maßnahmen zur Risikominderung umsetzen (gemäß den beim Onboarding getroffenen Vereinbarungen): Der Kunde lädt die Daten zunächst unter einem temporären Namen hoch und benennt sie anschließend um; der Kunde erstellt eine Markierungsdatei bzw. eine .done-Datei, auf deren Vorliegen der Kopier-Job wartet; der Kopier-Job überprüft, ob die Dateigröße bei zwei Lesevorgängen im Abstand von wenigen Sekunden stabil bleibt; die Datei wird auf der LMS-Seite unter einem temporären Namen kopiert und erst nach Abschluss der Übertragung an den endgültigen Speicherort umbenannt.

Ausführung (Schritt 3 – innerhalb des LMS)

• Überprüfen Sie die Zeitplanung des Ausführungs-Jobs (Z) und seine Zeitzonenreferenz und vergleichen Sie den Puffer erneut mit Y entsprechend Abschnitt 2.

• Wenn die Datei vorhanden und vollständig war, aber falsch verarbeitet wurde, sollten Sie eher den Inhalt bzw. das Format als den zeitlichen Ablauf als Ursache vermuten:

  • Vergleichen Sie CSV und XML – der Dateityp entspricht den Anforderungen des Ausführungs-Jobs, und beide Formate werden tatsächlich unterstützt, sofern beide verwendet werden.

  • Überprüfen Sie die Kodierung (UTF-8 vs. UTF-8-mit-BOM vs. eine regionale Codepage), die Zeilenenden, das Trennzeichen, die Kopfzeile und die Spaltenreihenfolge.

  • Schema/Struktur für XML validieren (Ist es richtig aufgebaut? Entspricht es dem erwarteten Schema/der DTD?).

• Stellen Sie sicher, dass der Ausführungs-Job auf dasselbe Verzeichnis verweist, in das der Kopier-Job schreibt.

4.4 Zeitumstellungs- / Zeitzonenprüfung

1. Ermitteln Sie, auf welche Zeitzone die einzelnen Rechner eingestellt sind (SFTP-Host, Kopier-Job-Host, LMS-Host)?

2. Ermitteln Sie, in welcher Zeitzone die einzelnen Jobs konfiguriert sind. Ein Crontab kann die Systemzeitzone mit einem TZ / CRON_TZ Eintrag überschreiben – Überprüfen Sie den Kopier-Job und den Ausführungs-Job.

3. Stellen Sie sicher, dass alle drei Schritte dieselbe Referenz verwenden. Die sauberste Lösung ist eine UTC End-to-End-Auslegung, sodass sich die Puffer nie ändern.

4. Überprüfen Sie, ob die Lieferzeiten des Kunden in der Zeitplanung bzw. der SLA, die Sie ihm zur Verfügung stellen, in UTC oder in Ortszeit angegeben sind. Eine Diskrepanz in diesem Punkt ist eine häufige Ursache für Probleme.

4.5 Checkliste zur Überprüfung

• Datei auf dem SFTP-Server zum Zeitpunkt X vorhanden (mit serverseitigem Zeitstempel erfasst)

• Datei vollständig auf SFTP (keine Null-Byte-Datei / der Upload ist nicht noch im Gange)

• Kopier-Job zum Zeitpunkt Y ausgelöst (Cron- / Systemprotokoll)

• Kopier-Job wurde erfolgreich beendet (Jobprotokoll, Endstatus)

• SFTP-Login weiterhin gültig (Schlüssel / Passwort / Host Key)

• Ziel ist beschreibbar und verfügt über freien Speicherplatz

• Kopiervorgang wurde rechtzeitig vor Z abgeschlossen (Start-/Endzeitstempel)

• Datei war im LMS vorhanden und vollständig bei Ausführung zum Zeitpunkt Z

• Alle drei Schritte beziehen sich auf dieselbe Zeitzonenreferenz (UTC End-to-End empfohlen)

• Dateiformat und Kodierung für den Ausführungs-Job korrekt (CSV- und XML-Fälle)

4.6 Eskalation

• Wenn die Ursache eine verspätete oder fehlerhafte Lieferung ist
  → Kunde / Ansprechpartner

• Wenn die Ursache bei den SFTP-Zugangsdaten oder der Verbindung liegt
  → Scheer IMC Infrastruktur- / Hosting-Team

• Wenn die Ursache im LMS-Ausführungs-Job oder in der Importlogik liegt
  → Scheer IMC Incident Management- / Hosting-Team

• Wenn die Ursache eine Abweichung zwischen Zeitzone und Zeitumstellung im Zeitplan ist
  → Scheer IMC Incident Management-Team

5. Projektphase – Onboarding eines neuen Kunden

5.1 Setup-Checkliste

1. Stellen Sie dem Kunden das SFTP-Konto bzw. die Anmeldedaten (Schlüssel oder Passwort) zur Verfügung und vergewissern Sie sich, dass er eine Verbindung herstellen kann.

2. Vereinbaren Sie die Verzeichnisstruktur und die Namenskonvention für Dateien.

3. Vereinbaren Sie das/die Dateiformat(e) – CSV, XML oder beides – sowie die Kodierung und das Schema.

4. Einigen Sie sich auf eine Methode für den sichere Upload (zunächst unter einem temporären Namen speichern und anschließend umbenennen oder eine Markierungsdatei bzw. eine „.done“-Datei verwenden).

5. Vereinbaren Sie den Liefertermin (X) und legen Sie die Zeitzone fest. Wir empfehlen die durchgängige Verwendung von UTC, damit die Zeitumstellungen keinen Einfluss auf die Puffer haben.

6. Konfigurieren Sie den Kopier-Job (Y) mit einem ausreichenden Puffer nach Zeitpunkt X.

7. Überprüfen Sie den Zeitplan des Ausführungs-Jobs (Z) und stellen Sie sicher, dass dessen Puffer nach Y auch die ungünstigste einstündige Umstellung auf die Sommerzeit bewältigt.

8. Richten Sie die Protokollierung (Zeitstempel für „geliefert“, „Kopieren gestartet“, „Kopieren beendet“ und „ausgeführt“) sowie Warnmeldungen bei einem sich verkleinernden Puffer ein, nicht nur bei einem vollständigen Ausfall.

5.2 Zeitplan und Zeitzone vereinbaren (Sizing)

Wählen Sie X, Y und Z so, dass selbst der reduzierte Puffer (nach einer einstündigen Umstellung auf Sommerzeit gemäß Abschnitt 2) größer ist als die längste realistische Übertragungsverzögerung zuzüglich der Kopierdauer. Die einfachste Möglichkeit, bei beiden Zeitumstellungen auf der sicheren Seite zu bleiben, besteht darin, beide Puffer gleich groß und großzügig zu dimensionieren.

5.3 Überprüfen der ersten Dateien

1. Führen Sie einen vollständigen Testzyklus mit einer repräsentativen CSV-Datei durch: Lieferung → Kopieren → Ausführen, wobei bei jedem Schritt die Zeitstempel und die Datei überprüft werden.

2. Wiederholen Sie den Vorgang mit einer repräsentativen XML-Datei (richtig aufgebaut und schemakonform).

3. Stellen Sie sicher, dass die „Safe-Upload“-Methode tatsächlich ein teilweises Kopieren verhindert (testen Sie beispielsweise einen unterbrochenen Upload).

4. Erfassen Sie die tatsächlich festgestellten Puffer und vergleichen Sie diese mit dem vereinbarten Zeitplan.

5.4 Checkliste für das Go-live

• Der Kunde hat bestätigt, dass er Zugriff auf den SFTP-Server hat.

• Namenskonvention, Verzeichnis, Format und Kodierung sind dokumentiert und vereinbart.

• Die „Safe-Upload“-Methode wurde implementiert und getestet.

• Zeitplan (X, Y, Z) und Zeitzonenangaben, wie in Abschnitt 3.2 dokumentiert und dem Kunden mitgeteilt.

• Es wurde nachgewiesen, dass die Puffer eine einstündige Zeitumstellung überstehen.

• Protokollierung und Warnmeldungen sind eingerichtet.

• Die CSV- und XML-Testdateien wurden durchgängig erfolgreich verarbeitet.

• Die in Abschnitt 6.2 erfassten Werte pro Kunde wurden hinterlegt.

6. Referenz

6.1 Glossar

6.2 Werte pro Kunde / pro Umgebung (ausfüllen)