Skip to main content

xSuite Interface Windows Prism 5.x – Online Help

Input System "WebServiceInput"

The "WebServiceInput" input system is used to transfer new data from a third-party application to xSuite Interface. Using the "WebServiceInputClient" output system, the data can also be transferred from another xSuite Interface instance.

Only the properties listed in General Properties apply to this output system.

The input web service has the following endpoints:

Endpoint

Description

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

Basically, a batch with all its constituent documents is always sent to the web service in one call. If the batch consists of only a single document, an artificial batch object will always still be generated as a bracket around this document.

The binary data of the file attachments can be included directly in the document objects with Base64 encoding. In order to limit the amount of data to be transferred in one call in the case of many or large file attachments, the attachments can be uploaded individually in advance (see endpoints below).

The complete object for a batch with one document and one field and one file attachment each looks like the following example:

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

For information on naming the fields and the syntax of the field contents, see Index Data Reader "WebService".

Header data fields and table fields are sent together to a flat list, but differ by the value in .ItemNo. For header data fields, always use the value 0. If omitted, this will be the default value used. For table fields, specify the specific number of the table row to which the fields belong.

The .Key property of a file attachment only applies if its binary data is not sent directly as in the example. As return values, the web service returns the database ID and a UUID that identify the batch created.

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]

These endpoints are the three alternatives for uploading the binary data of file attachments to the server before transferring the batch of documents.

The server stores this data for a maximum of 30 minutes in the main memory and temporarily in the storage. After this time has elapsed or after a restart of the program, the attachments can no longer be referenced.

The reference is the freely selectable but unique "Key" which can be entered when uploading a file. If the "Key" is missing, a UUID will be implicitly generated as a key and returned by the web service. Assign these key values to the .Key properties of the Files[] objects so that, when the batch is ultimately transferred, the file attachments are referenced. The other two file properties are no longer relevant in this case. As a final option, if the name was not already supplied in the course of file upload, you can set the .Name property.

In the UploadFileBinary variant, the "Key" is to be sent as a URL parameter, and the filename is also to be sent as a URL parameter or alternatively as a "filename" property of the "Content-Disposition" header. The pure binary data of the file forms the body content of the request.

In the variant UploadFileForm, the transfer is performed as form data (content type "multipart/form-data") with the "Key" as a URL parameter, the data content as "file" key, and the file name as "filename" key of the form. The "multipart" transfer of multiple files at the same time is not supported on the server side.

In the UploadFileJson variant, the body content is expected to be a JSON object that corresponds exactly to an object from the .Files[] list in the above example. The object must thus contain the .Name, .Key, and .Data properties with the Base64-encoded binary data.

The file attachments are extracted from the transmitted data directly in the input system. The index values should preferably be read via the "WebService" index data reader in the "Process" step.

In this section: