ff-operation-zias-connect

Connector für das ZIAS (Zusatzinformations- und Alarmierungssystem) des Landkreises Aichach-Friedberg.

Das Tool überwacht bestimmte Verzeichnisse auf neue PDF- und JSON-Dateien und lädt diese automatisch in die FF Operation API hoch.

Funktionsweise

1. Der Daemon überwacht json_dir auf neue JSON-Dateien und optional pdf_dir auf neue PDF-Dateien
2. Dateiereignisse werden debounced (2 s), um unvollständige Uploads zu vermeiden, solange eine Datei noch geschrieben wird
3. Es werden nur .pdf-Dateien in pdf_dir und .json-Dateien in json_dir verarbeitet – andere Dateitypen werden ignoriert
4. Dateien werden anhand ihres SHA-256-Hashs erkannt – wird eine Datei mit gleichem Dateinamen mit identischem Inhalt erneut geschrieben, wird kein erneuter Upload ausgelöst. Wird eine Datei gelöscht und später mit gleichem oder anderem Inhalt neu erstellt, wird sie erneut hochgeladen
5. Leere Dateien werden still übersprungen und erst beim nächsten Schreib-Event erneut verarbeitet
6. JSON-Dateien werden anhand eines konfigurierbaren Feld-Mappings auf den API-Body gemappt und als application/json gesendet
7. PDF-Dateien werden als multipart/form-data gesendet; der Dateiname wird automatisch verarbeitet und als incidentId mitgesendet
8. Die Originaldatei bleibt unverändert am Speicherort und der Upload wird protokolliert
9. Bei einer eindeutigen Server-Antwort (4xx/5xx) wird kein Wiederholungsversuch unternommen – die Datei wird direkt in quarantine_dir kopiert
10. Bei Netzwerkfehlern wird der Upload bis zu 5-mal mit exponentiellem Backoff wiederholt; schlagen alle Versuche fehl, wird die Datei optional in quarantine_dir kopiert

Voraussetzungen

• Raspberry Pi OS oder ein beliebiges Linux-System mit systemd (mit 64Bit)
• wget oder curl für den ersten Download und automatische Updates
• sudo / Root-Zugriff für Installation, Updates, Konfiguration und Dienstverwaltung
• Netzwerkzugang zur FF Operation API

Ersteinrichtung auf dem Raspberry Pi

Einmalig manuell installieren – danach kann das Tool sich selbst aktualisieren.

1) Binary herunterladen

$ export ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
$ export PACKAGE_VERSION="latest"
$ export DOWNLOAD_URL="https://code.jk-effects.cloud/api/packages/ff-admin/generic/ff-operation-zias-connect/${PACKAGE_VERSION}/zias-connect-${ARCH}"

$ wget -O zias-connect "${DOWNLOAD_URL}" || curl -L -o zias-connect "${DOWNLOAD_URL}"
$ chmod +x zias-connect

Hinweis: PACKAGE_VERSION="latest" lädt die neueste Version herunter. Statt latest kann auch eine konkrete Version angegeben werden, z. B. v1.2.3.

2) Binary installieren

sudo cp zias-connect /usr/local/bin/zias-connect
zias-connect version

3) Konfiguration erstellen und prüfen

sudo zias-connect config
sudo zias-connect validate

4) Systemd-Service installieren und starten

sudo zias-connect install
zias-connect status
zias-connect logs

Befehle

Befehl	Beschreibung
zias-connect config	Konfiguration erstellen oder aktualisieren
zias-connect validate	Konfiguration und Verzeichniszugriff prüfen
zias-connect daemon	File-Watcher im Vordergrund starten (wird intern vom Service verwendet)
zias-connect install	Systemd-Service installieren und starten
zias-connect start	Service starten
zias-connect stop	Service stoppen
zias-connect restart	Service neu starten
zias-connect status	Service-Status anzeigen
zias-connect logs	Service-Logs verfolgen (letzte 50 Zeilen)
zias-connect update	Neueste Binary herunterladen und Service neu starten
zias-connect update --version v1.2.3	Bestimmte Version herunterladen
zias-connect uninstall	Service aus systemd entfernen
zias-connect version	Installierte Version und Architektur anzeigen

Konfiguration

Die Konfiguration wird unter /etc/ff-operation-zias-connect.json gespeichert und interaktiv über sudo zias-connect config erstellt.

Feld	Pflicht	Beschreibung
api_url	✓	Basis-URL der FF Operation API (z. B. https://operation.example.de) – Pfad, Query und Fragment werden automatisch entfernt
api_key	✓	Bearer-Token zur Authentifizierung beim Upload
json_dir	✓	Verzeichnis, das auf .json-Dateien überwacht wird
pdf_dir	–	Optional. Verzeichnis, das auf .pdf-Dateien überwacht wird. Leer lassen, um PDF-Verarbeitung zu deaktivieren
quarantine_dir	–	Optional. Hier werden Dateien abgelegt, deren Upload dauerhaft fehlschlug oder vom Server abgelehnt wurde

Konfiguration anpassen

Bei erneutem Aufruf von zias-connect config werden die aktuellen Werte in [eckigen Klammern] angezeigt:

• Enter drücken: aktuellen Wert behalten
• Neuen Wert eingeben: aktuellen Wert ersetzen
• - eingeben: optionales Feld leeren (deaktivieren)

sudo zias-connect config
sudo zias-connect validate
sudo zias-connect restart

Incident-ID Parsing

Die incidentId wird aus den ZIAS-Feldern casenumber und casenumbershort abgeleitet und mit einem Datum im Format YYYY-MM-DD ergänzt.

Eingabeformate

Feld	Format	Beispiel
casenumber (Long-ID)	<Typ> <X>.<Y> <JJMMTT> <Sequenz>	T 7.1 260101 0
casenumbershort (Short-ID)	<Typ><Sequenz>	T0

Ablauf

1. Short-ID bestimmen – Ist casenumbershort vorhanden, wird diese direkt verwendet. Andernfalls wird die Short-ID aus casenumber extrahiert (Typ + Sequenz: T 7.1 260101 0 → T0).
2. Datum anhängen – Das Datum wird in folgender Priorität ermittelt:
   1. casetime: ISO 8601 Timestamp wird auf YYYY-MM-DD reduziert
   2. Kein Datum verfügbar: nur die Short-ID ohne Datum
3. Ergebnis – Short-ID + Leerzeichen + Datum

Die Fallback-Logik stellt sicher, dass die incidentId beim ersten Mapping (ohne casetime) und nach einem Update (mit casetime) identisch bleibt, solange sich das Datum nicht ändert.

Update

# Neueste Version herunterladen
sudo zias-connect update

# Bestimmte Version herunterladen
sudo zias-connect update --version v1.2.3

Deinstallation

sudo zias-connect uninstall
# Binary optional manuell entfernen:
sudo rm /usr/local/bin/zias-connect

Fehlersuche

Symptom	Mögliche Ursache	Lösung
401 Unauthorized	Falscher API-Key	sudo zias-connect config erneut ausführen
404 Not Found	Falsche api_url oder Endpunkt nicht vorhanden	URL prüfen mit sudo zias-connect validate
4xx / 5xx vom Server	Server hat Anfrage abgelehnt	Logs prüfen: zias-connect logs; Datei liegt in quarantine_dir
Upload wird nie ausgelöst	Verzeichnis nicht beschreibbar oder falscher Pfad	sudo zias-connect validate ausführen
Dateien bleiben in der Quarantäne	Upload wiederholt fehlgeschlagen oder vom Server abgelehnt	Logs prüfen: zias-connect logs, API-Erreichbarkeit testen
Service startet nicht	Konfiguration fehlt oder ist ungültig	sudo zias-connect config && sudo zias-connect validate

Logs jederzeit live verfolgen:

zias-connect logs

Kurzbefehle (Aliases)

Folgende Alternativen stehen ebenfalls zur Verfügung:

• ozc
• ffozc
• ziasc
• ff-operation-zias-connect

ozc status
ziasc logs