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 entprellt (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. Leere Dateien werden still übersprungen und erst beim nächsten Schreib-Event erneut versucht
5. JSON-Dateien werden anhand eines konfigurierbaren Feld-Mappings auf den API-Body gemappt und als application/json gesendet
6. PDF-Dateien werden als multipart/form-data gesendet; der Dateiname wird automatisch verarbeitet und als incidentId mitgesendet
7. Die Originaldatei bleibt unverändert am Speicherort und der Upload wird protokolliert
8. Bei einer eindeutigen Server-Antwort (4xx/5xx) wird kein Wiederholungsversuch unternommen – die Datei wird direkt in quarantine_dir kopiert
9. 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 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

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