Datenaustausch#

Der Datenaustausch umfasst den Import und Export von Aufträgen sowie von Stammdaten (Auftraggeber, Partner, Postleitzahlen). Empfohlener Weg ist der Kommandozeilen-Client livectl (siehe CLI-Einrichtung).

Für programmatischen Zugang gibt es eine REST-API unter /api (Authentifizierung über ein per livectl login erzeugtes Token). Der Datenimport läuft dort über die generische Import-Schnittstelle mit dem jeweiligen DTO (fsg1/fsg2/fsg3). Der einfachste und empfohlene Weg bleibt jedoch der CLI.

Aufträge#

Aufträge tauschen Sie über den Befehl assignments (Aliase: assignment, ass, t) und das passende DTO aus.

Neuaufträge importieren (FSG1)#

livectl assignments import auftraege.csv --tenant-id <mandant> --dto fsg1

import = empfohlener Regelweg (Upsert): neue Aufträge werden angelegt, bestehende aktualisiert; wiederholtes Einspielen ist unschädlich und bereits eingetragene Ergebnisse bleiben erhalten. Die Auflösung läuft über das Aktenzeichen des Einspeisenden (AktenzeichenEinspeisender) bzw. die original*-Spalten — das Aktenzeichen muss über Re-Imports stabil bleiben.
create = Sonderfall garantiert leere Erstbefüllung: legt nur neue Aufträge an und bricht ab, sobald ein Auftrag schon existiert.
replace = Gesamtbestand atomar ersetzen; verwirft bereits eingetragene Ergebnisse und ist für laufende Bestände nicht geeignet.

Korrekturen einspielen: Bestehende Aufträge aktualisieren Sie einfach durch erneuten import der korrigierten Datei (auch einzelner Zeilen) — kein Löschen und Neuanlegen nötig. Der Status und erfasste Ergebnisse bleiben dabei unverändert.

→ Format: Neuaufträge (FSG1)

Statusänderungen / Außendienstergebnis importieren (FSG2)#

livectl assignments import status.csv --tenant-id <mandant> --dto fsg2

→ Format: Statusänderungen (FSG2)

Aufträge exportieren (FSG3)#

Für den Export gibt es bewusst keinen eigenen export-Unterbefehl — der Export ist der Lese-Befehl mit dem Format FSG3:

livectl assignments --dto fsg3 -f csv > auftraege.csv

Alternativ mit Zieldatei:

livectl assignments list auftraege.csv --dto fsg3 -f csv

→ Format: Aufträge (FSG3)

Aufträge importieren / Bestand migrieren (FSG3)#

Seit Version 1.5.1035 lässt sich das FSG3-Format auch importieren — Auftrags- und Ergebnisdaten in einem Schritt. Das ist der empfohlene Weg für die Migration eines Bestands aus einem Altsystem, das den vollständigen Auftragsstand als FSG3 liefert:

livectl assignments import auftraege.csv --tenant-id <mandant> --dto fsg3

Der Import ist idempotent (Upsert): wiederholtes Einspielen aktualisiert bestehende Aufträge statt abzubrechen; bereits erfasste Ergebnisse bleiben erhalten.
Neu angelegte Aufträge landen im Status zu bestätigen; die Spalte Auftragsstatus verhält sich auf bestehenden Aufträgen wie beim FSG2-Import.
Die Betriebsdaten-Spalten (lupdate, Einstelldatum, Bestätigungsdatum, Bearbeitungsende, Abschlussdatum, Rückgabedatum, Rechnungsdatum) sind export-only und werden beim Import stillschweigend ignoriert — eine unveränderte FSG3-Exportdatei ist damit direkt wieder importierbar.
Historische Status-, Datums- und Partner-Stände übernehmen Sie über die original*-Spalten (nur für Administratoren des Mandanten); die passende Vorlage liefert der Export mit --original-fields. Details: Migration von Bestandsaufträgen

Import-Verhalten: tolerant vs. strict#

Der Import ist standardmäßig tolerant: Gültige Zeilen werden importiert, fehlerhafte Zeilen werden einzeln mit Zeilennummer und Grund gemeldet und sind in der PWA als „Ungültig" sichtbar und korrigierbar.

livectl assignments import auftraege.csv --tenant-id <mandant> --dto fsg1 --strict

--strict bricht beim ersten Fehler komplett ab; es wird dann nichts importiert. Das frühere --ignore ist ein veraltetes No-op und kann weggelassen werden.

Serverseitig abgewiesene Aufträge (z. B. PLZ außerhalb des Servicegebiets)#

Neben den clientseitig gemeldeten Formatfehlern gibt es serverseitige Aktivierungsprüfungen — der häufigste Fall ist eine Schuldner-PLZ außerhalb des bedienten Servicegebiets. Solche Zeilen meldet der Import als abgewiesen (z. B. „Debtor ZIP is outside the configured FSG service area"). Der Auftrag wird dabei serverseitig geparkt: Er existiert, erscheint aber weder in der PWA noch in assignments list/exists, bis er repariert ist.

Reparieren: Korrigieren Sie die Zeile (bei gleichem AktenzeichenEinspeisender!) und spielen Sie sie erneut per assignments import ein. Der geparkte Auftrag wird dadurch vollständig aktiviert — Partner-Zuordnung über die PLZ und Status zu bestätigen werden gesetzt.
Prüfen: Ob zu einem Aktenzeichen ein geparkter Auftrag existiert, zeigt der Trockenlauf livectl assignments rm --original-ref <aktenzeichen> (ohne --yes wird nichts gelöscht).
Verwerfen: Einen geparkten Auftrag, der nicht repariert werden soll, entfernt livectl assignments rm --original-ref <aktenzeichen> --purge --yes physisch. Das physische Löschen erfordert das Recht assignment:purge.

Prüfen Sie nach jedem Import die Zusammenfassung auf abgewiesene Zeilen (rejected), damit geparkte Aufträge nicht unbemerkt liegen bleiben.

Stammdaten#

Stammdaten verwalten Sie über die jeweiligen Aggregate nach dem gleichen Verb-Schema (create, import, export, list …). Der Import liest strukturierte Dateien (YAML oder JSON, - für JSON über stdin); CSV/XLSX sind bei Stammdaten Export- und Ansichtsformate:

livectl clients import clients.yaml              # Auftraggeber
livectl partners import partner.yaml             # Partner / Ausführende
livectl postal-areas import plz.csv --dto fsg.postal-area   # PLZ / Servicegebiete (CSV/XLSX ok)

Mehr dazu unter Auftraggeber, Partner und Konten.

Container & Formate#

CSV und XLSX sind gleichwertige Container. CSV ist Semikolon-getrennt und UTF-8-kodiert; Beträge mit Komma ohne Währungszeichen (z. B. 1206,55), Datum in deutscher Form TT.MM.JJJJ (ISO-Datum wird ebenfalls akzeptiert). Die maßgeblichen Feld- und Spaltendefinitionen finden Sie unter FSG-Formate.