153 lines
5.2 KiB
Markdown
153 lines
5.2 KiB
Markdown
# 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](docs/01-paperless-vorbereiten.md)
|
|
2. [Export aus ecoDMS](docs/02-export-aus-ecodms.md)
|
|
3. [Extraktion und Prüfung](docs/03-extraktion.md)
|
|
4. [Import](docs/04-import.md)
|
|
5. [Nacharbeit](docs/05-nacharbeit.md)
|
|
|
|
Dazu als Nachschlagewerk: [Das ecoDMS-Exportformat](docs/referenz-ecodms-exportformat.md)
|
|
— 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
|
|
|
|
```bash
|
|
# 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](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](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.
|