Import von Dokumenten mittels Import-User

Einleitung

In diesem Anleitungsartikel erfahren Sie alle wichtigen Informationen zu der Erstellung von DvImport Dateien und dem dazugehörigen Upload-Mechanismus über die API-Schnittstelle von docuvita.

DvImport Dateien können:

Einzelne Objekte beschreiben
(Objekt-) Strukturen abbilden
(Objekt-) Strukturen updaten

Vorlage für einzelne Objekte

<?xml version="1.0" encoding="utf-8"?>
<import>
	<data>
        <object type="@@object.type@@" obj.name="@@obj.name@@" RequiredFieldName="@@RequiredFieldValue@@"/>
	</data>
</import>

Beispiel

In diesem Beispiel wird eine neue Kundenakte mit dem Name Mustermann GmbH und der Kundennummer 8755 angelegt.

<?xml version="1.0" encoding="utf-8"?>
<import>
	<data>
	  <object type="Kundenakte" obj.name="Mustermann GmbH" kundennummer="8755">
	</data>
</import>

Vorlage für neue verschachtelten Objekte

<?xml version="1.0" encoding="utf-8"?>
<import>
	<data>
        <object type="@@object.type@@" obj.name="@@obj.name@@" RequiredFieldName="@@RequiredFieldValue@@">
            <object type="@@obj.type@@" obj.name="@@obj.name@@">
                <object type="@@obj.type@@" doc.filename="@@FILENAME@@" ver.comment="@@COMMENT@@"/>
            </object>
        </object>
	</data>
</import>

Beispiel

In diesem Beipiel wird das Objekt Kundenakte mit dem Namen Mustermann GmbH angelegt, das Feld kundennummer (falls im docuvita vorhanden) wird mit 8755 belegt. Danach wird der Ordner Rechnungen angelegt und zum Schluss wird die Datei Rechnung_2019-02_MustermannGmbH.PDF mit dem Namen Rechnung 2018-08 unterhalb des Ordners Rechnungen abgelegt.

Kundennummer="8755" ist in dem Fall ein Pflichtfeld.

<?xml version="1.0" encoding="utf-8"?>
<import>
  <data>
  <object type="Kundenakte" obj.name="Mustermann GmbH" kundennummer="8755">
        <object type="Ordner" obj.name="Rechnungen">
            <object type="Dokument" doc.filename="Rechnung_2019-02_MustermannGmbH.PDF" obj.name="Rechnung 2018-08" ver.comment="Import Xentral-Schnittstelle vom 2019-03-21" />
        </object>
    </object>
</data>

Vorlage für bestehende verschachtelten Objekte

<?xml version="1.0" encoding="utf-8"?>
<import>
	<data>
		<object type="@@obj.type@@" obj.name="@@obj.name@@" loctype="@@obj.parentType@@" locvalue="@@obj.parentKeyValue@@">
			<object type="@@obj.type@@" doc.filename="@@FILENAME@@" ver.comment="@@COMMENT@@"/>
		</object>
	</data>
</import>

Beispiel

In diesem Beispiel wird das Dokument Rechnung_2019-02_MustermannGmbH.PDF mit dem Namen Rechnung 2018-08 unter dem Ordner Rechnungen abgelegt, der unterhalb der Kundenakte mit der Kundennummer(Schlüsselfeld) 8755 liegt.

Falls der Ordner Rechnungen im docuvita nicht vorhanden ist, wird er automatisch angelegt.

<?xml version="1.0" encoding="utf-8"?>
<import>
  <data>
    <object type="Ordner" obj.name="Rechnungen" loctype="Kundenakte" locvalue="8755">
        <object type="Dokument" doc.filename="Rechnung_2019-02_MustermannGmbH.PDF" obj.name="Rechnung 2018-08" ver.comment="Import Xentral-Schnittstelle vom 2019-03-21" />
</object>
</data>
</import>

Attributbeschreibung

Attribut	Beschreibung	Beispiel
type	Objekttyp, der importiert wird	type="Ordner" oder type="Dokument"
obj.name	Name des Objekts im docuvita oder Name, nach dem das neue Objekt im docuvita genannt wird.	obj.name="Belege"
loctype	Typ des Parentobjekts, unter dem das angegebene Objekttype gesucht wird	loctype="Kundenakte"
locvalue	Wert des Schlüsselfelds von dem Parentobjekt	loctype="Kundeakte" locavalue="5"
doc.filename	Originalname des Dokumentes, das importiert werden soll	doc.filename="Rechnung.pdf"
ver.comment	Versionskommentar	ver.comment="Import durch XXX-Schnittstelle vom 2019-03"
RequiredFieldName	Name des Pflichtfelds im docuvita	kundennummer="8755"
RequiredFieldValue	Wert des Pflichtfelds. Soll-Wert oder Ist-Wert, dies hängt davon ab, ob das Objekt bereits besteht oder neu angelegt werden soll.	kundennummer="8755"

API

1.Als erstes muss der Befehl importapi_uploadimportset an den Server geschickt werden.

Beispiel: URL: https://h02.docuvita.online/Alias/services/importapi_uploadimportset/?format=json

JSON Request:

{
"BatchImportGuid": "9832a5f1-c664-4aee-9e12-4734ca0e0087",
"ImportName": "Testimport",
"ImportTagName": "Test",
"StartImportAfterUpload": "true",
"UserName": "Testuser",
"Password": "TopSecret",
"SystemReference": "1"
}

Parameter	Wert
BatchImportGuid	Eine beliebige GUID
ImportName	Name des Imports
ImportTagName	Dies kann verwendet werden um dem ImportSet eine Gruppe zuzuweisen
StartImportAfterUpload	true
UserName	Name des Import-Users in docuvita
Password	Passwort des Import-Users
SystemReference	Mandant, in der Regel 1

JSON Antwort:

Die Antwort auf dem Request sieht wie folgt aus:

{
    "BatchImport": {
        "Batchimportid": 9,
        "Batchimportguid": "9832a5f1c6644aee9e124734ca0e0087",
        "Systemreference": 1,
        "Name": "test",
        "Tagname": "Test",
        "Datecreated": "2019-04-05T15:17:33.0000000+02:00",
        "Owner": 1,
        "Ownername": "Gehaltsabrechnungen",
        "Status": 0
    },
    "UploadGuid": "f194b4e1-ada3-464f-bf4e-df48a6966804"
}

Aus der Antwort wird lediglich das UploadGuid benötigt

2. Der Upload der .zip Datei erfolgt per multipart/form-data POST-Request

Beispielupload per multipart/form-data

Upload mit JavaScript

/**
*Lädt eine Datei zu docuvita
*
*@param {string} inURL - enthält die URL + uploadGuid in folgendem Format: https://localhost/server/services/fileupload?guid=uploadGuid[+'&format=json']
*@param {string} inFile - die hochzuladene Datei
*
*@returns {object} - Die Serverantwort
**/
function uploadFile(inURL, inFile) {

  var boundary = "----------" + getTimeTicks();
  
  var header = toUTF8("--" + boundary + "\r\n"+"Content-Disposition: form-data; name=\"file\"; filename=\"" + inFile.getName() + "\"\r\nContentType: " + inFile.getMimeType() +'\r\n\r\n') 
  var footer = toUTF8("\r\n--" + boundary + "--\r\n")

  var dataStream = Utilities.newBlob(header).getBytes()
                   .concat(inFile.getBlob().getBytes())
                   .concat(Utilities.newBlob(footer).getBytes()
                   
   var options = {
    method : "POST",
    contentType : "multipart/form-data; boundary=" + boundary,
    payload : dataStream,
    muteHttpExceptions: true
  };
  
  return UrlFetchApp.fetch(inURL, options);
}

function getTimeTicks() {
 
  var epochTicks = 621355968000000000;
  var ticksPerMillisecond = 10000;
  return (epochTicks + (new Date().getTime() * ticksPerMillisecond)).toString(16);
}

function toUTF8(s) {
    return decodeURIComponent(escape(s))
};

Support Technet

Wiki & Dokumentation

Import von Dokumenten mittels Import-User

Einleitung

Vorlage für einzelne Objekte

Beispiel

Vorlage für neue verschachtelten Objekte

Beispiel

Vorlage für bestehende verschachtelten Objekte

Beispiel

Attributbeschreibung

API

Beispieldatei