Diese Anleitung beschreibt den Upload von Dokumenten in docuvita über die Import-API mittels ZIP-Archiv und dvImport-Steuerdatei.
Referenzdokumente:
Vor dem ersten Import müssen folgende Punkte geklärt bzw. eingerichtet sein:
Empfehlung: Für den Start und die ersten Tests einen einfachen Testordner anlegen und die dvImport-Dateien erst dann erweitern, wenn man mit der Funktion vertraut ist.
Für einen Import über die Import-API wird zunächst eine GUID benötigt; diese kann selbst erzeugt werden. Mit dieser GUID (BatchImportGuid) wird der Import über den Endpunkt
/server/services/importapi_uploadimportset
der API in docuvita registriert.
Parameter:
| Parameter | Wert |
|---|---|
ImportName |
frei wählbar |
ImportTagName |
nicht benötigt |
BatchImportGuid |
die im Vorfeld erzeugte GUID |
StartImportAfterUpload |
true |
UserName |
Import-Benutzername |
Password |
zugehöriges Passwort |
SystemReference |
1 |
Sind alle Parameter korrekt gesetzt, liefert die Antwort eine GUID zurück. Diese wird für den anschließenden Upload benötigt.
Der Upload erfolgt über den Upload-Endpunkt /fileupload?guid=<uploadguid aus vorherigem Scritt>.
multipart/form-data und beinhaltet die ZIP-Datei.Das ZIP-Archiv enthält:
Jede dvImport-Datei ist XML mit exakt diesem Rumpf:
<?xml version="1.0" encoding="utf-8"?>
<import>
<data>
<!-- hier die zu importierenden Objekte in <object/>-Notation -->
</data>
</import>
Die Datei muss XML-konform sein. Werden Werte dynamisch eingesetzt, müssen sie escaped werden:
| Zeichen | Escape-Sequenz |
|---|---|
& |
& |
< |
< |
> |
> |
" |
" |
' |
' |
<object>-ElementJedes zu importierende Objekt (Akte, Ordner, Dokument) ist ein <object>-Tag. Es gelten folgende Regeln:
type ist immer Pflicht – der Name des Objekttyps, wie er in der Objekttypkonfiguration angezeigt wird (nicht der interne Name).obj.name.doc.filename – den Pfad zur zu importierenden Datei (relativ innerhalb des ZIP-Archivs). Das Objekt mit doc.filename ist das eigentliche Dokument; alles darüber ist Struktur.type, doc.filename, docDeleteFile, versioncomment.Beispiel eines Dokument-Objekts (Objekttyp- und Feldnamen sind installationsabhängig):
<object type="VK_Auftrag"
doc.filename="beispieldokument.txt" <!-- Dokumentdatei -->
obj.name="Beispieldokument" <!-- Systemfelder (obj.*) -->
obj.datecreated="2026-07-14"
obj.vouchernumber="Beleg_134417"
obj.vouchertype="Prüfprotokoll"
obj.transactionkey="V260706"
firma="XYZ" <!-- benutzerdefinierte Felder -->
kundennummer="10011"
kundenname="Musterkunde GmbH" />
obj.* = Systemfelder, die docuvita für alle bzw. für Dokument-Objekttypen mitbringt:
| Feld | Bedeutung |
|---|---|
obj.name |
Objektname (Pflicht) |
obj.datecreated |
Erstelldatum |
obj.vouchernumber |
Belegnummer (z. B. interne Nummer des führenden Systems) |
obj.vouchertype |
Belegart |
obj.transactionkey |
Vorgangsnummer |
Ohne Präfix = selbst definierte Felder aus dem Customizing (im Beispiel: kundennummer, kundenname, firma). Es darf jedes am Objekttyp definierte Feld per Feldname="Wert" befüllt werden; Feldnamen ohne Leerzeichen.
Ineinander geschachtelte <object>-Elemente legen die Hierarchie im Archiv an, z. B.:
Kundenakte "Musterkunde GmbH (10011)" (kundennummer="10011")
└── Ordner "Belege"
└── Ordner "Verkaufsbelege"
└── VK_Auftrag ← Dokument mit doc.filename
Als dvImport-Datei (beispielhaft):
<?xml version="1.0" encoding="utf-8"?>
<import>
<data>
<object type="Kundenakte"
obj.name="Musterkunde GmbH (10011)"
kundennummer="10011"
kundenname="Musterkunde GmbH">
<object type="Ordner" obj.name="Belege">
<object type="Ordner" obj.name="Verkaufsbelege">
<object type="VK_Auftrag"
doc.filename="beispieldokument.txt"
obj.name="Beispieldokument"
obj.datecreated="2026-07-14"
obj.vouchernumber="Beleg_134417"
obj.vouchertype="Prüfprotokoll"
obj.transactionkey="V260706"
firma="XYZ"
kundennummer="10011"
kundenname="Musterkunde GmbH" />
</object>
</object>
</object>
</data>
</import>
Für jede Ebene entscheidet die Schlüsselfeld-Konfiguration des Objekttyps (Administration → Objekttypen), ob ein vorhandenes Objekt wiederverwendet oder ein neues angelegt wird:
kundennummer); die Akte für Kunde 10011 wird gefunden, statt doppelt angelegt zu werden.obj.name; „Belege" wird im Kontext dieser Akte gefunden oder dort neu angelegt.Beim Dokument gilt: Existiert bereits eines mit dem Schlüsselwert, wird eine neue Version angelegt (bei globalem Schlüssel zusätzlich in die neue Struktur verschoben), sonst ein neues Dokument.
Wichtig für die Fehlerbehandlung: Liefert ein Schlüsselwert mehrere Treffer, wird bei einem Dokument ein Fehler protokolliert und der Import bricht ab; bei Ordner/Akte gibt es nur eine Warnung und das erste gefundene Objekt wird verwendet.
Welche Felder als Schlüssel dienen, steht nicht in der dvImport-Datei – das ist Installations-Customizing. Die dvImport-Datei liefert nur die Werte; das Customizing entscheidet, was davon als Schlüssel wirkt.