Inbound-API

Inbound-App

 Basisinformationen

In diesem Thema findest du allgemeine Informationen zur Inbound-API.

 Über die Inbound-API

In dieser Dokumentation erfährst du, wie du die Programmierschnittstelle der Inbound-App für eigene Entwicklungen nutzen kannst. Die Inbound-App stellt Funktionalitäten rund um die Themen Import, Aufbereitung und Weiterverarbeitung von digitalen Seiten bereit.

 Funktionsumfang der Inbound-App

Die Inbound-App umfasst die Verwaltung digitaler Sammlungen von Seiten, den sogenannten Stapeln. Folgende Funktionen sind enthalten:

  • Import von Seiten aus externen Systemen (z.B. von der Scan-App)
  • Export der Stapelseiten für Drittsysteme
  • Bearbeitung des Stapels und seiner Seiten
  • Einfaches Berechtigungskonzept

 Verwenden der API-Funktionen

Im Folgenden lernst du die unterschiedlichen Möglichkeiten kennen, die Schnittstellen der Inbound-App für deine Anforderungen zu verwenden.

 Allgemeines

In diesem Kapitel findest du allgemeine Informationen zur Verwendung der API.

 Format der Antwort bei Fehlern

In diesem Kapitel erfährst du, in welchem Format Fehler ausgegeben werden. Abhängig vom Verarbeitungsergebnis des Vorgangs wird die HTTP-Anforderung mit verschiedenen HTTP-Statuscodes beantwortet. Optional werden beschreibende Informationen zurückgeliefert.

Beispielantwort für eine fehlgeschlagene Anforderung (Request):


HTTP/1.1 400 BadRequest

{
    "reason": "AuthorizedGroups and AuthorizedUsers are empty. At least one must be set. Parameter name: authorization",
    "details": "Exception type: System.ArgumentException",
    "severity": 3,
    "errorCode": 0
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
reasonEin optionaler kurzer Text zur Beschreibung der Fehlerursache. Dieser Text wird als Titel der Fehlermeldung verwendet.
hintEin optionaler Hinweistext für den Anwender mit Tipps zur Fehlerbehebung.
detailsOptionale Detailinformationen zum Fehler.
severityOptionaler Schweregrad des Fehlers. Folgende Werte sind möglich: Success = 0, Information = 1, Warning = 2, Error = 3
errorCodeEin optionaler Fehlercode zur internen Identifizierung.

 Verwenden der API ohne Benutzerkontext

Mit der App-Session der Identityprovider-App kannst du die API ohne Benutzerkontext aufrufen. Alle öffentlichen Schnittstellen der Inbound-App unterstützen diese App-Session. Nähere Informationen zur Generierung einer App-Session findest du in der API-Dokumentation der Identityprovider-App. Sorge dafür, dass nach dem Erstellen eines Stapels auch Benutzer Zugriff auf den Stapel erhalten. Beachte dazu den Abschnitt Vergeben von Stapelberechtigungen für Benutzer oder Gruppen.

 Erstellen eines Stapels

Du kannst einen neuen Stapel automatisiert in der Inbound-App erstellen, ohne dass ein Anwender eine Aktion durchführen muss. Um einen neuen Stapel zu erstellen, führe folgende Schritte durch:

  • Ermitteln der Linkrelation für die Erstellung eines neuen Stapels
  • Aufrufen der URL zur Erstellung eines neuen Stapels

 Ermitteln der Linkrelation zum Erstellen eines Stapels

Verwende eine HTTP-GET-Anforderung, um die Root-URL der Inbound-App aufzurufen:

Request


GET /inbound
Accept: application/hal+json

Das JSON-Objekt der Inbound-App enthält die Linkrelation importProcessTarget, mit der du einen Stapel erstellen kannst.

 Response

{
    "_links": {
        "importProcessTarget": {
            "href": "inbound/importprocess",
            "templated": false
        }
    }
}

Das Ermitteln der Linkrelation brauchst du auch für folgende Funktionen:

 Aufrufen der URL zur Erstellung eines Stapels

Nachdem du die Linkrelation ermittelt hast, kannst du die URL zum Erstellen eines Stapels aufrufen. Führe eine HTTP POST-Anforderung mit den benötigten Eigenschaften als Body an die URL aus.

 Request

POST /inbound/importprocess
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "name": "my batch 1",
    "batchProfile": "0017836e-a74a-4258-8cc4-7b0ab3ea6bb2",
    "propertiesUrl": "/app/url",
    "properties": {
        "sa.propertyKey1": "value",
        "propertyKey2": "another value"
    }
}

Das Feld name ist optional und muss nicht übergeben werden. Wenn du das Feld name nicht übergibst, wird der Name des Stapels automatisch vergeben. Über den Parameter batchProfile kannst du dem Stapel ein Importprofil zuweisen. Wenn du den Parameter nicht angibst, wird dem Stapel das Standardprofil zugewiesen. Zusätzlich kannst du mit dem Feld properties weitere Eigenschaften übergeben. Dieses Feld ist optional und muss nicht übergeben werden. Du solltest ein eindeutiges Präfix für die Schlüssel der Eigenschaften verwenden, um Namenskonflikte mit anderen Apps zu vermeiden. Bei der Abfrage der Eigenschaften und den Nachbearbeitungsoptionen werden diese Schlüssel wieder zurückgegeben. Nähere Informationen dazu findest du im Abschnitt Abfragen der Eigenschaften und Nachbearbeitungsoptionen. Die weiteren Eigenschaften des Stapels können bei der Erstellung nicht mitgegeben werden. Fülle die weiteren Eigenschaften beim Erstellen eines Stapels nicht aus. Werden Eigenschaften mit der ID einer Eigenschaft des aktuell ausgewählten Katalogs übergeben, so werden diese auf die Dokumente übertragen. Alternativ kann mit dem Parameter propertiesUrl eine URL angegeben werden. Diese wird von der InboundApp aufgerufen und darüber bereitgestellte Eigenschaften, sowie ggf. die Kategorie, übernommen. Wenn der Aufruf erfolgreich ist, erhältst du eine Antwort mit der URL zum erstellten Stapel im Header Location und den Eigenschaften des Stapels im Body.

 Response

HTTP/1.1 201 Created
Location: /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb

{
    "id": "0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb"
}

Informationen zu den Parametern des JSON-Objektes findest du im Abschnitt Abrufen eines Stapels. Wenn das Erstellen des Stapels fehlschlägt, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen findest du im Abschnitt Format der Antwort bei Fehlern.

 Request der InboundApp zum Abrufen der Eigenschaften

GET /app/url
Origin: https://baseuri
Accept: application/json

{
    "properties": {
        "sa.propertyKey1": "value",
        "propertyKey2": "another value"
    }
}

Alternativ kannst du einen Stapel auch mit einer HTTP GET-Anforderung erstellen.

 Request

/inbound/importprocess/new?BatchProfileId=ProfileID&Properties={"Property1ID":"Property1Value","Property2ID":"Property2Value",...}

Über den Parameter BatchProfileId kannst du dem Stapel ein Importprofil zuweisen. Wenn du den Parameter nicht angibst, wird in der Oberfläche ein Dialog angezeigt, über den das Importprofil ausgewählt werden kann.

Optional kannst du kannst du über den Parameter Properties JSON-formatiert Dokument-Eigenschaften an den Stapel übergeben. Alternativ können diese mit dem Parameter PropertiesUrl als URL übergeben werden. Sofern die übergebenen IDs der Eigenschaften im aktuell ausgewählten Katalog verfügbar sind, werden sie auf die Dokumente übernommen.

 Ermitteln der BatchProfileId

Verwende eine HTTP-GET-Anforderung, um die Root-URL der Inbound-App aufzurufen:

 Request

GET /inbound
Accept: application/hal+json

Das JSON-Objekt der Inbound-App enthält die Linkrelation batchProfiles, mit der du alle Importprofile aufrufen kannst.

 Response

{
    "_links": {
        "batchProfiles": {
            "href": "/inbound/batchprofile",
            "templated": false
        }
    }
}

 Aufrufen der URL zum Abfragen der Importprofile

Mit der Linkrelation für die Importprofile kannst du die Liste aller Importprofile wie folgt aufrufen:

 Request

Get /inbound/batchprofile
Accept: application/hal+json

Wenn der Aufruf erfolgreich ist, werden im Body die Importprofile als JSON zurückgegeben:

 Response

HTTP/1.1 200 Ok

{
    "_links": {},
    "profiles": [
        {
            "batchProfileId": "0017836e-a74a-4258-8cc4-7b0ab3ea6bb2",
            "name": "My favorite profile"
        }
    ]
}

 Abrufen eines Stapels

Du kannst die Details und Eigenschaften zu einem Stapel als JSON-Repräsentation abrufen oder die Detailansicht zu einem Stapel anzeigen. Dazu musst du die ID des Stapels kennen. Um einen Stapel abzurufen, musst du folgende Schritte durchführen:

  • Ermitteln der Linkrelation für das Abrufen des Stapels
  • Aufrufen der URL zum Abrufen des Stapels

 Ermitteln der Linkrelation zum Abrufen des Stapels

Verwende eine HTTP-GET-Anforderung, um die Root-URL der Inbound-App aufzurufen:

 Request

GET /inbound
Accept: application/hal+json

Das JSON-Objekt der Inbound-App enthält die Linkrelation importProcess, mit der du einen Stapel aufrufen kannst.

 Response

{
    "_links": {
        "importProcess": {
            "href": "inbound/importprocess/{id}",
            "templated": true
        }
    }
}
 Verwenden von Parametern beim Abrufen eines Stapels

Du kannst das Abrufen oder Anzeigen von Details eines Stapels mit folgenden Parametern beeinflussen:

EigenschaftBeschreibung
idGibt die ID des Stapels an, dessen Details abgerufen werden sollen.

 Aufrufen der URL zum Abfragen der Eigenschaften des Stapels

Wenn du eine URL erzeugt hast, kannst du die Details des Stapels wie folgt abrufen:

 Request

Get /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb
Accept: application/hal+json

Wenn der Aufruf erfolgreich ist, werden im Body die Eigenschaften des Stapels als JSON zurückgegeben:

 Response

HTTP/1.1 200 Ok

{
    "id": "0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb",
    "name": "my batch 1",
    "importDateTime": "2019-01-28T10:46:25.0131376Z",
    "creatorId": "4a0df94e-da62-4f84-823b-2cc97b16341e",
    "creatorName": "John Doe",
    "pageCount": 0,
    "binaries": [],
    "documents": [
        {
            "id": "6f53d725-f4f5-442e-a058-a01eaf05cbf5",
            "binaries": [],
            "sortingNumber": 1,
            "_links": {
                "self": {
                    "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5",
                    "templated": false
                },
            },
        }
    ],
    "_links": {
        "self": {
            "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb",
            "templated": false
        },
        "fileUpload": {
            "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/blob",
            "templated": false
        },
        "authorization": {
            "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/authorization",
            "templated": false
        }
    }
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
idGibt die ID des Stapels an.
nameGibt den Anzeigenamen des Stapels an.
importDateTimeGibt den Erstellungszeitpunkt des Stapels mit Datum und Uhrzeit an. Der Zeitpunkt wird in der koordinierten Weltzeit (UTC) angegeben.
creatorIdDie ID des Identityprovider-Benutzers, der den Stapel erstellt hat.
creatorNameDer aktuelle Anzeigename des Identityprovider-Benutzers, der den Stapel erstellt hat. Wenn der Benutzer in der Identityprovider-App gelöscht wird, wird der Name des Benutzers zum Erstellungszeitpunkt des Stapels zurückgegeben.
pageCountDie aktuelle Anzahl an Seiten im Stapel. Für die Anzahl werden nur Seiten berücksichtigt, die aktuell im Stapel sichtbar sind.
binariesGibt ein Array mit allen Seiten des Stapels an. Auch gelöschte Seiten werden aufgeführt.
documentsGibt ein Array mit allen Dokumenten des Stapels an.
documents._linksEnthält die Linkrelationen zum Dokument.
documents._links.selfSelf-Link des Dokuments.
_linksEnthält die Linkrelationen zum Stapel.
_links.selfSelf-Link.
_links.fileUploadURL zum Hinzufügen von Dateien zu einem Stapel. Weitere Informationen findest du im Abschnitt Hinzufügen von Seiten zu einem Stapel.
_links.authorizationURL zum Abfragen und Erteilen der Berechtigungen für den Stapel.

Wenn das Abrufen des Stapels fehlschlägt, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen findest du im Abschnitt Format der Antwort bei Fehlern.

 Aufrufen der URL für die Details eines Stapels (HTML-Seite)

Wenn du die HTML-Darstellung des Stapels aufrufen möchtest, musst du zunächst die URL erzeugen. Weitere Informationen zum Erzeugen der URL erhältst du im Abschnitt Ermitteln der Linkrelation zum Abrufen des Stapels.

Gib die URL im Browser ein, um die HTML-Seite anzuzeigen.

 Request

GET /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb
Accept: application/hal+json

 Abrufen eines Dokuments

Du kannst die Details und Eigenschaften zu einem Dokument eines Stapels als JSON-Repräsentation abrufen. Dazu musst du wissen, welche Dokumente ein Stapel enthält. Um ein Dokument abzurufen, musst du folgende Schritte durchführen:

  • Ermitteln und Aufrufen der Linkrelation für das Abrufen des Stapels
  • Ermitteln der Linkrelation für das Abrufen des Dokuments
  • Aufrufen der URL zum Abrufen des Dokuments

 Ermitteln und Aufrufen der Linkrelation für das Abrufen eines Stapels

Informationen zum Ermitteln und Aufrufen der Linkrelation des Stapels findest du im Abschnitt Abrufen eines Stapels.

 Ermitteln der Linkrelations zum Abrufen des Dokuments

Das JSON-Objekt des Stapels enthält ein Array mit allen enthaltenen Dokumenten, diese haben jeweils eine Linkrelation self, mit der du das Dokument abrufen kannst.

 Aufrufen der URL zum Abfragen der Eigenschaften des Dokuments

Führe eine HTTP GET-Anforderung auf die URL durch.

 Request

Get /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5
Accept: application/hal+json

Wenn der Aufruf erfolgreich ist, werden im Body die Eigenschaften des Dokuments als JSON zurückgegeben:

 Response

HTTP/1.1 200 Ok

{
    "id": "6f53d725-f4f5-442e-a058-a01eaf05cbf5",
    "binaries": [],
    "sortingNumber": 1,
    "properties": [
        {
            "id": "069d1f97-ab46-4d17-a4ef-0408fc4f1289",
            "value": "RN-1847",
            "name": "Order number",
            "internal": false,
            "_links": {
               "self": {
                    "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb",
                    "templated": false
                }
            },
        }
    ],
    "_links": {
        "self": {
            "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5",
            "templated": false
        },
        "addProperty": {
            "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties",
            "templated": false
        },
        "deleteProperty": {
            "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties/{propertyId}",
            "templated": false
        },
        "patchProperty": {
            "href": "/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties",
            "templated": true
        }
    }
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
idGibt die ID des Dokuments an.
binariesGibt ein Array mit allen Seiten des Dokuments an.
sortingNumberGibt die eins basierte Position des Dokuments im Stapel an.
propertiesEnthält alle Eigenschaften des Dokuments.
properties.idGibt die ID der Eigenschaft an. Weitere Informationen findest du im Abschnitt Hinzufügen von Eigenschaften zu einem Dokument.
properties.valueGibt den Wert für die Eigenschaft an.
properties.nameGibt den Anzeigenamen der Eigenschaft an.
properties.internalGibt an, ob es sich um eine interne Eigenschaft handelt. Interne Eigenschaften sind nicht zur Anzeige für den Anwender gedacht und können nicht bearbeitet werden.
_linksEnthält die Linkrelationen zum Dokument.
_links.selfSelf-Link.
_links.addPropertyURL zum Hinzufügen von Eigenschaften zu einem Dokument. Weitere Informationen findest du im Abschnitt Hinzufügen von Eigenschaften zu einem Dokument.
_links.deletePropertyURL zum Löschen von Eigenschaften eines Dokuments. Weitere Informationen findest du im Abschnitt Hinzufügen von Eigenschaften zu einem Dokument.
_links.patchPropertyURL zum Bearbeiten einer oder mehrerer Eigenschaften des Dokuments. Weitere Informationen findest du im Abschnitt Hinzufügen von Eigenschaften zu einem Dokument.

Wenn das Abrufen des Dokuments fehlschlägt, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen findest du im Abschnitt Format der Antwort bei Fehlern.

 Erteilen von Stapelberechtigungen für Benutzer oder Gruppen

Ein Anwender kann nur diejenigen Stapel sehen und bearbeiten, für die er eine Berechtigung hat. Der Stapelersteller ist zunächst der einzige Berechtigte. Wenn du Berechtigungen für einen Stapel hast, kannst du anderen Benutzern und Benutzergruppen die Berechtigung für den Stapel erteilen. Jeder Benutzer, der die Berechtigung erhält, kann den Stapel sehen und bearbeiten. Du kannst die aktuell erteilten Berechtigungen abfragen. Dafür benötigst du die ID des Stapels. Die Anforderung zum Abfragen muss im Kontext eines Benutzers durchgeführt werden, der bereits Berechtigungen für den Stapel hat. Führe diese Schritte durch:

  • Ermittle die Linkrelation für das Abrufen eines Stapels.
  • Rufe die URL zum Abrufen eines Stapels auf.
  • Ermittle die Linkrelation zum Abfragen und Erteilen von Berechtigungen.
  • Rufe die URL zum Abfragen und Erteilen von Berechtigungen des Stapels auf.

 Ermitteln und Aufrufen der Linkrelation für das Abrufen eines Stapels

Zum Ermitteln und Aufrufen der Linkrelation des Stapels, gehe wie im Abschnitt Abrufen eines Stapels vor.

 Ermitteln der Linkrelation zum Abfragen und Erteilen von Berechtigungen

Das JSON-Objekt des Stapels enthält die Linkrelation authorization, mit der die Berechtigungen für den Stapel bestimmt werden können.

 Aufrufen der URL zum Abfragen der Berechtigungen auf den Stapel

Führe eine HTTP GET-Anforderung auf die URL durch.

 Request

GET /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/authorization
Accept: application/hal+json

Wenn der Aufruf erfolgreich ist, werden im Body die Stapelberechtigungen als JSON zurückgegeben:

 Response

HTTP/1.1 200 Ok

{
    "authorizedUsers": [ "UserId1", "UserId2" ],
    "authorizedGroups": [ "GroupId1", "GroupId2" ]
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
authorizedUsersGibt ein Array mit den Identityprovider-Benutzer-IDs an, die Berechtigungen für den Stapel haben.
authorizedGroupsGibt ein Array mit den Identityprovider-Gruppen-IDs an, die Berechtigungen für den Stapel haben.

Wenn das Abrufen der Stapelberechtigungen fehlschlägt, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen findest du im Abschnitt Format der Antwort bei Fehlern.

Um anderen Benutzern oder Benutzergruppen die Berechtigungen zum Anzeigen und Bearbeiten eines Stapels zu erteilen, musst du die ID des Stapels kennen (wie beim Abfragen der Berechtigungen). Die Anforderung muss außerdem im Kontext eines Benutzers durchgeführt werden, der Berechtigungen für den Stapel hat. Um eine oder mehrere Berechtigungen für einen Stapel zu erteilen, führe folgende Schritte durch:

  • Ermittle die Linkrelation zum Abfragen und Erteilen von Berechtigungen. Wie du die Linkrelation ermittelst, erfährst du im Abschnitt Ermitteln der Linkrelation zum Abrufen des Stapels.
  • Rufe die URL zum Abfragen und Erteilen von Berechtigungen des Stapels auf.

 Aufrufen der URL zum Erteilen von Berechtigungen für den Stapel

Führe eine HTTP POST-Anforderung mit den benötigten Eigenschaften als Body auf diese URL aus.

 Request

POST /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/authorization
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "authorizedUsers": [ "UserId3", "UserId4" ],
    "authorizedGroups": [ "GroupId3", "GroupId4" ]
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
authorizedUsersGibt das Array mit den Identityprovider-Benutzer-IDs an, die Zugriff auf den Stapel erhalten sollen.
authorizedGroupsGibt das Array mit den Identityprovider-Gruppen-IDs an, die Zugriff auf den Stapel erhalten sollen.

Du kannst beliebig viele Benutzer oder Gruppen oder eine Kombination aus beiden angeben. Mindestens eines der beiden Arrays muss einen Wert enthalten. Beachte beim Angeben von Benutzern oder Gruppen folgende Hinweise:

  • Benutzer und Gruppen, die bereits Zugriff auf den Stapel haben, werden nicht erneut hinzugefügt.
  • Bei der Übergabe einer Gruppen-ID wird nur die Gruppe und nicht die aktuell darin befindlichen Mitglieder der Gruppe gespeichert. Wenn sich also nachträglich die Mitglieder der Gruppe ändern, hat die Änderung auch Auswirkungen auf die Zugriffsberechtigungen des Stapels.
  • Wenn in der Anfrage Benutzer oder Gruppen fehlen, die bereits Zugriff auf den Stapel haben, wird den entsprechenden Benutzern oder Gruppen die Berechtigung auf den Stapel durch die Anfrage nicht entzogen.

Ist der Aufruf erfolgreich, wird der HTTP-Statuscode 200 zurückgegeben. Wenn das Konfigurieren der Berechtigungen fehlschlägt, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen findest du im Abschnitt Format der Antwort bei Fehlern.

 Hinzufügen von Seiten zu einem Stapel

Du kannst einem Stapel automatisiert Seiten hinzufügen. Dazu musst du die ID des Stapels kennen. Die Anforderung (Request) muss im Kontext eines Benutzers durchgeführt werden, der Berechtigungen auf den Stapel hat. Um eine oder mehrere Seiten zu einem Stapel hinzuzufügen, führe folgende Schritte durch:

  • Ermittle die Linkrelation für das Abrufen eines Stapels.
  • Rufe die URL zum Abrufen eines Stapels auf.
  • Ermittle die Linkrelation zum Hinzufügen von Seiten.
  • Rufe die URL zum Hinzufügen von Seiten auf.

Du kannst Seiten auf zwei verschiedene Weisen hinzufügen:

  • Beim Aufruf der URL zum Hinzufügen von Seiten sendest du eine Datei im Body mit.
  • Beim Aufruf der URL zum Hinzufügen von Seiten sendest du einen Verweis auf eine Datei im Body mit.

Folgende Dateitypen werden unterstützt:

  • pdf
  • tiff
  • jpeg
  • gif
  • bmp
  • png
  • docx (nur Cloud)
  • xlsx (nur Cloud)
  • pptx (nur Cloud)
  • msg (nur Cloud)
  • eml (nur Cloud)
  • xml (xRechnungen- und ZUGFeRD-Formate; nur Cloud)

 Ermitteln und Aufrufen der Linkrelation für das Abrufen eines Stapels

Informationen zum Ermitteln und Aufrufen der Linkrelation des Stapels findest du im Abschnitt Abrufen eines Stapels.

 Ermitteln der Linkrelation zum Hinzufügen von Seiten

Das JSON-Objekt des Stapels enthält die Linkrelation fileUpload, mit der du Seiten zu einem Stapel hinzufügen kannst.

 Aufrufen der URL zum Hinzufügen von Seiten

Wenn du die Datei im Body mitsenden möchtest, führe eine HTTP POST-Anforderung mit der Datei im Body auf diese URL aus. Zusätzlich musst du den Header-Wert Content-Type entsprechend füllen. Wenn du alternativ einen Verweis auf die Datei angeben möchtest, führe eine HTTP POST-Anforderung mit den benötigten Eigenschaften als Body an diese URL aus.

 Request

POST /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/blob
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json
Content-Disposition: attachment; filename="ExampleName.pdf"

{
    "contentUri": "/myApp/files/6979814d-8dbe-4998-adc0-cc570a42fa92"
}

Der Wert des Parameters Content-Disposition wird als Anzeigename des Dokumentes verwendet. Der Dateiname muss als URI kodiert im Content-Disposition-Parameter eingefügt werden. Der Paramter contentUri ist ein Pflichtparameter. Die URI kann relativ zur Basisadresse oder absolut sein. Wenn die URI relativ zur Basisadresse ist, werden die Authentifizierungsinformationen des aktuellen Benutzers weitergegeben. Wenn der Aufruf erfolgreich ist, wird die URL zur hinzugefügten Datei im Header Location zurückgegeben.

 Response

HTTP/1.1 201 Created
Location: /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/blob/294c0d89-1e3f-4917-9b8e-32a42afa2954

Wenn das Hinzufügen von Seiten fehlschlägt, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen findest du im Abschnitt Format der Antwort bei Fehlern.

 Hinzufügen von Eigenschaften zu einem Dokument

Du kannst die Eigenschaften von Dokumenten in einem Stapel automatisiert festlegen und bearbeiten. Dazu musst du die ID des Stapels kennen. Die Anforderung (Request) muss im Kontext eines Benutzers durchgeführt werden, der Berechtigungen auf den Stapel hat. Um eine oder mehrere Eigenschaften zu einem Dokument hinzuzufügen, führe folgende Schritte durch:

  • Ermittle die Linkrelation für das Abrufen eines Stapels.
  • Rufe die URL zum Abrufen eines Stapels auf.
  • Ermittle die Linkrelation zum Abrufen der verfügbaren Eigenschaftsfelder.
  • Rufe die URL zum Abrufen der verfügbaren Eigenschaften auf.
  • Ermittle die Linkrelation zum Abrufen des Dokumentes, dessen Eigenschaften du bearbeiten möchtest.
  • Ermittle die Linkrelationen zum Hinzufügen, Löschen oder Bearbeiten der Eigenschaft.
  • Rufe die URL der Aktion auf, die du ausführen möchtest.

 Ermitteln und Aufrufen der Linkrelation für das Abrufen eines Stapels

Informationen zum Ermitteln und Aufrufen der Linkrelation des Stapels findest du im Abschnitt Abrufen eines Stapels.

 Ermitteln der Linkrelations zum Abrufen der Eigenschaftsfelder

Das JSON-Objekt des Stapels enthält die Linkrelation propertyDefinition, mit der du alle in der Inbound-App vorhandenen Eigenschaftsfelder abrufen kannst.

 Aufrufen der URL zum Abfragen der Eigenschaftsfelder

Führe eine HTTP GET-Anforderung auf die URL durch.

 Request

GET /inbound/propertydefinitions
Accept: application/hal+json

Wenn der Aufruf erfolgreich ist, werden im Body die verfügbaren Eigenschaftsfelder als JSON zurückgegeben:

 Response

HTTP/1.1 200 Ok

{
    "propertyDefinitions": [
        {
            "id": "069d1f97-ab46-4d17-a4ef-0408fc4f1289",
            "custom": false,
            "name": "Order number",
            "propertyType": 1
        },
        {
            "id": "0d36c8da-c5ef-4cd3-9e75-9a931dcb6c7a",
            "custom": false,
            "name": "Total amount",
            "propertyType": 2,
            "belongsTo": "66de5185-b270-4920-8f01-643a7ea4b7b1"
        },
        {
            "id": "66de5185-b270-4920-8f01-643a7ea4b7b1",
            "custom": false,
            "name": "Total amount currency",
            "propertyType": 5,
            "belongsTo": "0d36c8da-c5ef-4cd3-9e75-9a931dcb6c7a"
        }
    ]
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
idGibt die ID der Eigenschaft an. Mit dieser ID kann die Eigenschaft auf einem Dokument ausgelesen und bearbeitet werden.
customGibt ab, ob die Eigenschaft durch den Administrator oder das System erzeugt wurde.
nameGibt den Namen der Eigenschaft in der angefragten Sprache an.
propertyTypeGibt den Datentyp der Eigenschaft an. Mögliche Werte findest du in der untenstehenden Tabelle für verfügbare Werte der Eigenschaft propertyType.
belongsToEin optionaler Verweis auf eine zweite verknüpfte Eigenschaft. Z.B. zwischen einem Zahlenfeld und einem Währungsfeld, die zusammen einen Geldwert darstellen.
 Verfügbare Werte für die Eigenschaft "propertyType" eines Eigenschaftsfeldes
WertBeschreibung
1String Textwert mit maximal 450 Zeichen.
2Number Zahlenwert mit Punkt als Dezimaltrenner im Wertebereich zwischen ±1.0×10^-28 bis ±7.9228 × 10^28.
3Date Datumswert im Format yyyy-MM-dd.
4DateTime Datums- und Zeitwert im Format yyyy-MM-ddTHH:mm:ss.fffzzz.
5Currency Währungskürzel mit drei Zwichen nach ISO 4217.

 Ermitteln und Aufrufen der Linkrelation für das Abrufen eines Dokuments

Informationen zum Ermitteln und Aufrufen der Linkrelation des Dokuments findest du im Abschnitt Abrufen eines Dokuments.

 Ermittle die Linkrelationen zum Hinzufügen, Löschen oder Bearbeiten der Eigenschaft

Abhängig davon, was du mit der Eigenschaft machen möchtest, benötigst du eine der folgenden drei Linkrelationen aus dem JSON-Objekt des Dokuments:

  • addProperty, mit der du dem Dokument eine Eigenschaft hinzufügen kannst, sofern es diese Eigenschaft noch nicht enthält.
  • deleteProperty, mit der du eine Eigenschaft des Dokuments löschen kannst, sofern es diese Eigenschaft enthält.
  • patchProperty, mit der du den Wert einer Eigenschaft des Dokuments bearbeiten kannst, sofern es diese Eigenschaft bereits enthält.

 Aufrufen der URL zum Hinzufügen einer Eigenschaft

Führe eine HTTP POST-Anforderung gegen die addProperty Route aus.

 Request

POST /inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "propertyDefinitionId": "069d1f97-ab46-4d17-a4ef-0408fc4f1289",
    "value": "RN-1857"
}

Das Feld propertyDefinitionId muss die ID eines der zuvor abgerufenen Eigenschaftsfelder enthalten. Das Feld value muss den gewünschten Wert als string enthalten. Der string muss entsprechend dem propertyType des Eigenschaftsfeldes formatiert sein.

 Response

HTTP/1.1 201 Created
Location: /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties/069d1f97-ab46-4d17-a4ef-0408fc4f1289

{
    "id": "069d1f97-ab46-4d17-a4ef-0408fc4f1289",
    "name": "Order number",
    "value": "value",
    "internal": false
}

 Aufrufen der URL zum Löschen einer Eigenschaft

Ersetze den Platzhalter {propertyId} in der deleteProperty Route durch die ID der zu löschenden Eigenschaft und führe eine HTTP DELETE-Anforderung gegen die Route aus.

 Request

DELETE /inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties/069d1f97-ab46-4d17-a4ef-0408fc4f1289
Origin: https://baseuri
Accept: application/hal+json
 Response

HTTP/1.1 200 OK

 Aufrufen der URL zum Bearbeiten einer Eigenschaft

Führe eine HTTP PATCH-Anforderung gegen die patchProperty Route aus, um eine oder mehrere Eigenschaften gleichzeitig zu bearbeiten.

 Request

PATCH /inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "patches": [
        {
            "op": "REPLACE",
            "path": "0d36c8da-c5ef-4cd3-9e75-9a931dcb6c7a",
            "value": "123"
        },
        {
            "op": "REPLACE",
            "path": "66de5185-b270-4920-8f01-643a7ea4b7b1",
            "value": "EUR"
        }
    ]
}

Das Feld patches enthält ein Array von patch-Objekten. Das Feld patches.op enthält die Operation, hier immer "REPLACE". Das Feld patches.path muss die ID einer am Dokument gesetzten Eigenschaft enthalten. Das Feld patches.Value muss den gewünschten Wert als string enthalten. Der string muss entsprechend dem propertyType des Eigenschaftsfeldes formatiert sein.

 Response

HTTP/1.1 200 OK
 Error Response

Wenn das Bearbeiten der Eigenschaften fehlschlägt, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen findest du im Abschnitt Format der Antwort bei Fehlern. Wenn nur einzelne Eigenschaften des Requests nicht geändert werden konnten, enthält die Antwort zusätzlich zu den üblichen Feldern eine Aufzählung der nicht erfolgreich ausgeführten Operationen. Alle nicht in dieser Aufzählung enthaltenen Eigenschaften des Requests wurden erfolgreich geändert.


HTTP/1.1 400 BadRequest

{
    "reason": "Not all properties were updated: 0d36c8da-c5ef-4cd3-9e75-9a931dcb6c7a: Invoice is not a valid number.",
    "severity": 3,
    "errorCode": 0,
    "PatchErrors": {
        "0d36c8da-c5ef-4cd3-9e75-9a931dcb6c7a": "Invoice is not a valid number."
    }
}

Das zusätzliche Feld PatchErrors ist ein Dictionary mit den IDs der nicht erfolgreich verarbeiteten Eigenschaften als Schlüssel und einer zugehörigen Fehlermeldung als Wert.

 Ändern von Kategorie und Name eines Dokuments

Du kannst die Kategorie sowie den Namen einzelner Dokumente ändern. Dazu musst du die ID des Stapels sowie die ID des Dokuments kennen. Die Anforderung (Request) muss im Kontext eines Benutzers durchgeführt werden, der Berechtigungen auf den Stapel hat.

  • Ermittle die Linkrelation für das Abrufen eines Stapels.
  • Rufe die URL zum Abrufen eines Stapels auf.
  • Ermittle die Linkrelation zum Ändern des Dokuments.
  • Ändere das Dokument durch Aufruf der URL.

 Ermitteln und Aufrufen der Linkrelation für das Abrufen eines Stapels

Informationen zum Ermitteln und Aufrufen der Linkrelation des Stapels findest du im Abschnitt Abrufen eines Stapels.

 Ermitteln der IDs der Kategorien

Zum Ändern der Kategorie wird die ID der entsprechenden Kategorie benötigt. Dazu ist es möglich, eine Liste aller Kategorien zu erhalten.

 Request

GET /inbound/categories
Origin: https://baseuri
Accept: application/hal+json
 Response

{
    "categories":[
        {
        "id": "dc144c5f-bd22-4f4f-92a8-338782db479c",
        "name": "Contract"
        }
    ]
}

 Ermitteln und Aufrufen der URL zum Ändern des Dokuments

Ersetze den Platzhalter {documentId} in der documentUpdate Route durch die ID des zu ändernden Dokuments und führe eine HTTP PATCH-Anforderung aus. Diese findest du im JSON-Objekt des Stapels.

 Request

PATCH /inbound/importprocess/e69bb791-3a90-4ebf-bd9d-36d411886c92/document/62a2cd1c-26b9-45cf-897d-8de6ba46e0b8
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
    "patches": [
        {
            "op": "REPLACE",
            "path": "/category",
            "value": "c3dc3e4b-34d5-41cd-bb9e-755b3b5c62a0"
        },
        {
            "op": "REPLACE",
            "path": "/name",
            "value": "newname"
        }
    ]
}
 Hinweise zu den Eigenschaften
EigenschaftHinweis
patchesArray von patch-Objekten
opOperation des patches, hier immer REPLACE
pathZu ändernder Wert, hier immer /category oder /name
valueDer neue Wert des Feldes als string. Bei der Kategprie muss hier die ID angegeben werden
 Response

HTTP/1.1 200 OK
 Error Response

Wenn das Bearbeiten der Eigenschaften fehlschlägt, wird eine entsprechende Antwort (Response) zurückgegeben. Weitere Informationen findest du im Abschnitt Format der Antwort bei Fehlern.


HTTP/1.1 400 BadRequest

{
    "reason": "Path value '/invalidPath' is not valid.",
    "details": "Exception type: System.ArgumentException",
    "severity": 3,
    "errorCode": 0
}

 Abschließen des Imports

Wenn du das Hinzufügen von Seiten beendet hast, kannst du den Import abschließen. Nach dem Abschluss des Imports und der Analyse aller einzelnen Seiten, beginnt ein Analyseprozess für alle Dokumente. Beim Analyseprozess weist die Anwendung den Dokumenten automatisch Kategorien zu. Wenn du den Import eines Stapels abschließt, ist er größtenteils für die manuelle Bearbeitung gesperrt.

 Ermitteln und Aufrufen der Linkrelation für das Abrufen eines Stapels

Wie du die Linkrelation des Stapels ermittelst und aufrufst, erfährst du im Abschnitt Abrufen eines Stapels.

 Ermitteln der Linkrelation zum Abschließen des Imports

Das JSON-Objekt des Stapels enthält die Linkrelation update, mit der du den Status des Stapels per HTTP PATCH-Anforderung verändern kannst. Um den Import abzuschließen, verwende den Wert 1 für den Paramter value.

 Request

PATCH /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
    "path": "/state",
    "Op": "REPLACE",
    "value": "1"
}

Eine Antwort mit Status-Code 200 signalisiert dir, dass der Aufruf erfolgreich war.

 Response

HTTP/1.1 200 OK

 Anbinden von externen Systemen

In diesem Abschnitt erfährst du, wie du externe Systeme (Drittanbieteranwendungen) an die Inbound-App anbinden kannst, um weitere Zielsysteme zu integrieren. Mit Erweiterungspunkten hast du die Möglichkeit, die Inbound-App um deine eigenen Funktionen zu erweitern.

 Vorbereiten deiner App

Damit Erweiterungen von der Inbound-App gefunden werden, muss deine App diese Schnittstelle bereitstellen. Die Inbound-App nutzt zum Auffinden von Apps, die Erweiterungen bereitstellen, das Konzept einer HTTP GET-Anforderung für die Root-Ressource der Apps (systemBaseUri-Pfad mit dem App-Namen). Es werden alle Apps abgefragt, die am HTTP-Gateway registriert sind. Stelle sicher, dass der Administrator deine App nicht aktiv ausgeschlossen hat.

 Bereitstellen der URL zu den Erweiterungspunkten

Die Root-Ressourcen dieser Apps werden zyklisch abgefragt (Request). Die Antwort (Response) einer App wird daraufhin geprüft, ob eine Linkrelation namens inboundExtensions enthalten ist. Diese Linkrelation gilt als Signal, dass die App Erweiterungen für die Inbound-App anbietet. Die Inbound-App führt eine HTTP GET-Anforderung auf den angegebenen Link aus und erwartet von der antwortenden App ein genormtes JSON-Objekt mit dem HTTP-Statuscode 200.

 Request

GET https://host/myapp/ HTTP/1.1
Accept: application/hal+json
 Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
    "_links" : {
        "inboundExtensions" : {
            "href" : "/myapp/inboundExtensions"
        }
    }
}

Hinweis

Die Abfrage der Root-Ressourcen erfolgt anonym (ohne Authentifizierung).

 Hinzufügen von Exportsystemen

Du kannst manuelle und automatische Exportsysteme hinzufügen. Wenn du ein manuelles Exportsystem hinzufügst, wird dieses System deinen Anwendern im Exportassistenten angeboten. Automatische Exportsysteme dienen der Speicherung von Stapeln ohne Benutzerinteraktion.

 Beispiel

Das Beispiel zeigt, wie du die HTTP-Antwort der Linkrelation inboundExtensions gestaltest, um mithilfe des Erweiterungspunkts ein manuelles und ein automatisches Exportsystem hinzuzufügen.

 Response

{
    "extensions": [
        {
            "id": "myapp-FileDownload",
            "caption": "Download file",
            "context": "ExportImportProcess",
            "uriTemplate": "/myapp/export",
            "activationConditions": [
                {
                    "propertyId": "exportedDocuments.count",
                    "operator": "OR",
                    "values": [
                        "2"
                    ]
                }
            ]
        },
        {
            "id": "myapp-AutomatedExport",
            "caption": "Automated export from myApp",
            "context": "ExportImportProcessAutomated",
            "uriTemplate": "/myapp/exportautomated"
        }
    ]
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
idLegt den eindeutigen technischen Namen fest, der verwendet wird, um die Erweiterung von anderen Erweiterungen zu unterscheiden.
captionAnzeigetext der Erweiterung im Exportassistenten.
contextLegt fest, ob es sich um ein manuelles oder ein automatisches Exportsystem handelt. Gib für ein manuelles Exportsystem den Wert ExportImportProcess und für ein automatisches Exportsystem den Wert ExportImportProcessAutomated an.
uriTemplateDefiniert die URL, die von der Inbound-App mit dem unten beschriebenen JSON-Objekt aufgerufen werden soll. Hierbei werden keine URL-Parameter unterstützt.
activationConditions (nur verfügbar für manuelle Exportsysteme)Pro Erweiterung teilt die Anwendung mit, unter welchen Aktivierungsbedingungen das manuelle Exportsystem angezeigt werden soll. Ein Exportsystem wird dann angezeigt, wenn alle Einzelbedingungen zutreffen. Wenn die Liste der Aktivierungsbedingungen keinen Eintrag enthält, ist das Exportsystem immer aktiv. Wenn eine Aktivierungsbedingung inhaltlich nicht korrekt ist, wird die Bedingung ebenfalls als aktiv angesehen. Aktivierungsbedingungen werden als Array angegeben.
activationConditions[].propertyIdGibt die ID der Eigenschaft an, die für die Aktivierungsbedingung geprüft wird. Mögliche Werte findest du in der untenstehenden Tabelle für verfügbare Werte der Eigenschaft propertyId.
activationConditions[].operatorDer Operator gibt an, auf welche Art und Weise eine Einzelbedingung ausgewertet wird. Mögliche Werte findest du in der untenstehenden Tabelle für verfügbare Werte der Eigenschaft operator.
activationConditions[].valuesGibt die Werte in Form eines Arrays an, die mit dem Wert der propertyId-Eigenschaft verglichen werden.
 Verfügbare Werte für die Eigenschaft "propertyId" einer Aktivierungsbedingung
WertBeschreibung
properties.nameDer Name des aktuellen Stapels.
properties.creatorNameDer Name des Stapelerstellers.
properties.importDateTimeDas Erstelldatum des Stapels im ISO 8601-Format.
properties.*Eine Eigenschaft des Stapels, die du mit der API bestimmen kannst. Du musst das Sternchen mit der angegebenen Eigenschaft ersetzen. Mehr Informationen findest du im Abschnitt Aufrufen der URL zur Erstellung eines Stapels.
 Verfügbare Werte für die Eigenschaft "operator" einer Aktivierungsbedingung
WertBeschreibung
OREine OR-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft einem der Werte entspricht. Die Groß- und Kleinschreibung wird nicht berücksichtigt.
NOTOREine NOTOR-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft keinem der Werte entspricht. Die Groß- und Kleinschreibung wird nicht berücksichtigt.
NOTEMPTYEine NOTEMPTY-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft nicht leer ist.
GREATERTHANEine GREATERTHAN-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft größer ist als der erste Wert.
SMALLERTHANEine SMALLERTHAN-Bedingung ist dann erfüllt, wenn der aktuelle Wert der Eigenschaft kleiner ist als der erste Wert.
 Aufrufen des Exportsystems

Die Inbound-App führt eine HTTP POST-Anforderung an die als Eigenschaft (uriTemplate) angegebene URL aus. Die benötigten Eigenschaften werden als Body gesendet.

 Request

POST /myapp/export
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{ 
    "importProfileId": "62fd81f9-eb87-4461-9f3d-b1cd66bb5dde",
    "documents": [
        {
            "propertiesUri": "/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties",
            "sourceFilesUri": "/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/sourcefiles",
            "originFilesUri": "/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/originfiles",
            "successCallbackUri": "/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/stored/505d86b1-0a21-45f3-8b1f-80112138b497",
            "primaryExportFile": 2,
            "exportFiles": [
                {
                    "downloadUrl": "/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/blob/faf1de7e-467b-4c5f-9f33-1ab0fcc45013?ImportProcessId=fcc8c956-bfcb-4b30-bc09-9161f6f16eb2",
                    "mimeType": "application/pdf",
                    "extension": ".pdf"
                }
            ],
            "sourceSystem": "inboundApp"
        }
    ]
}

Mit der HTTP POST-Anfrage wird eine Liste von Dokumenten an das Exportsystem übergeben.

 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
importProfileIdGibt die Id des Importprofils an, mit dem die Dokumente importiert wurden.
propertiesUriMit der URL der Eigenschaft propertiesUri kannst du die Eigenschaften und Nachbearbeitungsoptionen des Dokuments abfragen. Die Abfrage, ob ein Dokument nach dem erfolgreichen Export gelöscht werden soll, ist eine mögliche Nachbearbeitungsoption. Diese Option wird von der Inbound-App übermittelt.
sourceFilesUriMit der URL der Eigenschaft sourceFilesUri kannst du die Quelldateien des Dokumentes ermitteln. Mit einer HTTP GET-Anforderung erhältst du eine Liste von URLs. Diese Liste enthält die Dateien, aus denen das Dokument entstanden ist. Für bestimmte Prozesse müssen diese Dateien dauerhaft gespeichert werden.
originFilesUriMit der URL der Eigenschaft originFilesUri kannst du die importierten Dateien des Dokumentes ermitteln. Mit einer HTTP GET-Anforderung erhältst du eine Liste von URLs. Diese Liste enthält die Dateien, die der Anwender importiert hat und aus denen gegebenenfalls die Quelldateien des Dokuments entstanden sind. Für bestimmte Prozesse müssen diese Dateien dauerhaft gespeichert werden.
authorizationUriMit der URL der Eigenschaft authorizationUri kannst du die Stapelberechtigungen des Dokumentes ermitteln. Mit einer HTTP GET-Anforderung erhältst du die Liste die unter Aufrufen der URL zum Abfragen der Berechtigungen auf den Stapel beschrieben ist. Für bestimmte Prozesse empfielt es sich, die gleichen Benutzer auf die Weiterverarbeitung zu berechtigen.
successCallbackUriMit der URL der Eigenschaft successCallbackUri musst du der Inbound-App beim manuellen Export mitteilen, wenn das Dokument vom Exportsystem erfolgreich gespeichert wurde. Der Aufruf muss für jedes Dokument erfolgen. Führst du diesen Schritt nicht durch, kann die Inbound-App die Nachbearbeitungsoptionen nicht auswerten und die Benutzererfahrung wird gemindert. Für automatische Exportsysteme ist das Aufrufen des Success-Callbacks nur notwendig, wenn der Ablagevorgang asynchron durchgeführt wird (siehe Antwort des Exportsystems bei der automatischen Ablage).
errorCallbackUriDie URL der Eigenschaft errorCallbackUri steht nur bei der automatischen Ablage zur Verfügung. Das Aufrufen des Error-Callbacks ist nur notwendig, wenn der Ablagevorgang asynchron durchgeführt wird (siehe Antwort des Exportsystems bei der automatischen Ablage).
primaryExportFileDieser Parameter entscheidet, ob die generierte Datei im Original- oder als PDF-Format bereitgestellt wird. Je nachdem, welches Profil du verwendest, wird der jeweilige Standardwert verwendet. Der Wert 1 steht für das Original-, der Wert 2 für ein PDF-Format.
exportFilesFür jede generierte Datei teilt die Anwendung mit, unter welcher URL die Datei abgerufen werden kann. Die Eigenschaft downloadUrl enthält die URL zu der erstellten Datei. Die Eigenschaft mimeType beschreibt den Internet Media Type und extension die konkrete Dateiendung der erstellten Datei.
sourceSystemGibt das Quellsystem an, aus dem das Dokument stammt. Du kannst die Eigenschaft verwenden, um Eigenschaften aus anderen Apps abzufragen.
 Antwort des Exportsystems bei der manuellen Ablage

Bei einem manuellen Exportsystem muss die erfolgreiche Antwort des Exportsystems auf die HTTP POST-Anforderung eine URL zum Exportdialog des Exportsystems als Location-Header zurückgeben:

 Response

HTTP/1.1 201 Created
Location: /myapp/downloadpage
 Antwort des Exportsystems bei der automatischen Ablage

Beim automatischen Export muss dein Exportsystem für jedes Dokument zurückgeben, ob es erfolgreich gespeichert werden konnte. Dazu gibt es zwei Möglichkeiten. Als erste Möglichkeit kann dein Exportsystem die Anfrage der Inbound-App synchron verarbeiten und nach durchgeführtem Export das folgende Ergebnis zurückliefern:

 Response

HTTP/1.1 200 OK

{
    "storeResult": [
        {
            "location": "/myapp/location",
            "errorCode": 0,
            "message": "",
        }
    ]
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
storeResultFür jedes Dokument, das beim Aufrufen des Exportsystems übergeben wurde, musst du angeben, ob es erfolgreich verarbeitet wurde. Weitere Informationen findest du im Abschnitt Aufrufen des Exportsystems. Bei der automatischen Ablage werden erfolgreich exportierte Dokumente immer aus dem Stapel gelöscht.
storeResult[].locationGibt den Speicherort des Dokuments an.
storeResult[].messageIm Fehlerfall kannst du eine Beschreibung des Fehlers bereitstellen.

Alternativ kann dein Exportsystem den Ablagevorgang asynchron ausführen. Dies bietet sich insbesondere für die Verarbeitung großer Dokumente an, um Zeitüberschreitungen während des Exports zu vermeiden. Dazu muss dein Exportsystem den Aufruf des Exportsystems mit dem HTTP-Status 202 Accepted beantworten. Die Inbound-App wertet in diesem Fall den Inhalt der Antwort nicht aus und wartet darauf, dass für jedes Dokument entweder der Success- oder der Error-Callback aufgerufen wird.

 Aufruf des Success-Callbacks

POST /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/74e53fa9-d8fb-4769-85ff-0783902f3ba2/storesuccess?tokenId=f30dae4a-488e-441c-a8c7-95ed5421f6c2
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
    "location": "/myapp/location"
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
locationGibt den Speicherort des Dokuments an.
 Aufruf des Error-Callbacks

POST /inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb/document/91aba59a-cf40-4599-9a3d-792f36ccfdf6/storeerror?tokenId=ea1fb6cb-02f6-4fce-ae3d-bd18c7c3d0dd
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/json

{
    "message": "Error while storing",
    "errorCode": 123
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
messageIm Fehlerfall kannst du eine Beschreibung des Fehlers bereitstellen.
 Abfragen der Eigenschaften und Nachbearbeitungsoptionen

Um die Eigenschaften und Nachbearbeitungsoptionen eines Dokuments abzufragen, führe eine HTTP GET-Anforderung auf die als propertiesUri hinterlegte URL aus. Nachbearbeitungsoptionen musst du beim manuellen Export mit der URL der Eigenschaft successCallbackUri übergeben. In der Antwort werden auch Eigenschaften aufgelistet, die bei der Erstellung des Stapels angegeben werden. Weitere Informationen findest du im Abschnitt Erstellen eines Stapels.

 Request

GET /inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties
Accept: application/hal+json

Das JSON-Objekt enthält folgende Informationen:

 Response

{
   "properties": [
        {
            "key": "creatorName",
            "values": [
                "Andrew Administrator"
            ],
            "type": "String"
        },
        {
            "key": "importProcessname",
            "values": [
                "Batch name"
            ],
            "type": "String"
        },
        {
            "key": "importProcessId",
            "values": [
                "2ae14919-6e90-4534-ad2b-2fbc79d3e51d"
            ],
            "type": "String"
        },
        {
            "key": "importDateTime",
            "values": [
                "2019-01-01T12:00:00+02:00"
            ],
            "type": "Datetime"
        },
        {
            "key": "documentName",
            "values": [
                "6f53d725-f4f5-442e-a058-a01eaf05cbf5"
            ],
            "type": "String"
        },
        {
            "key": "documentCategoryId",
            "values": [
                "cb2ea8f9-9980-4ac7-9777-025173b2a5f1"
            ],
            "type": "String"
        },
        {
            "key": "documentCategoryName",
            "values": [
                "E-Mail"
            ],
            "type": "String"
        }
    ],
    "userData": [
        {
            "key": "deleteBatchUserData",
            "display": "Delete document after successful storage?",
            "values": [
                {
                    "value": "delete",
                    "display": "Delete document",
                    "default": false
                },
                {
                    "value": "notDelete",
                    "display": "Keep document",
                    "default": true
                }
            ]
        }
    ]
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
propertiesListe der Eigenschaften.
properties[].keySchlüssel der Eigenschaft.
properties[].valuesListe der Werte.
properties[].typeDatentyp, der die Eigenschaft beschreibt.
userDataListe der Nachbearbeitungsoptionen.
userData[].keySchlüssel der Eigenschaft.
userData[].displayAnzeigetext.
userData[].valuesListe der Werte.
userData[].values[].valueWert der Eigenschaft.
userData[].values[].displayAnzeigetext.
userData[].values[].defaultDefinition des Standardwerts.
 Verfügbare Datentypen für die Eigenschaft "properties"
DatentypBeschreibung
StringDatentyp für Zeichenketten.
DatetimeDatentyp für Zeitangaben im ISO 8601-Format.
NumberDatentyp für Ganzzahlen und Gleitkommazahlen.
 Hinweise zu den Eigenschaften eines Dokuments
EigenschaftBeschreibung
creatorNameName des Stapelerstellers.
editorIdID des Benutzers, der den Stapel zuletzt geöffnet hat. Bei einer automatischen Verarbeitung ist das Feld leer.
importProcessnameName des Stapels.
importProcessIdID des Stapels.
importDateTimeErstellungszeitpunkt des Stapels.
documentNameName des Dokuments.
documentCategoryIdID der Dokumentkategorie.
documentCategoryNameName der Dokumentkategorie.
 Übergeben der Nachbearbeitungsoptionen

Um beim manuellen Export die Nachbearbeitungsoptionen an die Inbound-App zu übertragen, führe eine HTTP POST-Anfrage an die URL der Eigenschaft successCallbackUri aus.

 Request

POST /inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/stored/505d86b1-0a21-45f3-8b1f-80112138b497
Origin: https://baseuri
Content-Type: application/json

{
    "location": "/myapp/location",
    "userData": [
        {
            "key": "deleteBatchUserData",
            "values": [
                "notDelete"
            ]
        }
    ]
}
 Hinweise zu den Eigenschaften
EigenschaftBeschreibung
locationSpeicherort des Dokuments.
userData[].keySchlüssel der Nachbearbeitungsoption.
userData[].valuesListe der ausgewählten Werte.

 Einschränken von Exportsystemen

Standardmäßig werden im Exportassistenten sämtliche Exportsysteme angezeigt. Mit einem Query-Parameter oder einer Stapeleigenschaft kannst du die Anzeige der manuellen Exportsysteme steuern.

 Einschränken des Exportsystems mit einem Query-Parameter

Um nur das Exportsystem mit der ID myapp-FileDownload anzuzeigen, rufe einen Stapel mit der folgenden URL auf.

 URL für ein ExportSystem

/inbound/importprocess/0f6f3e65-4dc4-4956-a3b6-0c6dd79017cb?exportSystem=myapp-FileDownload

Wenn der Query-Parameter mehrfach vorhanden ist, werden alle angegebenen Exportsysteme angezeigt.

 Einschränken des Exportsystems mit der Stapeleigenschaft

Um nur das Exportsystem mit der ID myapp-FileDownload anzuzeigen, musst du beim Erstellen des Stapels die Eigenschaft exportSystem verwenden. Beim Erstellen eines Stapels mit einer HTTP POST-Anforderung musst du die Stapeleigenschaft exportSystem verwenden.

 Request

POST /inbound/importprocess
Origin: https://baseuri
Accept: application/hal+json
Content-Type: application/hal+json

{
    "name": "my batch 1",
    "properties": {
        "exportSystem": "myapp-FileDownload"
    }
}

Alternativ kannst du die Stapeleigenschaft exportSystem auch bei einer HTTP GET-Anforderung beim Erstellen eines Stapels angeben.

 Request

/inbound/importprocess/new?exportSystem=myapp-FileDownload
 Erstellen eines Exportsystems mit Aktivierungsbedingungen

Beim Erstellen eines Exportsystems können Aktivierungsbedingungen angegeben werden. Diese Bedingungen werden beim Aufruf der Exportseite berücksichtigt. Weitere Informationen findest du im Abschnitt Hinzufügen von Exportsystemen.