REST-API
signoSign/Universal stellt eine REST-API zur Integration zur Verfügung. In diesem Kapitel wird weniger die technische Anwendung der API als eher das dahinterliegende Konzept erläutert.
Eine Auflistung aller verfügbaren API-Aufrufe samt Aufbau und Dokumentation ist aus der Swagger-UI zu entnehmen.
Die API ist in folgende Bereiche aufgeteilt:
Im weiteren Verlauf wird näher auf die einzelnen Bereiche eingegangen.
Allgemeines zum Verständnis
Diese technische Dokumentation erklärt die Begriffe und Sachverhalte im Zusammenhang mit Instance Tokens, Sessions, Containern, Viewern und Access URLs.
Instance Token:
Ein Instance Token ist eine eindeutige Zeichenkette, vergleichbar mit einem API-Key. Es muss bei jedem Aufruf eines geschützten REST-Endpoints als Autorisierungsmittel mitgegeben werden und fungiert als Zugangsschlüssel zu einem Container.
Container:
Ein Container beschreibt den Kontext eines Benutzers auf dem Server. Der Zugriff auf einen Container kann unabhängig von einer Session mithilfe des Instance Tokens erfolgen. In den meisten Fällen wird davon ausgegangen, dass ein einzelner Viewer in einem Container vorhanden ist, es ist jedoch auch möglich, mehrere Viewer in einem Container zu haben.
Session:
Eine Session beschreibt den Sitzungskontext eines Browsers mit dem Server. Sie repräsentiert die Interaktion eines Benutzers mit der Anwendung während eines bestimmten Zeitraums.
Viewer:
Viewer sind immer Bestandteil eines Containers. Sie bieten einen Kontext, in den ein Dokument geladen werden kann. In den meisten Anwendungsfällen wird davon ausgegangen, dass ein Container einen einzelnen Viewer enthält. Es besteht jedoch die Möglichkeit, dass ein Container potenziell mehrere Viewer enthält.
Laden eines Dokuments:
Ein Dokument wird immer in einen Viewer geladen. Das Dokument bleibt geladen, bis es aktiv entladen wird, das Instance Token widerrufen wird oder die assoziierte Session abläuft.
Ablauf der Session:
Eine Session hängt von dem in der web.xml festgelegten Timeout ab. Die Standardeinstellung ist 60 Minuten. Eine Ausnahme bilden externe Aufrufe von geteilten Dokumenten. Ihre Sitzung endet automatisch nach 10 Sekunden beim Verlassen des Viewers.
Access URL:
Eine Access URL ist eine einmalig verwendbare URL, die eine Session mit einem Viewer-Container verbindet. Sie wird immer für einen bestimmten Viewer ausgestellt. Durch das Aufrufen einer Access URL wird automatisch eine Verbindung zwischen der verwendeten Session und dem entsprechenden Viewer-Container hergestellt. Eine Access URL sollte unmittelbar vor der Verwendung erstellt werden, da sie nach Nutzung automatisch zerstört wird, um maximale Sicherheit zu gewährleisten.
Empfehlungen:
Ein Instance Token ist ein wichtiger Zugangsschlüssel zum Kontext eines Benutzers auf dem Server. Um einen reibungslosen und sicheren Betrieb zu gewährleisten, empfehlen wir die folgenden bewährten Vorgehensweisen im Umgang mit Instance Tokens:
Erstellung von Instance Tokens:
Ein Instance Token sollte immer für eine Session erstellt werden. Es ist ratsam, für jede Session ein Instance Token zu generieren, um eine klare Zuordnung zu ermöglichen.
Konsistente Zuordnung von Instance Tokens und Sessions:
Eine Session sollte nicht mit unterschiedlichen Instance Tokens verknüpft werden. Es ist wichtig, dass eine Session während ihrer Laufzeit immer nur ein Instance Token zur gleichen Zeit verwendet, um inkonsistente Zustände oder Zugriffsprobleme zu vermeiden.
Aktives Entladen von Dokumenten:
Nachdem ein Vorgang abgeschlossen wurde, sollten Dokumente aktiv entladen werden, um Ressourcen freizugeben und den Speicherverbrauch zu reduzieren. Dies kann entweder durch das manuelle Entladen des Dokuments oder durch das Widerrufen des zugehörigen Instance Tokens erfolgen.
Durch die Einhaltung dieser Empfehlungen können Sie eine konsistente und effiziente Nutzung von Instance Tokens gewährleisten und potenzielle Probleme im Zusammenhang mit der Sitzungsverwaltung und dem Laden von Dokumenten vermeiden.
Verwendung des Viewer
Das Konzept zur Verwendung des Viewer sieht vor, dass eine Instanz…
Generiert – Durch das Anfragen eines instancetoken.
Vorbereitet – Durch das Laden von Dokumenten oder das Vornehmen von Konfigurationen.
Aufgerufen – Durch das Anlegen und Aufrufen einer Zugriffs-URL.
Und Entsorgt wird – Durch das Zurückziehen des instancetoken.
Wird ein Viewer nicht durch das Zurückziehen des instancetoken entsorgt, kann das instancetoken und der dazugehörige Viewer weiterverwendet werden. In Multi-Viewer Szenarien sollten die Viewer bevorzugt von einem instancetoken erstellt werden, anstatt für jeden Viewer ein instancetoken zu generieren.
Vorbereiten des Viewer
Sobald ein Viewer instanziiert wurde, kann er konfiguriert und ein Dokument geladen werden. Die Vorbereitung kann in zwei Bereiche aufgeteilt werden:
Vorbereitung des Viewers selbst wie z. B.
Hinzufügen, Ändern und Löschen von Cookies für die Kommunikation mit fremden Systemen (z.B. Remote-Saving)
Vorbereitung eines geladenen Dokuments z. B.
Ein Viewer kann immer nur ein Dokument gleichzeitig geladen haben. Sobald ein weiteres Dokument geladen wird, wird das alte Dokument samt dokumentbezogener Einstellungen überschrieben.
Aufrufen des Viewer
Ein durch die API erzeugter Viewer ist ausschließlich über eine URL zugänglich, die mit einem Aufruf an die API abrufbar ist. Dabei handelt es sich um eine URL zu signoSign/Universal mit einer generierten Zeichenkette, die einen einmaligen autorisierten Zugriff auf den Viewer gewährt. Beim Aufruf wird die Session des aufrufenden Clients mit den Zugangsdaten eingeloggt, mit denen auch das instancetoken angefragt wurde. Der Client bleibt so lange eingeloggt, bis ein expliziter Logout durchgeführt oder das instancetoken zurückgezogen wird. Mit dem Aufruf der URL wird diese automatisch ungültig. Weiter ist zu beachten, dass beliebig viele URLs für eine Instanz angelegt werden können.
Eine Server Session kann beliebig viele Viewer eines instancetoken parallel öffnen. Die Viewer eines zweiten instancetoken können erst geöffnet werden, nachdem alle Viewer des ersten instancetoken geschlossen wurden.
Verwaltung persistierter Dokumente
Die API bietet die Möglichkeit in der konfigurierten Datenbank persistierte Dokumente zu verwalten. Dokumente der Datenbank können anhand ihrer numerischen ID direkt in den Viewer geladen werden.
Folgende Funktionen bietet die API hier:
Funktioniert nicht bei Verwendung einer eigenen Persistenzimplementierung.
Verwaltung geteilter Dokumente (Sharing Cases)
Auch die Verwaltung von geteilten Dokumenten ist über die API möglich.
Folgende Funktionen bietet die API hier:
Funktioniert nicht bei Verwendung einer eigenen Persistenzimplementierung.
Verwaltung von Keystores (Zertifikaten)
signoSign/Universal benötigt zwei verschiedene Zertifikate, ein Zertifikat für digitale Signaturen und ein Zertifikat für die Verschlüsselung von Biometriedaten. Diese Zertifikate müssen signoSign/Universal in Keystores zur Verfügung gestellt werden.
Das Konzept sieht hier zwei Schritte vor:
Hochladen eines Keystores, welcher die nötigen Zertifikate enthält
Zuweisung von Zertifikaten innerhalb eines Keystores mit einem bestimmten Zweck an einen Benutzer
Zertifikatszwecke:
Eine Zuweisung eines Zertifikats an einen Benutzer erfüllt immer einen bestimmten Zweck. Eine Zuweisung kann folgende Zwecke erfüllen:
SIGNING wird verwendet, um das Dokument digital zu signieren. Dies gewährleistet die Integrität des Dokuments. signoSign/Universal benötigt hier sowohl einen privaten Schlüssel als auch ein öffentliches Zertifikat.
ENCRYPTION wird verwendet, um die biometrischen Daten des Unterzeichners zu verschlüsseln. Dies gewährleistet die Nachvollziehbarkeit einer Unterschrift. signoSign/Universal benötigt hier nur ein öffentliches Zertifikat. Der dazugehörige private Schlüssel sollte separat an einem sicheren Ort verwahrt werden.
Folgende Funktionen bietet die API hier:
Sofern ein Benutzer keinerlei Zertifikatszuweisungen hat, legt signoSign/Universal selbst entsprechende Zertifikate an, wenn ein Zertifikat benötigt wird.
Funktioniert nicht bei Verwendung einer eigenen Persistenzimplementierung oder eines globalen Keystores.
Benutzerrollen und die ownerId
Einige Funktionen haben einen Parameter ownerId. Mit diesem Parameter lassen sich Funktionen im Namen dieses Benutzers ausführen. Zum Beispiel kann ein Benutzer A ein Dokument von Benutzer B herunterladen. Das ist aber nur möglich, wenn Benutzer A neben der Rolle ssu-user auch die Rolle ssu-admin hat.
Wird der Parameter ownerId leer gelassen, wird davon ausgegangen, dass es sich bei dem Wert um den Namen des Benutzers handelt, der die Anfrage durchführt. Übergibt ein Benutzer ohne die Rolle ssu-admin den Parameter und entspricht dieser nicht dem Namen des ausführenden Benutzer, so kommt es zu einem Zugriffsverstoß.
Abfrage detaillierter Informationen zu Dokumenten
Sobald ein Dokument in den Viewer geladen wurde, können Informationen über das Dokument abgefragt werden.
Verwendet wird hierfür die Ressource GET /viewer/document/information
Folgende Informationen sind abrufbar:
Allgemeine Informationen über das Dokument wie
Die Dokumenten ID
Die Anzahl aller Signaturfelder
Die Anzahl aller unterschriebenen Signaturfelder
Die Anzahl aller unterschriebenen Pflicht-Signaturfelder
Die Anzahl aller Formularfelder
Die Anzahl aller ausgefüllten Formularfelder
Die Anzahl aller ausgefüllten Pflicht-Formularfelder
Die Anzahl der Seiten
Information über alle Signaturfelder
Die HTML-ID, unter der das Signaturfeld im Viewer angezeigt wird
Die horizontale Position in Pixeln auf der Seite
Die vertikale Position in Pixeln auf der Seite
Die Breite in Pixeln
Die Höhe in Pixeln
Der Name des Signaturfeldes im PDF
Ein boolescher Wert, der aussagt, ob die Signatur obligatorisch ist
Ein boolescher Wert, der aussagt, ob das Feld im Viewer angezeigt wird
Gerenderte Bilder der Seiten als Base64 Strings
Den aktuellen Zustand des Dokuments als Binärdaten
Proprietäre HTTP Statuscodes
Die REST-API verwendet in Einzelfällen neben den Standard-Codes auch proprietäre Codes um die Behandlung von Sonderfällen zu ermöglichen.
Code | Nachricht | Bedeutung |
|---|---|---|
599 | Conflict Configuration | Die Anfrage kann nicht verarbeitet werden, weil sie in Konflikt mit den Servereinstellungen steht bzw. die benötigte Funktionalität nicht ausreichend konfiguriert ist. |
Verwaltung von Workflows
signoSign/Universal bietet mit der REST-API Ressource Workflows die Möglichkeit Abläufe zu automatisieren. Ein Ablauf und die darin verwendeten Daten werden in einer Vorlage (Blueprint) festgelegt, die anschließend beliebig oft gestartet werden kann.
Blueprints
Ein Blueprint definiert einen kompletten Ablauf und die damit verarbeitet Daten. Ein neu erstellter Workflow ist leer und muss mit Schritten (Steps) gefüllt werden. Anschließend kann der Blueprint gestartet werden. Jeder Start erzeugt einen Prozess. Nachträgliche Änderungen am Blueprint haben keine Auswirkungen auf die Prozesse.
Das Löschen eines Blueprints löscht die Schritte und alle Prozesse. Blueprints, die mit einem aktiven Prozess verknüpft sind, können nicht gelöscht werden.
Blueprint Steps
Die Blueprint Steps definieren welche Aktionen in welcher Reihenfolge ausgeführt werden. Schritte können sequenziell, parallel oder in einer Mischung beider Varianten ausgeführt werden.
Aktionen
Bei der Erstellung eines Schrittes wird durch dessen Typ die Art der Aktion festgelegt. Für jeden Typ bietet die REST-API einen Endpoint.
DEMAND_SIGNATURE
Eine Dokumentenmappe wird per E-Mail geteilt. Die Dokumente können über einen Link in der E-Mail im signoSign/Universal Viewer geöffnet und unterschrieben werden.
POST /workflows/blueprints/{blueprintId}/steps/demandSignature
POST /workflows/blueprints/steps/{stepId}/demandSignature/documents
Reihenfolge
Die Start-Reihenfolge der Workflow Steps wird über Indezes festgelegt. Jeder Step enthält ein Attribut stepIndex und nextStepIndex.
stepIndex
Das stepIndex Attribut legt fest, wann der Schritt ausgeführt wird. Ein Index kann von mehreren oder allen Steps verwendet werden. Die Liste der Indizes aller Schritte zusammen muss bei 1 beginnen und lückenlos sein (1, 2, 3, ...), ansonsten kann der Blueprint nicht gestartet werden.nextStepIndex
Das nextStepIndex Attribut legt fest, dass die Steps mit diesem stepIndex danach ausgeführt werden sollen. Ein Step mit stepIndex == N wird erst ausgeführt, wenn alle Steps mit nextStepIndex == N abgeschlossen sind. Steps, die durch kein nextStepIndex Attribut blockiert werden, werden beim Start des Blueprints gestartet.
Dokumentenmappen
Workflow Steps sind über Mappen (DocumentFolder) mit Dokumenten verknüpft. Eine Mappe kann beliebig viele Dokumente enthalten, ein Dokument kann nur mit einer Mappe verknüpft sein.
Standardmäßig wird für jeden Step, der Dokumente verarbeitet, eine leere Mappe erzeugt. Wenn dem Step ein Dokument zugeordnet wird, wird eine Kopie des Dokuments in der Mappe abgelegt. Wenn zwei Steps die selben Dokumente verarbeiten sollen, müssen sie die selbe Mappe verwenden. Die Mappe kann entweder bei der Erstellung des Steps festgelegt werden oder nachträglich beim Verknüpfen mit dem Dokument. Jeweils mit dem Parameter documentFolderId.
Prozesse
Ein Workflow Prozess repräsentiert einen gestarteten Blueprint. Für jeden Blueprint Step enthält der Prozess ein Event mit einer Kopie der Arbeitsdaten des Blueprint Steps. Nachträgliche Änderungen am Blueprint wirken sich nicht auf den Prozess oder dessen Events aus.
Mit der REST-API können Prozesse gestartet, abgefragt und gelöscht werden. Das Löschen entfernt den Prozess und dessen Events inkl. der Arbeitsdaten wie bspw. die Dokumente. Aktive Prozesse können nicht gelöscht werden.