Die Documents Partner API by SEPTEO ist die Schnittstelle, über die eine Fremdanwendung auf das Dokumentenmanagement einer Kanzlei zugreifen kann, ohne dass diese einen Port nach außen öffnen muss.
Wie der Zugriff abläuft
Der Aufruf geht nicht direkt an das Dokumentenmanagement der Kanzlei, sondern nimmt diesen Weg:
- Die Partneranwendung ruft die Cloud-Schnittstelle über HTTPS auf und weist sich mit einem Zugriffstoken aus.
- Die Cloud prüft Lizenz und Berechtigungen und leitet den Auftrag über einen Nachrichtenvermittler an den Connector weiter, der im Netz der Kanzlei läuft.
- Der Connector führt den Auftrag im lokalen LEXolution.DMS aus und schickt das Ergebnis auf demselben Weg zurück.
Entscheidend dabei: Der Connector baut ausschließlich ausgehende Verbindungen auf (HTTPS und MQTT über WebSocket, jeweils Port 443). In der Firewall der Kanzlei muss nichts für eingehenden Verkehr geöffnet werden.
Wer im Dokumentenmanagement handelt
Die Sitzung im lokalen Dokumentenmanagement läuft im Namen
des anfragenden Benutzers. Dessen Kennung reist mit dem Auftrag
mit, und die Rechte, die dieser Benutzer im Dokumentenmanagement der
Kanzlei hat, entscheiden über jeden einzelnen Zugriff. Lehnt das
Dokumentenmanagement ab, meldet die Schnittstelle
403 ON_PREM_PERMISSION_DENIED zurück.
Die Kanzlei behält damit die Hoheit über ihre Berechtigungen: Was ein Benutzer im Dokumentenmanagement nicht darf, darf er auch über die Schnittstelle nicht.
Was die Schnittstelle heute kann
| Bereich | Funktion |
|---|---|
| Akten und Ordner finden | Suche über den Namen, das Aktenzeichen oder einen Suchbegriff, oder ein seitenweises Durchblättern ohne Filter |
| Inhalt | Alle Dokumente einer Akte oder eines Ordners auflisten |
| Register | Die Register einer Akte oder eines Ordners auflisten und die Dokumente eines einzelnen Registers abrufen |
| Dokumente | Ein Dokument hochladen, herunterladen oder in eine andere Akte bzw. einen anderen Ordner umlegen |
| Betriebszustand | Den Verbindungszustand des Connectors der eigenen Kanzlei abfragen |
Die Endpunkte im Einzelnen stehen in Endpunktübersicht.
Die Begriffe des Dokumentenmanagements
Diese Dokumentation verwendet dieselben Begriffe wie das Handbuch von LEXolution.DMS. Wer das Dokumentenmanagement kennt, findet sich damit sofort zurecht; die englischen Namen daneben sind die, die in der Schnittstelle selbst auftauchen.
| Begriff | Bedeutung | In der Schnittstelle |
|---|---|---|
| Akte | Die Sammlung, der Dokumente zugeordnet sind. Alle Dokumente einer Akte teilen sich deren Aktendaten. |
container, containerId
|
| Ordner | Wie eine Akte, aber ohne Aktenverweise – etwa eine Wissensbasis. | ebenfalls container
|
| Register | Die Untergliederung innerhalb einer Akte oder eines Ordners, in die Dokumente einsortiert werden. |
filing-tray, trayId
|
| Registerstruktur | Der gesamte Registerbaum einer Akte oder eines Ordners. | die Liste der filing-tray-Einträge |
| Dokument | Die einzelne Datei samt ihrer Dokumentdaten. |
document, documentId
|
| Aktenzeichen | Die fachliche Kennung einer Akte. | fileReference |
Akte und Ordner sind für die Schnittstelle dasselbe.
Beide erscheinen als container, werden über dieselben
Aufrufe gefunden und gelesen, und beide können eine Registerstruktur
tragen. Wo diese Dokumentation der Kürze halber „Akte“ schreibt, gilt
dasselbe für einen Ordner.
Dokumentinhalte laufen nicht über die Schnittstelle
Die eigentlichen Dateibytes reisen nie durch die Schnittstelle selbst. Stattdessen gilt:
- Hochladen – die Anwendung lässt sich eine zeitlich befristete Upload-Adresse geben, legt die Datei dort ab und meldet der Schnittstelle anschließend nur noch, dass dieses abgelegte Objekt importiert werden soll.
- Herunterladen – die Schnittstelle antwortet mit einer zeitlich befristeten Download-Adresse, von der die Anwendung die Datei abholt.
Das hält die Aufrufe klein und schnell und erlaubt beliebig große Dokumente. Der Ablauf ist in Schnellstart an einem vollständigen Beispiel gezeigt.
Voraussetzungen für eine Integration
| Voraussetzung | Erläuterung |
|---|---|
| Lizenz der Kanzlei | Die Kanzlei benötigt eine der beiden Lizenzvarianten – siehe Lizenzen und Berechtigungen. Was im Einzelfall gilt, regelt der Vertrag mit STP |
| Benutzerkonten mit der passenden Rolle | Die Partneranwendung handelt im Namen eines Benutzerkontos der Kanzlei. Ob das die Konten der einzelnen Anwender sind oder ein technisches Konto der Anwendung, ist eine Entscheidung – beide Modelle stehen in Erste Schritte |
| Installierter Connector | Der Connector muss auf einem Server der Kanzlei installiert, angemeldet und mit dem Dokumentenmanagement verbunden sein |
Dokumentation zum Dokumentenmanagement selbst
Diese Seiten beschreiben die Schnittstelle. Das Dokumentenmanagement dahinter hat seine eigene Dokumentation im STP Help Center:
| Was | Wofür |
|---|---|
| STP Documents – allgemein | Das Produkt selbst: Akten, Ordner, Register, Dokumente, Berechtigungen |
| Server-API-Übersicht | Die lokale Server-Schnittstelle des Dokumentenmanagements – dieselbe Funktionalität, die die Documents Partner API über die Cloud erreichbar macht |
Die Server-API-Übersicht lohnt sich besonders für Integratoren: Wer die lokale Schnittstelle bereits kennt, findet dort die Begriffe und Zusammenhänge wieder, auf denen die Documents Partner API aufsetzt.
Weiterführend
Für die Kanzlei:
- Erste Schritte – was nötig ist, um ein Partnerprodukt zu nutzen
- Lizenzen und Berechtigungen
- Rollen und Gruppen
Für alle, die selbst entwickeln:
- Eine eigene Anwendung anbinden – Registrierung, Anmeldung, erster Aufruf
- Schnellstart – die Aufrufe mit curl und C#
- Fehlercodes