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. Parametername: 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: - Erteilen von Stapelberechtigungen für Benutzer oder Gruppen - Hinzufügen von Seiten zu einem Stapel - Abschließen des Imports

 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",
    "properties": {
        "sa.propertyKey1": "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. Zusätzlich kannst du mit dem Feld properties weitere Eigenschaften übergeben. Dieses Feld ist optional und muss nicht übergeben werden. Du solltest einen eindeutigen 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. 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.

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

Request


/inbound/importprocess/new?BatchProfileId=ProfileID

Über den Parameter BatchProfileId kann dem Stapel ein Importprofil zugewiesen werden. Wird der Parameter nicht angegben, wird in der Oberfläche ein Dialog angezeigt, über den das Importprofil ausgewählt werden kann.

 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"
      }
   ]
}

 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": [],
    _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.
_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

 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: - application/pdf - image/tiff - image/jpeg - image/gif - image/bmp - image/png

 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"
x-dv-splitdocument: 1
{
    "contentUri": "/myApp/files/6979814d-8dbe-4998-adc0-cc570a42fa92"
}

Mit dem Parameter x-dv-splitdocument wird gesteuert, dass beim Import der Datei ein neues Dokument erzeugt wird. Wenn du für den Parameter x-dv-splitdocument den Wert 1 angibst, wird der Dateiname des Parameters Content-Disposition 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.

 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 angegeben 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
 
{ 
   "documents":[ 
      { 
         "propertiesUri":"/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/document/6f53d725-f4f5-442e-a058-a01eaf05cbf5/properties",
         "sourceFilesUri":"/inbound/importprocess/fcc8c956-bfcb-4b30-bc09-9161f6f16eb2/stored/505d86b1-0a21-45f3-8b1f-80112138b497/sourcefiles",
         "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
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, die der Anwender importiert hat und aus denen das Dokument entstanden ist. Für bestimmte Prozesse müssen diese Dateien dauerhaft gespeichert werden.
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 Originalformat oder als PDF bereitgestellt wird. Je nachdem, welches Profil du verwendest, wird der jeweilige Standardwert verwendet. Der Wert 1 steht für das Originalformat, der Wert 2 für ein PDF.
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-Callback 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":"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.
importProcessnameName 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
 
{
    "userData": [
        {
            "key": "deleteBatchUserData",
            "values": [
                "notDelete"
            ]
        }
    ]
}

Hinweise zu den Eigenschaften

EigenschaftBeschreibung
keySchlüssel der Nachbearbeitungsoption.
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.