Übersicht

signoSign/Universal ist eine Webanwendung zum Anzeigen, Bearbeiten und Signieren von PDF-Dokumenten und kann flexibel von jedem Endgerät aus genutzt werden. Für einfache Anwendungsfälle stehen Apps für Android, iOS und Windows sowie die Webanwendung „signoSign/Universal Dokumentenpool“ zur Verfügung, mit denen die Anwendung ohne Integrationsaufwände verwendet werden kann. Bei komplexeren Anwendungsfällen kann die Anwendung über verschiedene Schnittstellen nahtlos in bestehende Systeme integriert werden.

Diese Dokumentation beschreibt die technischen Integrationsmöglichkeiten sowie die verfügbaren Programmierschnittstellen.

Architektur

signoSign/Universal besteht aus einem Frontend, welches dem Anwender in einem Browser oder einer der signoSign/Universal Apps auf dem Client angezeigt wird, und einem Backend, in dem die Verarbeitung der Dokumente auf einem Java-Server Server geschieht. Sowohl auf die Datenbank als auch auf die in der Session gespeicherten Daten kann über einen REST Webservice zugegriffen werden.

Als vorkonfigurierte Datenbank wird H2 verwendet. Es wird empfohlen, je nach Anwendungsszenario in produktiven Umgebungen eine andere Datenbank zu konfigurieren.

Konfiguration

signoSign/Universal kann sowohl statisch über Properties-Dateien, Umgebungs- und Systemvariablen als auch zum Teil dynamisch über einen REST Webservice konfiguriert werden. Die genaue Beschreibung der Konfiguration ist im Kapitel Konfigurationsparameter zu finden.

Schnittstellen

signoSign/Universal bietet umfangreiche Schnittstellen für verschiedene Technologien. Nachfolgend ein kurzer Überblick über die vorhandenen Schnittstellen und deren typischen Einsatzzwecke.

REST Webservice

Der REST Webservice ist die Basis für die Integration von signoSign/Universal und muss in jedem Fall verwendet werden, um eine Viewer-Instanz zu erzeugen, ein Dokument zu laden und die URL des Viewers abzufragen, um ihn in einem Browser oder einer Webview zur Anzeige zu bringen. Zusätzlich können das Aussehen und das Verhalten der Viewer-Instanz konfiguriert werden.

Darüberhinaus bietet der Webservice Funktionen zum Zugriff auf die konfigurierte Datenbank.

Über den Webservice ist eine flexible Integration mit nahezu allen Programmiersprachen möglich. signoSign/Universal benötigt keine direkte Verbindung zu anderen Systemen, der gesamte Datenaustausch geschieht über Webschnittstellen.

Austausch von Dokumenten mit fremden Systemen

Über den REST Webservice kann eine URL konfiguriert werden, über die signoSign/Universal ein Dokument in die Viewer-Instanz laden kann, sowie eine URL, zu der signoSign/Universal ein bearbeitetes Dokument beim Speichern hochladen kann. Dies kann benötigt werden, wenn der REST-Client keinen Zugriff auf die Dokumente hat, weil sie auf einem fremden System erstellt und weiterverarbeitet werden sollen. Hierbei können Cookies gesetzt werden, über die signoSign/Universal Anwendungsinformationen wie z. B. eine Autorisierung mitgeben kann.

Weitere Informationen sind in Kapitel "Kommunikation mit fremden Systemen" zu finden.

JavaScript-Funktionen und -Events

Das Frontend bietet verschiedene JavaScript-Funktionen, über die der Viewer programmatisch gesteuert werden kann, wenn er über ein iFrame in eine andere Webanwendung eingebettet wird. Damit kann z. B. das Unterschreiben gestartet oder das Speichern ausgelöst werden. Außerdem kann die umgebende Anwendung über bestimmte Ereignisse informiert werden und darauf reagieren.

Das Besondere an einer Integration über ein iFrame ist, dass die umgebende Anwendung geblockt werden kann und dass sie die Kontrolle behält, bis die Arbeit in signoSign/Universal beendet ist.

Protokolle

signoSign/Universal bietet eine Protokollierung für Dokumente und Workflows. In den Protokollen werden diverse Informationen über Veränderungen im Dokument oder Workflow protokolliert. Diese Informationen bleiben unabhängig von dem Dokument oder Workflow in der Datenbank gespeichert. Die Protokolle für die Dokumente und Workflows können über die REST-API abgerufen werden.

Benutzerverwaltung

Die Verwaltung der Benutzer erfolgt nicht direkt innerhalb der Anwendung selbst, sondern es stehen zwei verschiedene Ansätze zur Verfügung.

Der erste Ansatz besteht darin, OIDC (OpenID Connect) in der Anwendung zu konfigurieren. Dadurch werden die Benutzer über den entsprechenden Anbieter verwaltet. Hierbei werden die Benutzerrollen und -berechtigungen beim externen Identity Provider festgelegt.

Alternativ dazu können die Benutzer über den Security-Realm des Servers bereitgestellt werden. Dabei werden die Benutzerinformationen und Zugriffsrechte direkt auf dem Server verwaltet. In beiden Fällen müssen den Benutzern geeignete Rollen zugewiesen werden, um die Anwendung nutzen zu dürfen.

Für die Benutzerverwaltung stehen die REST-Ressource Users bzw. User zur Verfügung. Mithilfe dieser Ressource können verschiedene Aktionen durchgeführt werden, wie beispielsweise das Ändern der Benutzereinstellungen oder das Abrufen von Daten, die für den Betrieb der Anwendung notwendig sind. Es besteht auch die Möglichkeit, Benutzer zu löschen. Dabei ist zu beachten, dass das Löschen eines Benutzers lediglich den Benutzeraccount zurücksetzt und nicht verhindert, dass der Benutzer weiterhin die Anwendung nutzen kann.

Lizenzierung

Standardmäßig wird signoSign/Universal ohne eingetragenen Lizenzschlüssel ausgeliefert. In diesem Zustand lässt sich die Anwendung im Funktionsumfang uneingeschränkt nutzen, jedoch werden sowohl alle Signaturbilder als auch gerenderte Seiten mit einem Wasserzeichen versehen.

• Der Maschinenname
• Die maximale Anzahl der verwendeten Prozessorkerne
• Die Anzahl gleichzeitiger Benutzung des Viewers

Schlägt die Prüfung der Lizenz fehl oder es ist kein gültiger Lizenzschlüssel hinterlegt, kommt es beim Öffnen eines Dokuments in signoSign/Universal zu einer entsprechenden Fehlermeldung. Dieses Verhalten soll verhindern, dass die Anwendung versehentlich im Demo-Modus verwendet wird.

Ein Lizenzschlüssel kann in der settings.properties-Datei, als Java-System-Property oder als Umgebungsvariable gesetzt werden.

Lizenzmerkmal Maschinenname

Der in die Lizenz eingetragene Computername wird abgeglichen mit dem Ergebnis der Java-Funktion InetAddress.getLocalHost().getHostName() .

Lizenzmerkmal Prozessorkerne

Die in der Lizenz eingetragene Anzahl an verwendeten Prozessorkerne darf nicht geringer sein als die tatsächlich verwendete Anzahl an Kernen des betreibenden Servers.

Lizenzmerkmal gleichzeitige Benutzung des Viewers

Die in der Lizenz eingetragene Anzahl gleichzeitiger Benutzungen bezieht sich ausschließlich auf die Anzeige von Dokumenten im Viewer. Der Zugriff auf Datenbestände oder Ressourcen der Webservice-Schnittstelle fällt nicht unter gleichzeitiger Benutzung des Viewers.

Konfigurationsparameter

Die globalen Servereinstellungen werden in einer Standard Java Properties-Datei festgelegt. Die Anwendung enthält eine Datei mit Standardeinstellungen, die entweder direkt bearbeitet oder durch eine externe Properties-Datei überladen werden kann. Änderungen an den Einstellungen werden erst nach einem Neustart der Anwendung wirksam.

[WEB-APP-ROOT]/WEB-INF/classes/settings.properties
[WEB-APP-ROOT]/ssu_web-x.x.x.x.war/WEB-INF/classes/settings.properties

Dieses Kapitel beschreibt die möglichen Einstellungen in der Properties-Datei und wie diese Einstellungen festgelegt werden können.

Umgebungs- und Systemvariablen

Jede Einstellung aus der Properties-Datei kann auch durch Java System-Properties und Umgebungsvariablen festgelegt/überschrieben werden. Die Punkte in den Variablennamen können optional durch Unterstriche ersetzt werden.

Format:
signotec.ssu. [EINSTELLUNG]

• export signotec_ssu_business_licenseKey=myLicenseKey
• set signotec.ssu.business.licenseKey=myLicenseKey
• -Dsignotec.ssu.business.licenseKey=myLicenseKey

• Umgebungsvariablen mit Punkten sind nicht in jedem Betriebssystem erlaubt. Wir empfehlen, pauschal alle Punkte durch Unterstriche zu ersetzen. signotec.ssu.business.licenseKey - > signotec_ssu_business_licenseKey
• Es wird empfohlen, die Java System-Properties zu verwenden, weil sich der Abruf der Umgebungsvariablen auf verschiedenen Java-Servern voneinander unterscheiden kann.

Konfiguration auslagern

Um die zukünftige Wartung der Anwendung zu vereinfachen, sollten die Einstellungen getrennt von der Webanwendung gespeichert werden. Anstatt die Standardeinstellungen im Auslieferungspaket zu bearbeiten, sollten benutzerdefinierte Einstellungen in einer externen Properties-Datei festgelegt werden. Machen Sie eine Kopie der Standardeinstellungen und legen Sie mit der Variable „signotec_ssu_externalpropertiesfile“ den Speicherort der Kopie fest.

export signotec_ssu_externalpropertiesfile=/myConfigFolder/ssu/settings.properties

Beim Start wird signoSign/Universal erst die Standardeinstellungen laden und diese anschließend mit den externen Einstellungen erweitern/überschreiben.

Einstellungen web

Folgende Einstellungen sind in der settings.properties mit dem Präfix "web." möglich.

ssmPublicUrl

Beschreibt die öffentliche URL der signoSign/Universal Anwendung. Sie wird verwendet um Access-Urls zur Anwendung zu generieren. Bspw. für Links in Benachrichtigungs-Mails der Workflows.

ssmInternalUrl

Diese Eigenschaft definiert eine URL, unter der die signoSign/Universal-Anwendung vom Server aus erreichbar ist. Diese URL wird insbesondere für REST-Aufrufe verwendet, die nicht über eine öffentliche Schnittstelle aufgerufen werden müssen. Sie reduziert den öffentlichen Verkehr und erleichtert den Lastausgleich.

showLeaveUnchangedDialog

Diese Einstellung bestimmt, ob beim Verlassen eines unveränderten Dokumentes ein Dialog angezeigt wird, der den Benutzer darauf hinweist, dass keine Änderungen am Dokument vorgenommen wurden.

supportedCaptureInput

Diese Einstellung definiert eine Liste von erlaubten Eingabetypen für die Signatur. Bei der Erfassung wird geprüft, ob der verwendete Eingabetyp in der Liste enthalten ist. Ist der Eingabetyp nicht enthalten, wird die Erfassung mit einem Hinweis über die gültigen Eingabetypen abgebrochen.

signatureFieldsOrderMode

Diese Einstellung bestimmt, in welcher Reihenfolge die Signaturfelder im Viewer abgesprungen werden, wenn das Unterschreiben aller Felder durch Klick auf die Unterschreiben-Button gestartet oder der Signaturprozess durch die Einstellung automatedSignStartMode gestartet wird.

hardwarePadsOnly

Diese Einstellung bestimmt, ob ausschließlich mit Signaturpads oder auch mit der Maus oder einem Touchgerät unterschrieben werden kann. Wird diese Option aktiviert und es wird kein Signaturgerät erkannt, werden sämtliche Signaturfelder im Dokument ausgeblendet. Bei Verwendung der signoSign/Universal-Apps wird diese Option ignoriert.

disableMouseSignature

Diese Einstellung entscheidet darüber, ob Unterschriften mit dem Mauszeiger unterdrückt werden.

serialPadSearchType

Diese Einstellung bestimmt, ob und an welchen Ports des Client-Geräts nach seriellen Pads gesucht wird. Standardmäßig wird nicht nach seriellen Geräten gesucht.

wssDomainPort

Diese Einstellung bestimmt den Domain-Namen und den Port unter dem der WebSocket der signoPAD-API/Web angesprochen wird. Die Einstellung wird ignoriert, wenn das Add-On für den Internet Explorer (ActiveX Pad Server) verwendet wird. Weitere Informationen hierzu finden Sie in der Dokumentation der signoPAD-API/Web.

signatureColor

Diese Einstellung bestimmt die Strichfarbe der Unterschrift.

photoAllowedInApp

Über die signoSign/Universal-Apps können Signaturen zusammen mit einem Foto in ein Dokument eingebracht werden. Diese Einstellung entscheidet darüber, ob diese Option während des Signaturprozessen zur Verfügung steht.

logoutUrl

Beim Logout-Vorgang (signoSign/Universal Logout Button) versucht der Server den Client in folgender Reihenfolge zu mehreren URLs umzuleiten. Zuerst wird die URL, die mit dem Request-Parameter referer beim Laden des Dokumentes gesendet wurde verwendet. Wurde kein referer übergeben, wird zur Logout-URL weitergeleitet.

Sichtbarkeit der Toolbar-Buttons

Für viele Toolbar-Buttons kann die Sichtbarkeit eingestellt werden. Es kann eingestellt werden, ob ein Button sichtbar ist, ob er nur im Untermenü angezeigt wird, ob er abhängig vom verfügbaren Platz in der Kopfzeile angezeigt wird oder ob er priorisiert in der Kopfzeile angezeigt werden soll, was bedeutet, dass dieser Button als letztes in das Untermenü verschoben wird.

saveBeforeExport

Diese Einstellung bestimmt, ob vor dem Exportieren eines Dokuments aus dem Viewer heraus (durch betätigen des Exportieren-Buttons) der Speicherprozess durchgeführt wird oder nicht. Alle weiteren Einstellungen, die den Speicherprozess beeinflussen wie etwa saveImportedDocuments werden hierfür berücksichtigt.

saveImportedDocuments

Diese Einstellung entscheidet darüber, ob Dokumente, die nicht aus der Persistenz geladen wurden, beim Speicherprozess persistiert werden. Wird eine URL zum entfernten Speichern definiert, wird diese auch immer verwendet.

signPadDocumentView

Entscheidet darüber, ob beim Erfassen einer Unterschrift mit einem Signiergerät ein Ausschnitt des Dokuments um die Signatur herum dargestellt wird. (s.a. signPadDocumentViewScalingFactor, signPadDocumentViewMarginLeft und signPadDocumentViewMarginTop)

signPadDocumentViewScalingFactor

Diese Einstellung stellt den Skalierungsfaktor für den Dokumentenausschnitt auf dem Signaturgerät ein. Es ist ein Integer-Wert, der die Skalierung in Prozent angibt.

signPadDocumentViewMarginLeft

Diese Einstellung stellt den linken Rand des Unterschriftenfeldes im Dokumentenausschnitt dar. Je größer der Wert, desto mehr Abstand hat das Feld zum linken Rand.

signPadDocumentViewMarginTop

Diese Einstellung stellt den oberen Rand des Unterschriftenfeldes im Dokumentenausschnitt dar. Je größer der Wert, desto größer wird der Abstand zum oberen Rand.

autoShowDocumentOnPad

Die Einstellung bestimmt, ob beim Öffnen des Viewers automatisch die Dokumentenanzeige auf dem Signaturgerät gestartet werden soll. Der Autostart wird nur ausgeführt, wenn ein signotec Delta Gerät gefunden wurde und die signoPAD-API/Web auf dem Client installiert ist. Standardmäßig ist diese Funktion aktiviert.

clientDebugLogging

Diese Einstellung aktiviert die clientseitige Debug-Protokollierung über JavaScript. Alle Ausgaben werden zur Information in die Browserkonsole geschrieben. Es wird empfohlen, diese Option im produktiven Betrieb zugunsten der Leistung zu deaktivieren.

idleTimeout

Diese Einstellung legt den Zeitraum fest, nach dem ein geladenes Dokuments eines Benutzers durch den Server geschlossen wird.

Zulässige Werte:
Alle positiven Integer -werte, wobei 0 bedeutet, dass das Timeout deaktiviert ist.

captureBiometricData

Diese Einstellung aktiviert die Erfassung der biometrischen Daten bei der Unterschriftenerfassung. Wenn diese Funktion aktiviert ist, werden zusätzliche Eigenschaften der Unterschrift wie z. B. der zeitliche Ablauf und Stiftdruck erfasst.

mockMode

Im Mock-Mode werden gestartete Unterschriften umgehend mit zufällig generierten Punkten bestätigt. Die Verwendung von Signatur-Pads ist in diesem Modus deaktiviert, jedoch wird in der Anwendung die gleiche Sequenz von Events ausgelöst, wie wenn ein Signaturgerät angeschlossen ist. Darüber hinaus werden alle Formularfelder in diesem Prozess mit dem Wert 1 befüllt, um Konflikte mit Pflichtfeldern zu vermeiden.

padCertificationAuthorities

Mit dieser Einstellung kann eine PEM-Datei festgelegt werden, die eine oder mehrere Zertifikatketten von Zertifizierungsstellen enthält. Die Reihenfolge der Zertifikate in der Datei kann frei gewählt werden. Wenn eine Datei festgelegt ist, wird signoSign/Universal prüfen, ob das im Signaturgerät gespeicherte Signaturzertifikat von einem der enthaltenen Zertifikate signiert wurde. Ist dies nicht der Fall, können keine Unterschriften erfasst werden. Diese Funktion ist standardmäßig deaktiviert.

Diese Einstellung dient als Gewährleistung, dass nur Signiergeräte mit bekannten Signaturzertifikaten genutzt werden können.

legacySignatureImage

Die Einstellung legt fest, ob bei der Erfassung einer Signatur über die signoPAD-API/Web eine Raster- oder Vektorgrafik erzeugt und in das PDF eingebunden wird.

accentColor

Diese Einstellung legt die Akzentfarbe für den Dokumentenpool, den Viewer und durch den Server versandte E-Mails fest.

favicon

Diese Einstellung legt das Favicon für den Dokumentenpool und den Viewer fest.

logo

Diese Einstellung legt das Logo für den Dokumentenpool und durch den Server versandte E-Mails fest.

dynamicSignatureStrokes

Legt fest, ob Signaturen mit einer dynamischen oder konstanten Strichstärke erfasst werden.

web.proposeNewViewer

Die Einstellung regelt die Option für den Benutzer, beim Öffnen des Viewers eine experimentelle Variante des Viewers auszuprobieren, die sich derzeit in einer Testphase befindet.

Einstellungen business

Folgende Einstellungen sind in der settings.properties mit dem Präfix "business." möglich.

licenseKey

Hier kann der Lizenzschlüssel für signoSign/Universal eingetragen werden. Bitte ändern Sie diesen Wert nur nach Absprache mit signotec. Mit einem ungültigen Lizenzschlüssel kann die Anwendung nicht genutzt werden. Wenn kein Schlüssel angegeben ist, läuft die Anwendung im Evaluationsmodus.

Einstellungen persistence

Folgende Einstellungen sind in der settings.properties mit dem Präfix "persistence." möglich.

pathToDocumentConfigFile

Der Speicherort der Dokumententypen.

referrerUrl

Diese Einstellung legt die URL fest, zu der weitergeleitet wird, wenn im Viewer auf den Zurück-Button geklickt wird. Wird keine URL zum Zurückkehren definiert, wird der Zurück-Button nicht angezeigt. Beim Aufrufen der URL werden zwei Parameter angehängt.

useDocumentLocking

Die Einstellung entscheidet darüber, ob ein Dokument mehrmals gleichzeitig geöffnet werden kann. Standardmäßig ist diese Funktion deaktiviert.

formFieldProtectMode

Diese Einstellung steuert, welche Formularfelder beim Erfassen einer Unterschrift gesperrt werden bzw. als schreibgeschützt markiert werden. Unterschriftenfelder werden von dieser Funktion niemals gesperrt und bereits gesperrte Formularfelder werden niemals entsperrt.

Unabhängig von dieser Funktion werden Formular- und Signaturfelder, die im „signature field lock dictionary“ eines PDF-Signaturfeldes festgelegt sind, immer gesperrt.

signatureFieldAddingAllowed

Diese Einstellung bestimmt, ob das manuelle Hinzufügen von Signaturfeldern erlaubt ist. Standardmäßig ist diese Funktion aktiviert.

signatureBackgroundTransparent

Dieser Wert stellt ein, ob der Hintergrund des gerenderten Signaturbildes, welches im Dokument angezeigt wird, transparent ist.

signatureTextEnabled

Diese Einstellung bestimmt, ob der Signaturtext, wie z. B. der Zeitstempel (siehe persistence.signatureText) in das Bild der Unterschrift eingefügt und im Dokument sichtbar sein soll.

signatureText

Diese Einstellung kann einen beliebigen Text enthalten, der beim Unterschreiben zusätzlich zur Unterschrift in das Signaturfeld eingebracht wird. Als Platzhalter können @SIGNTIME und @LOCATION eingebracht werden, die durch reale Werte ersetzt werden.

Wenn die Einstellung leer gelassen wird, wird ein voreingestellter Zeitstempel in einem voreingestellten Format erzeugt, das der Spracheinstellung des aufrufenden Browsers entspricht.

signatureTextDateTimeFormat

Mit dieser Einstellung wird das Zeitstempelformat gesetzt, mit der @SIGNTIME in signatureText ersetzt wird, falls enthalten. Der Format-String muss den Regeln von Java SimpleDateFormat entsprechen.

signatureTextHorizontalAlign

Jedes Signaturfeld kann mit einem Signaturtext versehen werden. Über diese Einstellungen lässt sich die Ausrichtung des Textes definieren.

signatureTextVerticalAlign

Jedes Signaturfeld kann mit einem Signaturtext versehen werden. Über diese Einstellungen lässt sich die Ausrichtung des Textes definieren.

documentSharing

Diese Einstellung bestimmt, ob die Funktion zum Teilen von Dokumenten aktiviert ist. Wenn die Funktion deaktiviert ist, wird der Toolbar-Button deaktiviert/ausgegraut. Die Sichtbarkeit des Toolbar-Buttons wird mit web.sharingButtonVisibility eingestellt.

documentSharingEditablePassword

Diese Einstellung bestimmt, ob das Passwort eines geteilten Dokumentes vor dem Durchführen des Vorgangs bearbeitet werden kann. Standardmäßig ist diese Funktion aktiviert.

automatedSignStartMode

Mit dieser Eigenschaft lässt sich einstellen, ob und wie die Unterschriftenerfassung automatisch beim Öffnen eines Dokumentes gestartet wird.

automatedSaveMode

Mit dieser Eigenschaft lässt sich einstellen, ob und wann ein Dokument automatisch gespeichert wird.

allowSignfieldSelection

Diese Einstellung bestimmt, ob die Unterschriftenerfassung für ein Unterschriftenfeld durch Klick auf das Signaturfeld gestartet werden kann. Wenn die Funktion deaktiviert ist, können die Unterschriften nur in der vorgegebenen Reihenfolge geleistet werden, indem der "Unterschreiben"-Button genutzt wird.

usePadEncryption

Diese Einstellung steuert, ob die erfassten Daten einer Unterschrift im signotec Signiergerät oder im Backend der Webanwendung verschlüsselt werden. Sie wirkt sich also nur auf die Signatur mit Signiergeräten aus.

Zertifikate

signoSign/Universal benötigt jeweils ein Zertifikat für die Verschlüsselung der Unterschrift und einen Zertifikat mit privaten Schlüssel für die Signierung des Dokuments. Siehe auch Kapitel Zertifikate. Die Verschlüsselung im Signiergerät wird mit der Einstellung persistence.usePadEncryption gesteuert.

Hinweis
Zur Verschlüsselung der biometrischen Daten wird signoSign/Universal standardmäßig mit einem Zertifikat ausgeliefert, welches von einem Notar erstellt und verwaltet wird. Dies bietet höchstmögliche Sicherheit im Umgang mit den sensiblen Unterschriftsdaten, ohne dass Sie sich mit der Schlüsselverwaltung beschäftigen müssen. Im Streitfall kann die Entschlüsselung der Biometrie beim Notar beauftragt werden. Insofern Sie die Zertifikate lieber selbst verwalten möchten, denken Sie daran, die Konfiguration entsprechend anzupassen, bevor Sie das System produktiv nutzen. Mehr Informationen erhalten Sie direkt beim Vertriebsteam von signotec.
Das Dokument wird standardmäßig mit einem Demo-Zertifikat digital signiert, welches für den produktiven Einsatz durch ein vertrauenswürdiges Zertifikat ersetzt werden muss. Siehe auch Kapitel Globale Zertifikate.

useCertificateDataProperties

Diese Einstellung bestimmt, ob global ein Verschlüsselungszertifikat und ein Signierungszertifikat für alle Benutzer verwendet werden soll bzw. ob die Zertifikate aus einem zentralen Schlüsselspeicher geladen werden.

keystoreBiometric

Einstellung zum Festlegen des absoluten Speicherorts des Schlüsselspeichers, aus dem das Verschlüsselungszertifikat geladen wird.

biometricKeyStoreType

Einstellung zum Festlegen des Typs des Schlüsselspeichers wie JKS , PKCS12 , WINDOWS-MY usw. Der Standardwert ist der JRE-Standardtyp JKS oder der mit dem System-Property keystore.type festgelegte Typ.

biometricKeyStorePassword

Einstellung zum Festlegen des Kennworts für den Schlüsselspeicher. Verwenden Sie einen leeren Wert, wenn der Keystore-Implementierung ein Kennwortparameter null beim Aufruf der KeyStore.load() Methode übergeben werden muss.

biometricAlias

Einstellung für den Alias des Verschlüsselungszertifikats im Schlüsselspeicher.

keystoreSigning

Einstellung zum Festlegen des absoluten Speicherorts des Schlüsselspeichers, aus dem das Signierungszertifikat und der private Schlüssel geladen werden.

signingKeyStoreType

Einstellung zum Festlegen des Typs des Schlüsselspeichers wie JKS , PKCS12 , WINDOWS-MY usw. Der Standardwert ist der JRE-Standardtyp JKS oder der mit dem System-Property keystore.type festgelegte Typ.

signingKeyStorePassword

Einstellung zum Festlegen des Kennworts für den Schlüsselspeicher. Verwenden Sie einen leeren Wert, wenn der Keystore -Implementierung ein Kennwortparameter null beim Aufruf der KeyStore.load() Methode übergeben werden muss.

signingAlias

Einstellung zum Festlegen des Alias des Signierungszertifikats und des privaten Schlüssels im Schlüsselspeicher.

signingPrivateKeyPassword

Einstellung zum Festlegen des Kennworts für den privaten Schlüssel im Schlüsselspeicher. Verwenden Sie einen leeren Wert, wenn für der Keystore-Implementierung ein Kennwortparameter null beim Aufruf der KeyStore.load() Methode übergeben werden muss.

Passwörter

Die folgenden Einstellungen stehen für die individuelle Einstellung der gewünschten Passwortrichtline zur Verfügung.

passwords.length

Einstellung zum Festlegen der Mindest-Passwortlänge für eingegebene Passwörter

passwords.requireDigit

Diese Einstellung bestimmt, ob Passwörter Zahlen beinhalten müssen.

passwords.requireUppercase

Diese Einstellung bestimmt, ob Passwörter Großbuchstaben enthalten müssen.

passwords.requireLowercase

Diese Einstellung bestimmt, ob Passwörter Kleinbuchstaben enthalten müssen.

passwords.requireSpecial

Diese Einstellung bestimmt, ob Passwörter Sonderzeichen enthalten müssen.

passwords.allowedSpecialCharacters

Einstellung zum Festlegen der erlaubten Sonderzeichen.

allowedAuthenticationMethods

Einstellung zum Festlegen der erlaubten Authentifizierungsmethoden.

mailTemplatesLocation

Einstellung zum Festlegen des Verzeichnis der Mail Templates.

Einstellungen hibernate

Im Abschnitt hibernate der settings.properties wird die Datenbankverbindung festgelegt. Wenn keine benutzerdefinierte Datenbank konfiguriert wird, startet signoSign/Universal eine H2 Datenbank. Der Speicherort der Datenbank hängt von der Einstellung hibernate.connectionUrl ab.

connectionDriverClassName

Die JDBC-Treiberklasse. Wird für das Hibernate Property hibernate.connection.driver_class verwendet.

connectionUrl

Die JDBC-URL zur Datenbankinstanz. Wird für die hibernate-Einstellung hibernate.connection.url verwendet.

dialect

Mit dieser Eigenschaft generiert Hibernate das entsprechende SQL für die ausgewählte Datenbank. Wird für das Hibernate Property “hibernate.dialect” verwendet.

connectionUsername

Der Datenbank-Benutzername. Wird für das Hibernate Property “hibernate.connection.username” verwendet.

connectionPassword

Das Datenbankkennwort. Wird für das Hibernate Property “hibernate.connection.password” verwendet.

Einstellungen deployment

Diese Einstellungen betrifft die Bereitstellung zusätzlicher Funktionen durch signoSign/Universal.

Folgende Einstellungen sind in der settings.properties mit dem Präfix "deployment." möglich.

devTools

Dabei handelt es sich um ein boolesches Flag, das entscheidet, ob signoSign/Universal zusätzlich folgenden Inhalte bereitstellt:

• REST-API Showcase
• REST-API Swagger-UI
• Prozess Debug-Seite

pool

Entscheidet, ob signoSign/Universal ein Frontend zur Verwaltung von Dokumenten bereitstellt. Bei laufendem Server ist die Pool-Anwendung unter ../signoSignUniversal/pool zu finden

Einstellungen restapi

Diese Einstellungen betreffen die bereitgestellte REST-API.

Folgende Einstellungen sind in der settings.properties mit dem Präfix "restapi." möglich.

whiteList

Eine Liste von Hostnamen oder IP-Adressen, denen der Zugriff auf die REST-API gewährt wird. Das Asterisks-Symbol (*) dient hier als Wildcard-Zeichen.

Einstellungen smtp

Diese Einstellungen betreffen den Versand von E-Mails. SignoSign/Universal verwendet hierzu die Javamail-API.

host

Der Hostname des zu verwendenen SMTP-Servers.

user

Zu verwendender Benutzername zum SMTP-Servers.

password

Zu verwendendes Password zum SMTP-Servers.

userDisplayName

Der Anzeigename der in einer E-Mail als Absender anstatt der E-Mail-Adresse angezeigt wird.

auth

Bestimmt, ob sich die Javamail-API mithilfe des AUTH-Befehls authentifiziert.

startTlsEnable

Bestimmt, ob vor der Übertragung von Login-Daten eine TLS-geschützte Verbindung aufgebaut wird.

port

Der Port, welcher für SMTP verwendet werden soll.

sender

Eine E-Mail-Adresse, die als Absender für alle von signoSign/Universal versendeten E-Mails verwendet.

Einstellungen ltv

Die Long Term Validation (LTV) Einstellungen für Unterschriften.

Eine Unterschrift ohne LTV benötigt einen Online-Dienst des Zertifikatausstellers um die Gültigkeit des Signierungszertifikats zu prüfen. Die Gültigkeit einer LTV Unterschrift kann auch geprüft werden, wenn der Dienst nicht verfügbar ist. Alle Information zur Validierung werden zum Zeitpunkt der Unterschrift erstellt und im PDF gespeichert.

signoSign/Universal wird automatisch LTV verwenden, wenn alle Bedingungen erfüllt sind. Die dafür benötigten Daten werden zum großen Teil aus der Zertifikatskette des Signierungszertifikats erstellt. Um unnötige Downloads der Kette zu vermeiden, sollte der Schlüsselspeicher des Zertifikats auch dessen Zertifikatskette enthalten.

required

Bestimmt, ob LTV für eine Signatur vorrausgesetzt wird oder nicht.

Einstellungen tsa

Die Einstellungen des Time Stamp Authority (TSA) Services.

Der optionale Time Stamp Authority (TSA) Service mit dem ein vertrauenswürdiger Zeitstempel für die Unterschrift erstellt wird. Wenn kein Service festgelegt ist, wird die lokale Zeit des signoSign/Universal Servers verwendet.

Benutzername und Passwort werden für Basic Authentication verwendet. Eine SSL Authentifizierung per Zertifikat (SSL Peer Authentication) sollte zentral über die Sicherheitseinstellungen der JVM via System-Property javax.net.ssl.keyStore eingestellt werden.

host

Die URL des TSA Services.

user

Der optionale Benutzername für Basic Authentication am Service.

password

Das Passwort für Basic Authentication.

Einstellungen jobs

Die folgenden Einstellungen bestimmen das Verhalten der Jobs in signoSign/Universal.

Hinweise:
Wenn documentLifeTimeInterval gesetzt wird, muss auch documentLifeTimeCreation und/oder documentLifeTimeModification gesetzt werden. Dasselbe gilt auch umgekehrt.
Das Dokument wird immer zum frühesten eingestellten Zeitpunkt gelöscht.

documentLifeTimeInterval

Diese Einstellung bestimmt das Intervall, in dem geprüft wird, welche Dokumente gelöscht werden müssen.

documentLifeTimeCreation

Diese Einstellung bestimmt die Dauer in Tagen, die zum Zeitpunkt der Prüfung seit der Erstellung des Dokuments vergangen sein müssen, damit ein Dokument gelöscht wird.

documentLifeTimeModification

Diese Einstellung bestimmt die Dauer in Tagen, die zum Zeitpunkt der Prüfung seit der letzten Bearbeitung des Dokuments vergangen sein müssen, damit ein Dokument gelöscht wird.

Einstellungen pool

Die folgenden Einstellungen bestimmen das Verhalten der „signoSign/Universal Dokumentenpool“ Anwendung.

preferredSmsService

Der bevorzugte Dienstanbieter für das Senden von SMS.

sendMailMethodForDocumentSharing

Legt fest, ob eine E-Mail über den eingestellen SMTP-Server versendet oder per mailto an den lokalen Mailclient übergeben wird.

allowSameSharingAndTanMethod

Legt fest, ob die selbe Methode fürs teilen von TAN und Empfänger verwendet werden darf.

showUserSettings

Entscheidet, ob die Benutzereinstellungen in der Pool-Ansicht angezeigt werden.

showDocumentTypes

Legt fest, ob die Funktion zum Verwalten von Dokumententypen im Pool angezeigt wird.

whiteList

Eine Liste von Hostnamen oder IP-Adressen, denen der Zugriff auf den Pool gewährt wird. Das Asterisks-Symbol (*) dient hier als Wildcard-Zeichen.

Einstellungen SMS

signoSign/Universal verwendet einen externen Dienst für das Versenden von SMS. Dieses Kapitel beschreibt die Einstellungen der unterstützen Dienste, von denen einer verwendet werden kann.
Siehe auch pool.preferredSmsService

Einstellungen sms77

Die folgenden Einstellungen werden verwendet, um den SMS-Dienst der sms77 e. K. aufzurufen.

apiKey

Der API key zur Authentifizierung des SMS-Dienstanbieters. Sie können diesen Schlüssel im Entwicklerbereich von sms77.io erstellen und anzeigen.

Einstellungen sipgate

Die folgenden Einstellungen werden verwendet, um den SMS-Dienst der sipgate GmbH anzurufen.

token

Das Personal Access Token (PAT) zur Authentifizierung des SMS-Dienstanbieters. Der Token benötigt den Scope sessions:sms:write für das Versenden von SMS und den Scope sms:read für das Auslesen der zu verwendenden Nebenstelle.
Siehe auch https://www.sipgate.io/rest-api/authentication#personalAccessToken.

tokenId

Die Token-Id des Personal Access Token zur Authentifizierung des SMS-Dienstanbieters.

smsId

Die ID der Nebenstelle von der aus die Nachricht gesendet wird.
Siehe auch https://github.com/sipgate-io/sipgateio-sendsms-java#web-sms-extensions.

Einstellungen auth

Die folgenden Einstellungen konfigurieren die Authentifizierung von Benutzern. Standardmäßig wird der Authentifizierungsmechanismus des Servlet Containers bzw. Application Servers verwendet. Alternativ kann Single Sign On (SSO) mit OpenID Connect (OIDC) verwendet werden.

Hinweise:

• Die mobilen Apps für Android und iOS sind nicht kompatibel mit Single Sign On. Verwenden Sie die Einstellung auth.type = REALM, um signoSign/Universal über die Apps zu nutzen.
• Für die Nutzung von Single Sign On ist die Einstellung des Schlüssels web.ssmPublicUrl zwinged erforderlich.

type

Legt den Typ der Authentifizierung fest.

realm.forceLowerCaseUsername

Wenn diese Einstellung aktiviert ist, wird die Groß-/Kleinschreibung des Benutzernamens ignoriert. Benutzer "Max Mustermann" und "max mustermann" teilen sich die gleichen Daten im System, wie bspw. Dokumente. Beide Benutzer können sich aber anmelden, solange der Login-Mechanismus dies zulässt, aber signoSign/Universal verwendet intern den kleingeschriebenen Benutzernamen.

Diese Einstellung sollte aktiviert werden, wenn der Login-Mechanismus die Groß-/Kleinschreibung ignoriert.

oidc.discoveryUrl

Die URL der OpenID Provider Metadata des Identity Servers . Die URL endet i. d. R. mit /.well-known/openid-configuration .

oidc.clientId

Der Identifier mit dem signoSign/Universal beim Identity Server registriert ist. Eine Anwendung, die OpenID Connect verwendet, muss beim Identity Server registriert sein, wobei dieser Identifier vergeben wird, der für den Authorization Code Flow benötigt wird.

oidc.clientSecret

Das beim Identity Server festgelegte Geheimnis, welches signoSign/Universal für den Authorization Code Flow verwendet.

oidc.scope

Die Scope Werte, die für den Authorization Code Flow verwendet werden. Für die grundlegende Funktionalität benötigt OpenID Connect den Wert openid .

oidc.usernameClaim

Der Wert (claim) im Token, aus dem der Benutzername entnommen wird. Wenn der Wert nicht vorhanden oder leer ist, ist ein Login an signoSign/Universal nicht möglich.

oidc.rolesClaim

Der Wert (claim) im Token, aus dem die Benutzerrollen entnommen werden. Wenn der Wert im Token nicht vorhanden, leer oder kein JSON Array ist, ist ein Login an signoSign/Universal nicht möglich.

oidc.tokenAudience

Aus Sicht des Identity Servers ist signoSign/Universal eine Ressource. Ein OAuth Access-Token wird immer für eine Ressource ausgestellt. Mit dieser Einstellung kann eine Liste von gültigen Ressourcen festgelegt werden. Die signoSign/Universal REST-API wird nur die Access-Token akzeptieren, dessen aud claim Wert in dieser Liste enthalten ist. Die Prüfung ist deaktiviert wenn kein Wert festgelegt ist.

Wichtig
Wenn die signoSign/Universal REST-API öffentlich verfügbar ist, wird die Angabe dieser Liste aus Sicherheitsgründen dringend empfohlen. Eine öffentliche REST-API sollte immer prüfen ob ein Access-Token für die API ausgestellt wurde.

oidc.tokenIssuer

Eine Liste von zusätzlichen vertrauenswürdigen Access-Token Ausstellern. Der Aussteller aus den OpenID Provider Metadata ist immer vertrauenswürdig. Die signoSign/Universal REST-API wird nur Access-Tokens akzeptieren, dessen iss claim Wert bekannt ist.

Einstellungen remoteSignature

Um ein Dokument in signoSign/Universal per Fernsignatur unterschreiben zu können, wird der Dienst signotec signoRemoteSignature benötigt. Mit den folgenden Einstellungen wird die Verbindung zum Dienst festgelegt. Werden die Einstellungen nicht vorgenommen, sind Fernsignaturen deaktiviert.

service.baseUrl

Diese Einstellung bestimmt den Service der für die Fernsignatur genutzt werden soll.

service.licenseKey

Diese Einstellung setzt den Lizenzschlüssel zur Nutzung des signoRemoteSignature Services.

Einstellungen logging

Die folgenden Einstellungen konfigurieren das Logging der signoSign/Universal Anwendung. Siehe auch web.clientDebugLogging.

Standardeinstellungen

Sofern keine externen Einstellungen verwendet werden, wird standardmäßig über die Java Logging API (java.util.logging) mit Level INFO auf die Konsole geloggt.

############################################################
#   Global properties
############################################################

# "handlers" specifies a comma separated list of log Handler 
# classes.  These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
handlers = java.util.logging.ConsoleHandler

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

############################################################
# Facility specific properties.
# Provides extra control for each logger.
############################################################

de.signotec.level = INFO
org.apache.pdfbox.level = SEVERE
org.jboss.weld.level = INFO
  

config.file

Diese Eigenschaft kann verwendet werden, um einen lokalen Pfad einer externen Konfigurationsdatei für die Standard Java Logging API (java.util.logging) festzulegen. Wenn diese Eigenschaft nicht gesetzt oder leer ist, wird die in signoSign/Universal enthaltene Standardkonfiguration in Datei logging.properties verwendet.

Beispiel externe Logging Einstellungen

Folgendes Beispiel erweitert die Standardeinstellungen um das Logging in eine Datei mit dem java.util.logging.FileHandler .

############################################################
#   Global properties
############################################################

# "handlers" specifies a comma separated list of log Handler 
# classes.  These handlers will be installed during VM startup.
# Note that these classes must be on the system classpath.
handlers= java.util.logging.FileHandler, java.util.logging.ConsoleHandler

############################################################
# Handler specific properties.
# Describes specific configuration info for Handlers.
############################################################

java.util.logging.FileHandler.level = INFO
java.util.logging.FileHandler.pattern = ../logs/signoSignUniversal_%g.log
java.util.logging.FileHandler.limit = 5000000
java.util.logging.FileHandler.count = 20
java.util.logging.FileHandler.formatter =  java.util.logging.SimpleFormatter
java.util.logging.FileHandler.append = true

java.util.logging.ConsoleHandler.level = INFO
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

############################################################
# Facility specific properties.
# Provides extra control for each logger.
############################################################

de.signotec.level = INFO
org.apache.pdfbox.level = SEVERE
org.jboss.weld.level = INFO
  

Einstellungen redisson

Um die Anwendung auf einem Tomcat-Server mit Redis als Session Storage zu betreiben, sind entsprechende Konfigurationsschritte erforderlich. Diese Konfiguration muss sowohl in der Anwendung selbst als auch am Tomcat-Server durchgeführt werden.

Bitte beachten Sie, dass diese Funktion sich noch in einer experimentellen Phase befindet und Änderungen unterliegen kann.

Bereitstellung der Konfiguration für die Anwendung:
Es ist erforderlich, dass die Anwendung selbst eine Konfigurationsdatei im JSON- oder YAML-Format bereitgestellt bekommt. Diese Datei enthält die spezifischen Einstellungen für die Anwendung, einschließlich der Informationen zur Verbindung mit der Redis-Instanz. Die Dokumentation zum Inhalt der Konfigurationsdatei finden Sie hier: https://github.com/redisson/redisson/wiki/2.-Configuration#272-sentinel-yaml-config-format.

Konfiguration des Tomcat:
Die Konfiguration des Tomcat wird am besten hier beschrieben: https://redisson.org/articles/redis-based-tomcat-session-management.html

redission.YamlConfigFile / redission.jsonConfigFile

Diese Einstellung verweist auf eine Konfigurationsdatei für die Redisson-API, die über einen relativen oder absoluten Pfad angegeben werden kann. Die Konfigurationsdatei definiert die Einstellungen und Parameter für die Redisson-Bibliothek. Eine ausführliche Dokumentation des Dateiformats und der verfügbaren Konfigurationsoptionen finden Sie unter folgendem Link: https://github.com/redisson/redisson/wiki/2.-Configuration/.

Einstellungen webhooks

Über Webhooks können externe Systeme über bestimmte Ereignisse in signoSign/Universal informiert werden. Für jede Art von Ereignis kann eine URL definiert werden, die bei Auftreten des Ereignisses aufgerufen wird.

Genauere Informationen zu Webhooks finden Sie hier.

documentUpdatedEndpoint

Das Ereignis wird ausgelöst, wenn ein Speichern-Vorgang durchgeführt wurde. Dazu zählen auch Remote-Saving und das Abschließen geteilter Dokumente

Der EventType des Ereignisses lautet: DOCUMENT_UPDATED

documentSharedEndpoint

Das Ereignis wird ausgelöst, wenn ein Dokument geteilt wird bzw. wenn der Vorgang angelegt wurde.

Der EventType des Ereignisses lautet: DOCUMENT_SHARED

workflowProcessStartedEndpoint

Das Ereignis wird ausgelöst, wenn ein Workflow-Prozess gestartet wird.

Der EventType des Ereignisses lautet: WORKFLOW_PROCESS_STARTED

workflowProcessStartedEndpoint

Das Ereignis wird ausgelöst, wenn ein Workflow-Prozess beended wird. Beim beenden spielt es keine Rolle, ob der Prozess abgebrochen oder abgeschlossen wird.

Der EventType des Ereignisses lautet: WORKFLOW_PROCESS_ENDED

pdfFont-realFont.properties

Öffnen Sie signosignuniversal-[PLATTFORM]-[VERSION].ear/lib/ssu-business-[VERSION].jar/pdfFont-realFont.properties (Version für Application Server) bzw. signoSignUniversal.war/WEB-INF/lib/ssu-business-[VERSION].jar/pdfFont-realFont.properties (Version für Servlet Container).

Diese Properties-Datei bietet die Möglichkeit zum Mapping von Schriftartnamen, die in PDF-Dokumenten verwendet werden, aber in Browsern bzw. Apps nicht dargestellt werden können. Dies ist entweder der Fall, wenn im PDF-Dokument PDF-spezifische Kurzformen der Standard-Schriftartnamen verwendet werden (diese Mappings sind bereits enthalten), oder bei der Generierung Schriftarten verwendet wurden, die Browser und Apps nicht kennen (ebenfalls ein Beispiel enthalten).

Dokument teilen (Sharing Cases)

Ein Dokument, welches in signoSign/Universal gespeichert ist, kann mit der Sharing Case Funktion mit externen Personen geteilt werden. Die Person muss nicht in signoSign/Universal registriert sein.

Was ist ein Sharing Case

Ein Sharing Case ist ein dauerhaft gespeichertes Element in der Datenbank. Es kann erstellt, bearbeitet und gelöscht werden. Ein Sharing Case ist mit einem Dokument verknüpft. Pro Dokument können beliebig viele Sharing Cases erstellt werden.

Existiert ein Sharing Case für ein Dokument, so kann das Dokument ohne Authentifizierung im signoSign/Universal Viewer geöffnet, bearbeitet und gespeichert werden. Der Zugriff kann optional durch ein Passwort geschützt werden.

Sharing Case erstellen

Der signoSign/Universal Viewer bietet einen Toolbar Button, mit dem ein Sharing Case für das geöffnete Dokument erstellt werden kann. Die Sichtbarkeit des Buttons wird mit der Einstellung web.sharingButtonVisibility festgelegt. Der Button wird deaktiviert dargestellt, wenn die Sharing Case Funktion mit der Einstellung persistence.documentSharing deaktiviert ist.

Mit der REST-API Ressource sharingcases können Sharing Cases erstellt, bearbeitet und gelöscht werden. Auch die vom signoSign/Universal Viewer erstellten Sharing Cases können bearbeitet werden.

Sharing Case öffnen

Ein Sharing Case wird mit einer speziellen URL geöffnet. Die URL kann beliebig oft aufgerufen werden und ist bis zum Löschen oder Abschluss des Sharing Case gültig.

Die URL zum Sharing Case ist über die Rest-API abrufbar und berücksichtigt bei der Generierung die ssmPublicUrl-Einstellung.

Aufbau der Sharing Case URL

Aufgrund von eventuellen Änderungen am Aufbau der URL wird immer empfohlen die URL über die Rest-API abzurufen. Soll die Rest-API jedoch kein Bestandteil einer Integration sein, ist hier der Aufbau der URL dokumentiert. Es wird darauf hingewiesen, dass es bei einer solchen Integration zu Migrationsaufwänden bei Updates kommen kann.

URL Format: [HOST]/signoSignUniversal/webvieweropen?action=sharedviewer&u=[USERNAME]&s=[ACCESSID]

Sharing Case abschließen

Ein geteiltes Dokument gilt als abgeschlossen, sobald der dazugehörige Link aufgerufen, verändert und gespeichert wird. Der Zeitpunkt, zu dem das geteilte Dokument gespeichert wurde, wird dabei festgehalten.

Sofern SMTP-Einstellungen hinterlegt wurden und der Benutzername des teilenden Benutzers einer gültigen E-Mail-Adresse entspricht, wird der Benutzer mit einer entsprechenden E-Mail über den Abschluss des Vorgangs informiert.

Konfiguration von Dokumententypen

Ein Dokumententyp ist eine Gruppe von Dokumenten, die von signotec-Software immer auf die gleiche Weise behandelt werden. Dazu zählt z. B. das automatische Einbringen von Signaturfeldern beim Laden eines Dokuments. Solche Dokumenteigenschaften lassen sich entweder zentral durch Dokumentenkonfigurationen oder dezentral durch das Einbringen von SGN-Schlüsselwörtern in ein PDF definieren.

SGN/PDF-Dokumente

SGN-Dokumente sind ein signotec-eigener Dateityp. Dabei handelt es sich beim technischen Aufbau um ein gültiges PDF in dessen Keyword -Feld der Metadaten eine Zeichenkette mit einer bestimmten Syntax geschrieben steht.

Durch das Einbringen von SGN-Schlüsselwörtern kann ein bestimmtes Verhalten der Anwendung dezentral in einzelnen PDF-Dokumenten definiert werden. Die im Folgenden erklärten signotec-Schlüsselwörter ( SGN Keywords ) werden zurzeit von signoSign/Universal ausgewertet.

• Manche Kombinationen aus SGN Keywords sind nicht möglich oder schließen sich gegenseitig aus, daher sollten alle neu erstellten Dokumente vorab getestet werden.
• Das zu importierende Dokument mit SGN-Schlüsselwörtern muss die Dateiendung .SGN erhalten.

Liste der SGN-Schlüsselwörter

Die Steuerung des Verhaltens von SignoSign/Universal erfolgt über die sogenannten SGN-Schlüsselwörter. Diese müssen in die zu unterschreibenden SGN/PDF Dokumente in dem Feld Keywords eingetragen werden. Dieses Feld besitzt jedes PDF-Dokument und kann frei gefüllt werden.

/sgnsignatures {3}
/sgnsignature_1 {1 0 10 10 150 30}
/sgnsigner_1 {Kunde}
/sgnsignature_2 {2 0 166 167 394 238}
/sgnsigner_2 {Berater}
/sgnsignature_3 {1 1 266 267 494 338}
/sgnsigner_3 {Tester}

Obligatorische Schlüsselwörter

Schlüsselwort sgnsignatures

Das Schlüsselwort sgnsignatures hat folgende Bedeutung: Bei Verwendung von Unterschriftenfeldern mit fester Position (eingebracht mittels sgnsignature_<N> ), muss hier die Gesamtanzahl der eingetragenen Signaturfelder/Signaturpositionen angeben werden. Werden Unterschriftenfelder anhand von Suchtext definiert (eingebracht mittels sgnsignaturekw_<N> oder sgnsignaturekw_r<N> ), muss hier die Anzahl der verwendeten sgnsignaturekw_ bzw. sgnsignaturekw_r Schlüsselwörter angegeben werden. Dies ist notwendig, da die Gesamtanzahl der aus den Suchbegriffen resultierenden Signaturfelder zu Beginn des Unterschriftenerfassungsvorgangs unbekannt ist.

sgnsignatures{3}

Schlüsselwort sgnsignature_N

Dieses Schlüsselwort definiert ein zu unterschreibendes Signaturfeld. Es ermöglicht das elektronische Unterschreiben eines SGN/PDF-Dokumentes mit einer digitalisierten Unterschrift an einer bestimmten Position und auf einer bestimmten Seite. Es können bis zu N Unterschriften in das Dokument eingebracht werden. N muss eine Ziffer sein und kann im Moment maximal 30 betragen.

• Mit dem Wert für N kann auch die Reihenfolge der Unterschriften bestimmt werden.
• Es können maximal 10 Unterschriften auf einer Seite des Dokumentes eingebracht werden.
• Es können maximal 30 Unterschriften insgesamt in einem Dokument eingebracht werden.
• Mittels des <Option> Parameters kann definiert werden, ob das Unterschriftenfeld unterschrieben werden muss (Pflichtfeld) oder ob es auch leer bleiben kann.

/sgnsignature_1 {1 0 379 699 549 730}
/sgnsignature_2 {2 0 377 630 549 650}
/sgnsignature_3 {6 0 277 530 449 550}

Schlüsselwort sgnsigner_N

Dieses Schlüsselwort ermöglicht es, die angezeigte Titelzeile im jeweiligen Unterschriftenerfassungsdialog zu verändern. Die Zuordnung zum dazugehörigen Unterschriftenfeld erfolgt über den Wert N.

Beispiel für das Ändern der Titelzeile beim Einbringen der 1. und 3. Unterschrift:

/sgnsigner_1 {Bitte unterschreiben Sie Herr Max Mustermann}
/sgnsigner_3 {Bitte unterschreiben Sie Frau Martha Musterfrau}

Schlüsselwort sgnsignaturekw_N

Durch dieses Keyword wird ein Signaturfeld ohne feste Position definiert. Seine Position wird anhand eines im Dokument befindlichen Textes festgelegt. Dieser Text wird gesucht und das Signaturfeld bei der ersten Fundstelle eingebracht. Dabei wird es relativ zur Fundstelle versetzt.

Beispiel für ein Signaturfeld, das mittels Suchworte erstellt werden soll.

/sgnsignaturekw_1 {0 -10 -20 80 40 Antragsteller:}

Schlüsselwort sgnsignaturekw_rN

Durch dieses Keyword wird eine unbestimmte Anzahl von Signaturfeldern ohne feste Position definiert. Ihre Positionen werden anhand der Fundstellen eines Textes im Dokument festgelegt. Dieser Text wird gesucht und ein Signaturfeld bei jeder Fundstelle eingebracht. Alle Signaturfelder werden relativ zu den Fundstellen um dieselben Werte versetzt.

Der Aufbau und die Dokumentation der Parameter sind identisch mit denen des Schlüsselwortes sgnsignaturekw_N und können dort entnommen werden.

Dokumentenkonfiguration

Neben den SGN-Schlüsselworten, bei denen Angaben über ein gewünschtes Verhalten dezentral in einem Dokument bestimmt wird, bietet die Dokumentenkonfiguration die Möglichkeit solche Einstellungen programmatisch über den REST-Webservice oder zentral in einer Konfigurationsdatei zu definieren.

Der Name und der Ort der Konfigurationsdatei ist in den Einstellungen definiert. Ist ein Pfad zu einer Konfigurationsdatei definiert, führt ein Fehlen dieser Datei trotzdem nicht zu einem Fehler. Nur wenn die Datei existiert muss sie mit einer validen JSON-Struktur befüllt sein. Andernfalls kommt es beim Start der Anwendung zu einem Fehler.

• Die Dokumentation betreffend der JSON-Struktur ist Teil der Standardimplementierung der Persistenz. Diese kann wie im entsprechenden Kapitel beschrieben geändert werden.

Aufbau der Dokumentenkonfigurationdatei

Die Dokumentenkonfigurationsdatei muss ein JSON-Array enthalten. Dieses enthält JSON-Strukturen, die jede für sich eine Dokumentenkonfiguration enthalten. Beim Laden eines Dokument wird über alle verfügbaren Konfigurationen iteriert, und die erste Konfiguration, welche alle Bedingungen erfüllt, wird auf das zu ladende Dokument angewendet.

Die Datei wird beim Start der Anwendung eingelesen. Ist der Inhalt der Datei zum Start der Anwendung kein valides JSON-Array oder enthält ein JSON-Element des Arrays einen Fehler, schlägt der Start von signoSign/Universal fehl. Im Folgenden wird auf alle einzelnen Attribute eingegangen, welche eine Dokumentenkonfiguration enthalten kann.

[
  {
   /* doc config 1 */
  },
  {
   /* doc config 2 */
  }
]    

Aufbau einer Dokumentenkonfiguration

Die JSON-Struktur wird so, wie sie an die Anwendung übergeben wird, in ein von der signoSign/Universal verwendbares Objekt umgewandelt. Im folgendem werden alle möglichen Attribute für eine Dokumentenkonfiguration aufgelistet. Bei den Attributen wird jedoch noch zwischen Auswahlbedingungen und eigentlichen Konfigurationen unterschieden.

Auswahlbedingungen

In einer Dokumentenkonfiguration gibt es Attribute, die als Bedingungen dienen, ob eine Konfiguration auf ein Dokument angewendet wird oder nicht. Es können beliebig viele Bedingungsattribute in einer Konfiguration angegeben werden. Eine Konfiguration wird nur dann auf ein Dokument angewendet, wenn alle Bedingungen für ein Dokument erfüllt sind.

documentFileNamePattern

Beispiel: Eine Konfiguration, die auf ein Dokument angewendet wird, dessen übergebener Dateiname mit "abc" beginnt.

[
     {        
         "documentFileNamePattern": "abc*"
     }        
]        

documentIdPattern

Beispiel: Eine Konfiguration, die auf ein Dokument angewendet wird, dessen ID mit einer "1" beginnt.

[
     {        
         "documentIdPattern": "1*"
     }        
]        

• Wird eine alternative Persistenzimplementierung eingesetzt, kann es sich bei der Dokumenten ID auch um einen nicht-numerischen Wert handeln.

documentIdTarget

Beispiel: Eine Konfiguration, die auf ein Dokument mit der ID 2 angewendet wird.

[
     {        
         "documentIdTarget": "2"
     }        
]        

documentOriginTypes

• 1 - für Vorlagen
• 2 - für editierbare Dokumente die von Vorlagen abstammen
• 4 - für alle editierbaren Dokumente
• 8 - für importierte Dokumente
• 16 - für Dokumente die über einen Sharing Case geöffnet werden

[
     {        
         "documentOriginTypes": 9
     }        
]        

Attribute der Konfiguration

Dabei handelt es sich um die Attribute der Konfiguration, welche die Handhabung des Dokuments im Viewer tatsächlich beeinflussen.

signatureFieldMask

Beispiel: Zeigt dem Benutzer "User1" beim Laden des Dokuments Signaturfeld mit der Tab-Order 0 auf Seite 1 und das Signaturfeld mit dem Namen "SIGNATURE1" an.

[
     {        
         "signatureFieldMask": {
             "User1" : "(1,0);SIGNATURE1"
         }
     }        
]        
    

signatureFields

Beispiel: Beim Laden des Dokuments werden zwei Signaturfelder eingebracht. Ein statisches auf Seite 1 und ein dynamisches beim Textvorkommen "searchtext".

[
    {        
      "signatureFields":[
         {
            "@type":"static",
            "option":0,
            "signer":"signer",
            "posX":500,
            "posY":20,
            "width":200,
            "height":50,
            "pageNumber":1
         },         
         {
            "@type":"dynamic",
            "option":0,
            "signer":"string",
            "offsetX":20,
            "offsetY":45,
            "width":200,
            "height":50,
            "keyword":"searchtext",
            "recursive":false
         }
      ]
    }        
]

formFieldProperties

• Zur Identifizierung eines Formularfeldes müssen entweder pageNumber und tabOrder oder fieldName definiert sein. Ist beides angegeben wird der fieldName bevorzugt behandelt.

Beispiel:

[
    {
            "formFieldProperties":[
                {
                "@type":"signature",
                "fieldName":"string",
                "tabOrder":0,
                "pageNumber":0,
                "shown":true
                }
            ]
    }
]

Beispiel:

[
    {
            "formFieldProperties":[
                {
                "@type":"checkbox",
                "fieldName":"CheckBoxFormFIELD",
                "tabOrder":0,
                "pageNumber":0,
                "padSelectionSignatureField":"signFIELD",
                "padSelectionText":"Lorem ipsum dolor sit amet, consetetur.",
                "checkRequiredToSignSignatureField":"signFIELD",
                "checkRequiredToSignSignatureFieldText":"Lorem ipsum dolor sit amet",
                "showIndex":0
                }
            ]
    }
]

sharingCaseProperties

In diesem Bereich der Dokumentenkonfiguration kann das Verhalten von Dokumenten bei der Freigabe oder im geteilten Zustand zu beeinflussen. Die folgenden Attribute sind verfügbar.

• -

Beispiel:

[
{
        "sharingCaseProperties":[
            {
            "completionCallbackURL":"https://signotec.com",
            }
        ]
}
]

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.

• Verwendung des Viewers
• Verwaltung persistierter Dokumente (Ausschließlich bei Gebrauch der konfigurierten Datenbank)
• Verwaltung geteilter Dokumente
• Verwaltung von Keystores (Zertifikate)
• Verwaltung von Workflows

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.

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.

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

• 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.
  • Anpassungen an der Konfiguration
  • Laden eines gespeicherten Dokuments aus der Persistenz
  • Laden eines temporären Dokuments durch Übergabe einer Datei
  • Laden eines temporären Dokuments durch Übergabe einer URL
  • 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.
  • Einfügen von dynamisch platzierten Signaturfeldern
  • Einfügen von statisch platzierten Signaturfeldern

Hinweis:
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

Hinweis:
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

Funktioniert nicht bei Verwendung einer eigenen Persistenzimplementierung.

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.

• Persistieren eines Dokuments
• Löschen von n Dokumenten
• Abfragen von Binärdaten zu einem Dokument
• Abfragen von Metadaten zu n Dokumenten
• Abfrage aller Teilvorgänge zu einem Dokument

Verwaltung geteilter Dokumente (Sharing Cases)

Funktioniert nicht bei Verwendung einer eigenen Persistenzimplementierung.

Auch die Verwaltung von geteilten Dokumenten ist über die API möglich.

• Anlegen neuer Sharing Cases
• Abfrage aller Sharing Cases eines Benutzers
• Anfrage eines Sharing Case anhand der Datenbank ID
• Anpassen eines Sharing Case anhand der Datenbank ID

Verwaltung von Keystores (Zertifikaten)

Funktioniert nicht bei Verwendung einer eigenen Persistenzimplementierung oder eines globalen Keystores.

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.

• 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.

• Hochladen eines Keystore
• Löschen eines Keystore
• Anlegen einer Zuweisung eines Zertifikats an einen Benutzer mit einem Zweck
• Abfrage von Zuweisungen
• Abfrage von allen Zuweisungen an einen Benutzer
• Anpassen einer Zuweisung
• Löschen einer Zuweisung

Hinweis:
Sofern ein Benutzer keinerlei Zertifikatszuweisungen hat, legt signoSign/Universal selbst entsprechende Zertifikate an, wenn ein Zertifikat benötigt wird.

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

• 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.

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.

Austausch von Dokumenten mit fremden Systemen

Das Remote-Saving ermöglicht, ein geladenes Dokument direkt per HTTP an ein anderes System zu senden. Die URL kann per PATCH /viewer/configuration mit dem Parameter saveUrl gesetzt werden und ändert damit die Funktion des Speicherns im Viewer. Informationen über den Status der Signaturfelder, werden beim Request mit folgenden URL-Parameter angehängt.

• sf: Anzahl der unterschriebenen Felder
• usf: Anzahl der nicht unterschriebenen Felder
• smf: Anzahl der unterschriebenen Pflichtfelder
• usmf: Anzahl der nicht unterschriebenen Pflichtfelder

Folgende Punkte muss von der empfangenden Seite berücksichtigt werden:

• Die Möglichkeit einen Multipart-Upload (Content-Type: multipart/form-data) entgegennehmen zu können
• Das PDF wird im Feld saveFile übergeben.
• Das Fremdsystem muss bei Erfolg mit einer Response mit dem Inhalt

  {
      "remoteSavingResponse" : "REMOTE_SAVING_SUCCESSFUL"
  } 
  

  und im Fehlerfall mit

  {
      "remoteSavingResponse" : "REMOTE_SAVING_FAILED"
  } 
  

  antworten oder alternativ mit

  {
      "remoteSavingResponse" : "REMOTE_SAVING_FAILED",
      "customizedSavingErrorMessage" : "my custom error message"
  } 
  

• Autorisierungsmöglichkeit durch Cookies (Falls eine Autorisierung notwendig ist)

Das Setzen von Cookies für die Kommunikation mit fremden Systemen ist hier beschrieben.

Kommunikation mit fremden Systemen

In bestimmten Fällen muss signoSign/Universal Anfragen an fremde Server senden. Ein konkretes Beispiel dafür ist das Remote-Saving, bei dem das zu speichernde Dokument als Multipart-Upload auf einen anderen Server hochgeladen wird.

Die REST-API erlaubt es, Cookies an einen Viewer anzuhängen (POST /viewer/cookie) , die bei allen Anfragen an andere Systeme mitgesendet werden. Es werden dabei ausschließlich Cookies mitgesendet, welche für die im Cookie gesetzte Domain bestimmt sind.

Alle Cookies bleiben solange erhalten, bis sie explizit gelöscht oder das instancetoken, zu dem sie gehören, zurückgezogen wird.

Integration mittels iFrame

Häufig wird signoSign/Universal in eine bereits bestehende Webanwendung als iFrame eingebettet. Ein Beispiel dazu ist bei laufender Anwendung in unserem REST-API Showcase zu finden, sofern die devTools aktiviert sind. Für diese Art der Integration stellt signoSign/Universal öffentliche Javascript-Methoden und -Events bereit, die ebenfalls in diesem Kapitel dokumentiert sind.

Allgemeine Hinweise

Sofern die umschließende Webanwendung und signoSign/Universal unter der gleichen Domain betrieben werden, sollte eine iFrame-Integration problemlos möglich sein. Sollte es jedoch auch in diesem Szenario zu Problemen kommen, ist eventuell die ssmPublicUrl-Einstellung nicht richtig gesetzt und beachten Sie, dass die meisten Browser kein Mischen von HTTP-Inhalten auf HTTPS-Seiten (und umgekehrt) zulassen.

Bei Problemen mit der Integration kann in den vielen Fällen die Javascript-Konsole des Browsers Aufschluss über die Ursache geben.

Cross-Origin-Resource Sharing

Sofern die umschließende Webanwendung und signoSign/Universal nicht auf der gleichen Domain betrieben werden, muss das Einbetten von signoSign/Universal als iFrame auf HTTP-Protokollebene erlaubt sein. Das bedeutet, dass jeder HTTP-Response die Header Access-Control-Allow-Origin und Access-Control-Allow-Methods hinzugefügt werden müssen.

Das Einfügen dieser HTTP-Header kann entweder durch Konfiguration des Servers oder durch Aktivierung des integrierten CORS-Filters. Die Konfiguration des CORS-Filters ist bereits in der web.xml von signoSign/Universal enthalten, ist aber auskommentiert. Die web.xml befindet sich im WEB-INF-Ordner des WARs bzw. EARs.

Cookies

Die Authentifizierung an signoSign/Universal wird in Cookies festgehalten. Bei Betrieb im iFrame wird das signoSign/Universal-Cookie aber von der umschließende Webanwendung angefragt. Läuft die umschließende Webanwendung unter einer anderen Domain als signoSign/Universal, muss dieses Cookie den Zugriff von fremden Domains ausdrücklich erlauben.

Dieses Verhalten wird mit dem SameSite-Attribut eines Cookies definiert und muss für den iFrame-Betrieb den Wert Lax haben. Das kann in der Regel am verwendeten Server konfiguriert werden.

Speziell für den Apache Tomcat, wird eine context.xml im META-INF-Ordner des signoSign/Universal-WAR ausgeliefert. Darin wird das SameSite-Attribut im Auslieferungszustand auf Strict gesetzt.

Öffentliche JavaScript-Funktionen

Wird signoSign/Universal in einem iFrame aus einer umschließenden Anwendung heraus aufgerufen, existiert eine Menge an öffentlich dokumentierten Funktionen im JavaScript-Code, die über das iFrame-Element ausgeführt werden können.

Folgender Code-Ausschnitt führt beispielhaft die Speichern-Funktion aus:

    iframe = document.getElementById("iframe");
    iframe.contentWindow.viewerFunctions.saveDocument();

Folgende Funktionen stellt der Viewer bereit:

JavaScript-Events

Wird signoSign/Universal als iFrame in eine andere Anwendung eingebettet, kann die umschließende Anwendung über bestimmte Ereignisse informiert werden.

Abhängig vom Ereignis kann das Verhalten von signoSign/Universal beeinflusst werden, indem innerhalb des definierten Eventhandlers die Methode preventDefault des an das Event übergebenen Objektes aufgerufen wird.

    iframe = document.getElementById("iframe");
    iframe.contentWindow.addEventListener("SSUMessageEvent", function(e) {
        console.info("SSUMessageEvent");
        console.info(e.detail.severity);
        console.info(e.detail.message);
    });

SSUMessageEvent

Wird ausgelöst, wenn signoSign/Universal eine Information oder einen Fehler anzeigt.

Standardverhalten:
signoSign/Universal zeigt die auftretende Meldung als separaten Dialog an.

PreventDefault():
Die auftretende Meldung wird nicht in einem Dialog in signoSign/Universal angezeigt. Die umschließende Anwendung kann die Meldung selbst behandeln.

SSUSignaturePerformedEvent

Wird ausgelöst, wenn eine Unterschrift geleistet und an den Server gesendet wird.

SSUDocumentSavedEvent

Wird ausgelöst, sobald der Speichernprozess durchgeführt wurde.

SSUUpdateFormFieldsEvent

Wird ausgelöst, wenn vom Anwender geänderte Formularfelder mit dem Backend synchronisiert werden.

Standardverhalten:
Alle Eingaben des Anwenders werden an den Server übertragen und in die serverseitige Repräsentation des Dokuments geschrieben.

PreventDefault():
Verhindert die Synchronisation zwischen Front- und Backend. Die Eingaben werden nicht in das Dokument eingebracht.

SSUPadOpenedEvent

Wird ausgelöst, sobald eine Verbindung zu einem Signaturgerät geöffnet wird.

SSUPadClosedEvent

Wird ausgelöst, sobald eine Verbindung zu einem signotec Signaturgerät geschlossen wurde.

SSUPadStateChangedEvent

Wird ausgelöst, sobald sich der Status des geöffneten Pads ändert. Ein Signaturgerät kann einen der folgenden Status annehmen:

SSUSignatureStartEvent

Wird ausgelöst, sobald ein Signaturprozess gestartet wird.

Standardverhalten:
Der Signierdialog wird geöffnet.

PreventDefault():
Das Öffnen des Signierdialogs wird unterbunden.

SSUFormFieldFocusEvent

Wird ausgelöst, wenn ein Formularfeld fokussiert wird.

Standardverhalten:
Das angesprochene Formularfeld wird fokussiert.

PreventDefault():
Das fokussieren des Formularfeldes wird unterbunden.

SSUDocumentLoadedEvent

Wird ausgelöst, sobald das Dokument fertig im Viewer geladen ist. Diesem Event werden keine Parameter übergeben.

SSUPageNumberChangeEvent

Wird ausgelöst, wenn zu einer anderen Seite im Dokument gewechselt wird.

Webhooks

Webhooks sind eine Möglichkeit, um über bestimmte Ereignisse in signoSign/Universal informiert zu werden. Dazu wird eine URL angegeben, die von signoSign/Universal bei einem Ereignis aufgerufen wird. Der Inhalt jedes Webhook-Aufrufs ist ein JSON-Objekt, das den Kontext abbildet, in dem das Ereignis aufgetreten ist und je nach Kontext variiert die Menge an Informationen, die übermittelt werden. So werden beim Speichern eines Dokuments durch den benutzer selbst z.B. keine SharingCase-Informationen übermittelt. Findet das Speichern aber als Teil eines Workflows statt, werden die Workflow-Informationen übermittelt.

In dem Bereich webhooks der Einstellungen können Sie für jedes mögliche Ereignis eine separate URL definieren.

Inhalt von Webhooks

			{
				"Event": {
				  "TimeStamp": Date as string(yyyy-MM-dd'T'HH:mm:ss.SSSXXX),
				  "EventType": string,
				  "Software": {
					"Name": "SignoSign/Universal",
					"Version": string
				  },
				  "User": {
					"UserName": string
				  },
				  "EventData": {
					"Document": {
					  "DocumentName": string,
					  "DocumentId": number,
					  "SignatureFields": number,
					  "MandatoryFields": number,
					  "SignedSignatureFields": number,
					  "SignedMandatoryFields": number,
					  "FormFields": [
						{
						  "Name": string,
						  "Value": string,
						  "Mandatory": boolean
			   
						},
					  ]
					},
					"SharingCase": {
					   "SharingCaseId": number,
					   "AccessId": string
					},
					"Workflow": {
					  "ProcessId": string
					}
				  }
				}
			  }
		

Zertifikate

Bei der Verarbeitung einer Unterschrift werden die erfassten Daten verschlüsselt und das Dokument nach dem Einfügen der Unterschrift signiert. Die Verschlüsselung benötigt ein Public-Key-Zertifikat, welches einen öffentlichen Schlüssel enthält. Für die Signierung wird ein komplettes Schlüsselpaar benötigt, also ein Public-Key-Zertifikat, dessen Zertifikatskette und der private Schlüssel passend zum öffentlich Schlüssel des Zertifikats.

Ein Zertifikat kann global für alle Benutzer verwendet, automatisch pro Benutzer generiert oder flexibel über die REST-API verwaltet werden. Die Zertifikate und Schlüssel müssen signoSign/Universal für die oben genannten Operationen zur Verfügung gestellt bzw. von signoSign/Universal gespeichert werden. Dennoch kann signoSign/Universal nicht zur Verwaltung von Zertifikaten und Schlüsseln verwendet werden, weil es keinen oder nur eingeschränkten Zugriff auf die gespeicherten Daten bietet.

Hinweis
Zur Verschlüsselung der biometrischen Daten wird signoSign/Universal standardmäßig mit einem Zertifikat ausgeliefert, welches von einem Notar erstellt und verwaltet wird. Dies bietet höchstmögliche Sicherheit im Umgang mit den sensiblen Unterschriftsdaten, ohne dass Sie sich mit der Schlüsselverwaltung beschäftigen müssen. Im Streitfall kann die Entschlüsselung der Biometrie beim Notar beauftragt werden. Insofern Sie die Zertifikate lieber selbst verwalten möchten, denken Sie daran, die Konfiguration entsprechend anzupassen, bevor Sie das System produktiv nutzen. Mehr Informationen erhalten Sie direkt beim Vertriebsteam von signotec.
Das Dokument wird standardmäßig mit einem Demo-Zertifikat digital signiert, welches für den produktiven Einsatz durch ein vertrauenswürdiges Zertifikat ersetzt werden muss. Siehe auch Kapitel Globale Zertifikate.

Java Cryptography Architecture

Die Zertifikate und Schlüssel werden über die Java Cryptography Architecture (JCA) geladen. Alle Formate, die mit der Klasse java.security.KeyStore geladen werden können, können auch von signoSign/Universal verarbeitet werden. Das Laden eines Zertifikats benötigt i.d.R. folgende Einstellungen:

• einen Keystore Typ, der das Format des Schlüsselspeichers festlegt
• eine Keystore Datei passend zum Typ
• den Namen / Alias des Zertifikats innerhalb des Stores
• die Passwörter für das Laden des Stores und dessen Elemente.

Globale Zertifikate

Um global ein Verschlüsselungszertifikat und ein Signierungszertifikat für alle Benutzer zu verwenden, muss in den Servereinstellungen der Schlüssel useCertificateDataProperties aktiviert und die Quelle der Zertifikate festgelegt werden.

        
    persistence.useCertificateDataProperties = true
    
    persistence.keystoreSigning = /var/ssu/global-store.jks
    persistence.signingAlias = signingCert
    persistence.signingKeyStoreType = JKS
    persistence.signingKeyStorePassword = storePassword
    persistence.signingprivatekeypassword = keyPassword
    
    persistence.keystoreBiometric = /var/ssu/global-store.jks
    persistence.biometricAlias = encryptionCert
    persistence.biometricKeyStoreType = JKS
    persistence.biometricKeyStorePassword = storePassword
        
    

Standard Zertifikate
Die standardmäßig von signoSign/Universal verwendeten globalen Schlüsselspeicher befinden sich neben der Properties Datei für die Servereinstellungen. Die Schlüsselspeicher enthalten ein Schlüsselpaar und ein selbst signiertes Demo-Zertifikat für die digitale Signatur und ein Zertifikat zur Verschlüsselung der biometrischen Daten, welches von einem Notar erstellt und verwaltet wird. Siehe auch Kapitel Zertifikate.
Zur Verschlüsselung wird das Zertifikat biometricalias aus dem Schlüsselspeicher keystoreBiometric.jks verwendet. Für die Signierung wird das Schlüsselpaar signingalias aus dem Speicher keystoreSigning.jks verwendet. Das Passwort beider Schlüsselspeicher lautet password .

Das Demo-Zertifikat und dessen Schlüssel sind nur zur Evaluation von signoSign/Universal voreingestellt und müssen für den produktiven Einsatz durch vertrauenswürdige Daten ersetzt werden!

[WEB-APP-ROOT]/WEB-INF/classes/keystoreBiometric.jks
[WEB-APP-ROOT]/WEB-INF/classes/keystoreSigning.jks
[WEB-APP-ROOT]/ssu_web-x.x.x.x.war/WEB-INF/classes/keystoreBiometric.jks
[WEB-APP-ROOT]/ssu_web-x.x.x.x.war/WEB-INF/classes/keystoreSigning.jks

Benutzerspezifische Zertifikate

Wenn weder globale Zertifikate noch über die REST-API konfigurierte Zertifikate verwendet werden, wird signoSign/Universal für jeden Benutzer einen Schlüsselspeicher mit Verschlüsselungs- und Signierungs-Zertifikat generieren.

Hardware-Sicherheitsmodul

Für die Verwendung eines Hardware-Sicherheitsmoduls (HSM) wird ein JCA/JCE Provider des Herstellers benötigt. Der Provider befindet sich normalerweise in einer JAR Bibliothek, die signoSign/Universal zur Verfügung gestellt werden muss. Die Funktionalität des Providers wird automatisch von signoSign/Universal verwendet, wenn als Keystore Typ der vom Provider vorgegebene Name verwendet wird.

Konfigurationsbeispiel
Ein Beispiel für die Servereinstellungen wenn

• der Hersteller den Keystore Typ "custom.store" vorgibt
• die Keystore Datei in /var/ssu/customStore liegt
• der Name/Alias des Verschlüsselungs-Zertifikats "encryptionCert" ist
• der Name/Alias des Signinerungs-Zertifikats "signingCert" ist
• kein Passwort nötig ist

        
    persistence.useCertificateDataProperties = true
    
    persistence.keystoreSigning = /var/ssu/customStore
    persistence.signingAlias = signingCert
    persistence.signingKeyStoreType = custom.store
    persistence.signingKeyStorePassword =
    
    persistence.keystoreBiometric = /var/ssu/customStore
    persistence.biometricAlias = encryptionCert
    persistence.biometricKeyStoreType = custom.store
    persistence.biometricKeyStorePassword =
        
    

Migration

Bei einem Update auf eine Version mit einer höheren zweiten Versionsnummernstelle können Änderungen am Datenbank-Schema notwendig sein. Für diesen Fall wird ein Kommandozeilen-Tool ausgeliefert, dem die aktuell verwendete Version, die Version auf die migriert werden soll und die Verbindungsdaten zur Datenbank übergeben werden. Das Programm führt die Änderungen an der Datenbank dann sukzessiv bis zur gewünschten Version durch.

Das Tool wird als Main-Klasse des migration-tool-[VERSION].jar ausgeführt. Dieses Jar befindet sich unter im Unterordner migration des Auslieferungspaket.

Zum Ausführen des Tools kann folgendes Kommando (Windows OS) verwendet werden:

Das Tool fragt vor dem Start alle notwendigen Parameter ab. Das sind der Reihenfolge nach:

1. Die Angabe zur aktuell verwendeten Version
2. Die Angabe zur Version, auf die migriert werden soll
3. Die Verbindungs-URL zur Datenbank
4. Ein Benutzername für die Datenbank
5. Ein Passwort für den angegebenen Benutzer
6. Der Package-Name des zu verwendenden JDBC-Treibers
7. Die Angabe des, von Hibernate zu verwendenden SQL-Dialekts, als Package-Namen

Weitere Hinweise zum Gebrauch des Migrations-Tools:

• Der verwendete Datenbankbenutzer benötigt das Recht, Tabellen des signoSign/Universal-Schemas zu ändern.
• Die Parameter für die Datenbankverbindung können aus der Hibernate-Konfiguration entnommen werden.
• Die verwendete Datenbank muss gestartet sein, damit die Migration durchgeführt werden kann. Das bedeutet, wenn SSU im Auslieferungszustand verwendet wird, muss SSU gestartet werden, damit die H2-Datenbank läuft.

Health Check URL

Um die Erreichbarkeit der Anwendung zu prüfen, kann der Endpoint:

angesprochen werden. Dieser liefert einen "HTTP200/ OK" zurück, wenn die Anwendung verfügbar ist.