Skip to main content

xSuite Interface Windows Prism 5.x – Online-Hilfe

Eingabesystem "WebServiceInput"

Das Eingabesystem "WebServiceInput" dient der Übergabe neuer Daten aus einer Fremdanwendung an xSuite Interface. Unter Verwendung des Ausgabesystems "WebServiceInputClient" kann die Übergabe der Daten auch aus einer weiteren xSuite-Interface-Instanz erfolgen.

Für dieses Eingabesystem gelten ausschließlich die Eigenschaften, die unter Webservice-Schnittstellen aufgeführt sind.

Der Input-Webservice verfügt über die folgenden Endpunkte:

Endpunkt

Beschreibung

POST /api/v1/Input/{Tenant}/{Scenario}/Batches [InputUploadBatch]

Grundsätzlich wird immer ein kompletter Stapel mit allen enthaltenen Dokumenten in einem Aufruf an den Webservice übergeben. Wenn der Stapel nur aus einem einzelnen Dokument besteht, ist dennoch ein künstliches Stapelobjekt als Klammer um dieses Dokument zu generieren.

Die Binärdaten der Dateianlagen können mit Base64-Kodierung direkt in den Dokumentobjekten mitgegeben werden. Um bei vielen oder großen Dateianlagen die in einem Aufruf zu übertragende Datenmenge zu begrenzen, können die Anlagen vorab einzeln hochgeladen werden (siehe nachfolgende Endpunkte).

Das vollständige Objekt für einen Stapel mit einem Dokument und jeweils einem Feld und einer Dateianlage sieht beispielhaft wie folgt aus:

{
    "Name": "Batch1",
   "Documents": [
      {
         "Name": "Document1",
         "Fields": [
            {
               "Name": "Field1",
               "Value": "Hello World",
               "ItemNo": 0
            }
         ],
         "Files": [
            {
               "Name": "Attachment1.txt",
               "Key": null,
               "Data": "SGFsbG8gV2VsdCENCg=="
            }
         ]
      }
   ]
}

Informationen zur Benennung der Felder und der Syntax der Feldinhalte finden Sie unter Indexdatenleser "WebService".

Kopfdatenfelder und Tabellenfelder werden gemeinsam in einer flachen Liste übergeben, unterscheiden sich aber durch den Wert in .ItemNo. Für Kopfdatenfelder muss dieser Wert 0 sein. Dies ist auch der Standardwert bei Weglassung. Für Tabellenfelder muss die Nummer der Tabellenzeile angegeben werden, zu der die Felder gehören.

Die Eigenschaft .Key einer Dateianlage ist nur dann relevant, wenn deren Binärdaten nicht wie im Beispiel direkt mit übergeben werden. Als Rückgabewerte liefert der Webservice die Datenbank-ID und eine UUID zurück, die den erstellten Stapel identifizieren.

POST /api/v1/Input/{Tenant}/{Scenario}/Files/Binary [InputUploadFileBinary]

POST /api/v1/Input/{Tenant}/{Scenario}/Files/Form [InputUploadFileForm]

POST /api/v1/Input/{Tenant}/{Scenario}/Files/Json [InputUploadFileJson]

Diese Endpunkte sind 3 alternative Möglichkeiten, um die Binärdaten von Dateianlagen auf den Server hochzuladen, bevor der Stapel mit den Dokumenten übertragen wird.

Der Server speichert diese Daten für maximal 30 Minuten im Hauptspeicher und temporär im Storage. Nach Ablauf dieser Zeit oder nach einem Neustart des Programms können die Anlagen nicht mehr referenziert werden.

Als Referenz dient der frei wählbare, aber eindeutige "Key", der beim Hochladen einer Datei mitgegeben werden kann. Wenn der "Key" fehlt, wird implizit eine UUID als Schlüssel generiert und vom Webservice zurückgeliefert. Beim abschließenden Übertragen des Stapels sind die .Key-Eigenschaften der Files[]-Objekte mit diesen Schlüsselwerten zu versehen. Die anderen beiden Dateieigenschaften sind in diesem Fall nicht mehr relevant. Nur die Eigenschaft .Name kann optional noch gesetzt werden, wenn der Name nicht schon im Zuge des Datei-Uploads mitgeliefert wurde.

In der Variante UploadFileBinary ist der "Key" als URL-Parameter und der Dateiname ebenfalls als URL-Parameter oder alternativ als "filename"-Eigenschaft des "Content-Disposition"-Headers zu übergeben. Die reinen Binärdaten der Datei bilden den Body-Inhalt der Anfrage.

In der Variante UploadFileForm erfolgt die Übertragung als Formulardaten (Inhaltstyp "multipart/form-data") mit dem "Key" als URL-Parameter, dem Dateninhalt als "file"-Schlüssel und dem Dateinamen als "filename"-Schlüssel des Formulars. Die "Multipart"-Übergabe mehrerer Dateien gleichzeitig wird serverseitig nicht unterstützt.

In der Variante UploadFileJson wird als Body-Inhalt ein JSON-Objekt erwartet, das genau einem Objekt aus der .Files[]-Auflistung in obigem Beispiel entspricht. Das Objekt muss somit die Eigenschaften .Name, .Key und .Data mit den Base64-kodierten Binärdaten enthalten.

Die Extraktion der Dateianlagen aus den übermittelten Daten erfolgt direkt im Eingabesystem. Die Indexwerte sollten bevorzugt über den Indexdatenleser "WebService" im "Process"-Schritt eingelesen werden.

In diesem Abschnitt: