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 zentral durch Dokumentenkonfigurationen in ein PDF definieren.

Dokumentenkonfiguration

Die Dokumentenkonfiguration bietet die Möglichkeit bestimmte Dokumente mit besonderen Verhaltensweisen zu versehen. Solche Einstellungen können 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.

Aufbau des JSON-Array in der Dokumentenkonfigurationsdatei:

JSON

[
  {
   /* 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

Trifft zu, wenn die angegebene Zeichenkette mit dem Dateinamen des zu ladenden Dokuments übereinstimmt. Das Asterisk-Symbol (*) dient hier als Wildcard-Zeichen.

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

JSON

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

documentIdPattern

Trifft zu, wenn die angegebene Zeichenkette mit der Dokumenten ID des zu ladenden Dokuments übereinstimmt. Das Asterisk-Symbol (*) dient hier als Wildcard-Zeichen.

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

JSON

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

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

documentIdTarget

Trifft zu, wenn die angegebene Zeichenkette mit der Dokumenten ID des zu ladenden Dokuments übereinstimmt.

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

JSON

[
     {        
         "documentIdTarget": "2"
     }        
]

documentOriginTypes

Hierbei handelt es sich um eine Bitmaske, die als Integer Wert zwischen 1 und 31 angegeben wird. Mit diesem Attribut ist es möglich Konfigurationen auf Dokumente mit bestimmter Herkunft anzuwenden.

Folgende Werte existieren:

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

Beispiel: Eine Konfiguration, die auf Vorlagen und importierte Dokumente angewendet wird.

JSON

[
     {        
         "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

Dabei handelt es sich um Schlüssel-Wert-Paare, die darüber entscheiden, welche Signaturfelder für den aufrufenden Benutzer angezeigt und zum unterschreiben zu Verfügung stehen. Der Schlüssel ist hier der aufrufende Benutzername, für den die Maske gelten soll. Der Wert ist eine Zeichenkette und enthält durch ein Semikolon (;) getrennte Identifizierer für Signaturfelder. Ein Identifizierer für Signaturfelder besteht entweder aus Seitennummer und Tab-Order oder aus dem technischen Signaturfeldnamen.

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.

JSON

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

signatureFields

Hier gibt es die Möglichkeit ein Feld statisch oder dynamisch zu setzen. Bei dem Attribut handelt es sich um ein JSON-Array. Dieses kann dynamische ("@type":"dynamic",) und statische ("@type":"static",) Signaturfeldern enthalten. Statische Signaturfelder werden durch fixe Angaben im Dokument platziert. Dynamische Signaturfelder können relativ zu einer Position eines Textes im Dokument platziert werden. Jedes Signaturfeld setzt sich aus einer Menge von Attributen zusammen. Diese bestehen aus allgemeinen und Typabhängigen Attributen.

Allgemeine Signaturfeld-Attribute

Attribut	Beschreibung	Wertebereich
@type	Bestimmt den Typ des Signaturfeldes.	`"dynamic", "static"`
option	0 = Position muss nicht unterschrieben werden. 1 = Position muss unterschrieben werden. (Pflichtfeld)	`1, 0`
width	Bestimmt die Breite des Signaturfeldes.	`Integer > 0`
height	Bestimmt die Höhe des Signaturfeldes.	`Integer > 0`
signer	Bestimmt den Signaturfeldnamen.	`String`

Statische Signaturfeld-Attribute

Attribut	Beschreibung	Wertebereich
posX	Horizontale Position des Signaturfeldes. 0 entspricht dem oberen Rand der Seite.	`Integer >= 0`
posY	Vertikale Position des Signaturfeldes. 0 entspricht dem linken Rand der Seite.	`Integer >= 0`
pageNumber	Seitennummer auf der das Signaturfeld platziert wird. 1 entspricht der ersten Seite.	`Integer > 0`

Dynamische Signaturfeld-Attribute

Attribut	Beschreibung	Wertebereich
offsetX	Horizontale Verschiebung des Signaturfeldes, ausgehend von der Position des keyword-Textes im Dokument.	`Integer`
offsetY	Vertikale Verschiebung des Signaturfeldes, ausgehend von der Position des keyword-Textes im Dokument.	`Integer`
keyword	Suchwort (Zeichenkette). Das PDF Dokument wird nach diesem Suchwort durchsucht und die Koordinaten der ersten Fundstelle werden zurückgeliefert. Muss eine einzelne Zeichenkette sein (ohne Leerzeichen) und muss von Doppel-Hochkommas eingeschlossen sein. Es werden alle Seiten durchsucht.	`String`
recursive	Ein boolescher Wert, der darüber entscheidet, ob nur das erste Vorkommen des <keyword>-Textes mit einem Signaturfeld versehen wird oder alle Textvorkommen.	`true, false`

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

JSON

[
    {        
      "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

Bei diesem Attribut handelt es sich um ein JSON-Array. Jedes Element definiert zusätzliches Verhalten für einzelne Formularfelder bestimmter Typen. Jedes Element besteht aus allgemeinen und Typabhängigen Attributen. Die allgemeinen Attribute dienen hier zur Identifizierung des gewünschten Formularfeldes.

Formularfeld-Attribute: Allgemeine

Attribut	Beschreibung	Wertebereich
@type	Gibt den Typ des Formularfeldes an, für das die zusätzlichen Eigenschaften gelten sollen.	`"signature", "checkbox"`
fieldName	Der Feldname des Formularfeldes, für das die zusätzlichen Eigenschaften gelten sollen.	`String`
tabOrder	Der Tab-Order Wert des Formularfeldes, für das die zusätzlichen Eigenschaften gelten sollen. Die Tab-Order beginnt bei 0.	`Integer`
pageNumber	Die Seitennummer, auf der sich das Formularfeldes befindet, für das die zusätzlichen Eigenschaften gelten sollen. Die Seitenzahl beginnt bei 1.	`Integer > 0`

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

Formularfeld-Attribute: Signaturen

Attribut	Beschreibung	Wertebereich
shown	Entscheidet, ob das betroffene Signaturfeld beim Laden des Dokuments angezeigt werden soll.	`true, false`

Beispiel:

JSON

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

Formularfeld-Attribute: Checkboxen

Attribut	Beschreibung	Wertebereich
padSelectionSignatureField	Mit der signoPAD-API/Web (ab Version 1.4.1) ist es möglich, Checkboxen zum Setzen an ein Hardwarepad zu übergeben. Mit diesem Feld lässt sich definieren, ob eine Eingabe der Checkbox über das Signaturgerät erfolgen soll und vor welchem Signaturfeld das geschehen soll. Ein Signaturfeld wird entweder über den Signaturfeldnamen oder Seitennummer und Taborder angegeben. Wird eine leere Zeichenkette übergeben, findet der Vorgang zusammen mit der ersten Unterschrift statt. Checkboxen, welche auf diese Art an ein Signaturfeld gebunden werden, werden beim Speichern nicht mehr destruktiv ins Dokument eingebracht. Signaturgebundene Checkboxen werden inkrementell zusammen mit der entsprechenden Signatur gespeichert. Darüber hinaus werden die Formularfeldinformationen einer solchen Checkbox ebenfalls in die verschlüsselten Daten der Unterschrift selbst eingebracht.	`String`
padSelectionText	Sollte eine Checkbox zum Setzen an einem Hardwarepad definiert sein, ist es erforderlich, auch einen Text zu übergeben, der zusammen mit der Checkbox am Signaturgerät angezeigt wird. Die mögliche Länge des Texts ist abhängig vom verwendeten Signaturgerät, weil der angegebene Text auf das Display skaliert wird. Das bedeutet, umso mehr Text verwendet wird, desto kleiner wird die Schrift. Sind mehrere Checkboxen für eine Unterschrift definiert, werden sie nach Möglichkeit zusammen auf dem Display angezeigt. Ist dies aufgrund der Textmenge nicht möglich, werden die Eingaben auf mehrere Seiten verteilt. Für einen Zeilenumbruch im Text wird „\n“ verwendet.	`String`
checkRequiredToSignSignatureField	Genau wie für den Wert padSelectionSignatureField kann hier ebenfalls ein Signaturfeld angegeben werden. Um den Signiervorgang zu dem angegebenen Signaturfeld starten zu können, muss die entsprechende Checkbox angehakt sein. Wird eine leere Zeichenkette angegeben, gilt das beschriebene Vorgehen für den ersten Signiervorgang. Wird diese Checkbox auch zur Eingabe an einem Hardwarepad konfiguriert, findet die Validierung, ob eine entsprechende Checkbox angehakt ist, erst beim Bestätigen des Dialogs am Hardwarepad statt.	`String`
checkRequiredToSignSignatureFieldText	Sofern der Wert checkRequiredToSignSignatureField definiert wurde, wird dieser Wert in Form einer Meldung im Viewer angezeigt und der Signiervorgang wird abgebrochen, wenn die entsprechende Checkbox nicht angehakt ist.	`String`
showIndex	Ein Index, der bestimmt, in welcher Reihenfolge die Checkbox auf dem Pad angezeigt werden soll.	`Integer`

Beispiel:

JSON

[
    {
        "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.

Attribut	Beschreibung	Wertebereich
completionCallbackURL	Eine URL, zu der der Client navigiert, wenn der Benutzer den Vorgang abgeschlossen hat. Der Benutzer hat keine Wahl, ob er nach Abschluss des Vorgangs im Dokument bleibt oder das Dokument herunterlädt.	Eine URL als `String`
rejectable	Legt fest, ob der Vorgang vom Empfänger abgelehnt werden kann. Eine abgelehnte Operation nicht mehr als aktiv.	`boolean`
deferrable	Legt fest, ob der Empfänger den Vorgang speichern kann, ohne ihn abzulehnen, oder abgelehnt wird. Ein zwischengespeicherter Vorgang gilt weiterhin als aktiv.	`boolean`

Das Ablehnen und Zwischenspeichern von Vorgängen kann auch global durch persistence.documentSharingRejectable und persistence.persistencedocumentSharingDeferrable gesteuert werden.

Beispiel:

JSON

[
    {
        "sharingCaseProperties":[
            {
                "completionCallbackURL":"https://signotec.com",
                "rejectable":true,
                "deferrable":false,
            }
        ]
    }
]