ecoDMS → Paperless-ngx

Werkzeuge und Anleitung für die Migration eines ecoDMS-Archivs nach Paperless-ngx — mit Versionsketten, Berechtigungen, Klassifizierung und Notizen.

Erprobt an einem Bestand von rund 11.000 Dokumenten mit 12.000 Versionen, gewachsen über zwölf Jahre.

---

Was übernommen wird

ecoDMS	Paperless-ngx
Dokument	Dokument
Dateiversionen	Versionskette (versions, ab Paperless 3.0)
Ordnerhierarchie	Tags, je Ebene einer
Dokumentart	Dokumenttyp
Status	Tag Status: …
Bemerkung	Titel
cdate	Erstellungsdatum
Versions-Zeitstempel	added je Version (per Nachbearbeitung)
Dokument-ID	Archiv-Seriennummer + Zusatzfeld
Dynamische Attribute	Zusatzfelder (Custom Fields)
Wiedervorlage (defdate)	Zusatzfeld
Rollenrechte	Eigentümer + Objektberechtigungen
Notizen (econotice)	Notizen

Was nicht übernommen wird

Element	Grund
Klassifizierungshistorie	Paperless kennt keine Metadaten-Historie
Verknüpfungen zwischen Dokumenten	im Export nicht enthalten
Nicht unterstützte Dateitypen	.html, .zip, .indd und andere
E-Mail-Anhänge als eigene Dokumente	Paperless belässt sie in der .eml

Für die letzten drei Punkte erzeugen die Werkzeuge Listen zur Nacharbeit.

---

Aufbau

Die Migration läuft in zwei getrennten Stufen. Die Trennung ist Absicht: Stufe 1 ist offline, beliebig wiederholbar und ihr Ergebnis lässt sich ansehen, bevor irgendetwas geschrieben wird.

ecoDMS-Export ──▶ ecodms_extract.py ──▶ Manifest (JSON) ──▶ paperless_import.py ──▶ Paperless
   (Tranche)          Stufe 1              + Prüfbericht         Stufe 2            (REST-API)
                                           + Ausschlussliste
                                                                        │
                                                                        ▼
                                                              migration.sqlite
                                                                  (Journal)

Das Journal ist der Kern. Es hält je Dokument fest, was importiert wurde und was nicht. Dadurch ist der Import wiederaufsetzbar, Tranchen dürfen sich überschneiden, und die Zuordnung bleibt tranchenübergreifend auswertbar.

---

Dateien

Datei	Zweck
ecodms_extract.py	Stufe 1: Export → Manifest
paperless_import.py	Stufe 2: Manifest → Paperless
ecodms_notizen.py	Notizen aus econotice übertragen
docker-compose.yml	Paperless-Instanz für die Migration
Dockerfile	optional: Image mit E-Rechnungs-Parser
.env.example	Konfigurationsvorlage
rollen.yml.example	Übersetzung der ecoDMS-Rollen

Anleitung

1. Paperless-Instanz vorbereiten
2. Export aus ecoDMS
3. Extraktion und Prüfung
4. Import
5. Nacharbeit

Dazu als Nachschlagewerk: Das ecoDMS-Exportformat — die Eigenheiten des Formats, die während der Migration aufgedeckt wurden. Wer nur eine Sache liest, sollte es diese sein.

---

Voraussetzungen

• Paperless-ngx 3.0 oder neuer (Versionierung)
• ecoDMS mit Datenexport-Funktion (im Lizenzumfang, keine API nötig)
• Python 3.11+ mit requests und PyYAML
• Speicherplatz: etwa das Doppelte des ecoDMS-Bestands

---

Schnelleinstieg

# 1. Instanz starten (siehe docs/01)
docker compose up -d

# 2. Je Tranche extrahieren
python3 ecodms_extract.py /pfad/export1/archive -t export1 \
        -o export1.json --skipped-csv export1-nacharbeit.csv

# 3. Prüfbericht lesen. Ernsthaft.

# 4. Stammdaten anlegen, dann probeweise zwei Dokumente
export PT=dein_api_token
python3 paperless_import.py export1.json --setup
python3 paperless_import.py export1.json --limit 2 --stop-on-error

# 5. Volle Tranche, danach prüfen
python3 paperless_import.py export1.json
python3 paperless_import.py --verify

# 6. Nach ALLEN Tranchen
python3 paperless_import.py --emit-timestamps > fix_added.py
docker compose exec -T webserver python manage.py shell < fix_added.py
python3 ecodms_notizen.py --dry-run --csv notizen.csv

---

Lizenz

MIT, siehe LICENSE. Vor einer Veröffentlichung den Rechteinhaber eintragen.

Haftung

Die Werkzeuge lesen aus ecoDMS ausschließlich, schreiben aber in Paperless. Vor jedem Lauf ein Backup oder einen Dateisystem-Snapshot anlegen.

Sie wurden an einem gewachsenen Bestand erprobt, nicht formal getestet. Die MIT-Lizenz schließt jede Gewährleistung aus — das ist hier nicht nur Formsache: Eine Migration verändert einen Dokumentenbestand, und die Eigenheiten des Exportformats sind nicht dokumentiert, sondern durch Beobachtung erschlossen. Ein anderer Bestand kann Fälle enthalten, die hier nie aufgetreten sind.

Deshalb der Ablauf in docs/03-extraktion.md: erst extrahieren, Prüfbericht lesen, dann zwei Dokumente probeweise importieren, dann die volle Tranche.

Jede Anwendung dieses Skript- und Softwarepakets erfolgt auf eigene Gefahr und ohne jegliche Gewähr. Jede Haftung wird ausgeschlossen.