Overview

signoSign/Universal is a web application used to display, edit and sign PDF documents and can be used flexibly from any end device. Apps are available for Android, iOS and Windows for simple use cases, as well as a small web application (‘signoSign/Universal document pool’). These allow the application to be used without the need for integration. For more complex use cases, the application can be integrated seamlessly into existing systems via a range of interfaces.

This documentation describes the technical integration options and the application programming interfaces (APIs) available.

Architecture

signoSign/Universal consists of a frontend that is displayed to the user in a browser or one of the signoSign/Universal apps on the client, and a backend in which the documents are processed on a Java server. Depending on the integration scenario, the backend accesses a persistence in the form of a database, a persistence made available by the integrator via a plug-in interface or data stored in the session. A REST web service can be used to access both the database and the data stored in the session.

H2 is also supplied as a configured database. Depending on the application scenario, we recommend configuring another database in live environments. A database is not required to integrate a custom persistence or to simply just store the data in the session.

Configuration

signoSign/Universal can be configured both statically using properties files, environment variables and system variables, as well as dynamically to a certain extent using a REST web service or a plug-in interface. A more detailed description of the configuration can be found in the Configuration parameters section.

Interfaces

signoSign/Universal provides comprehensive interfaces for a wide range of technologies. The following section contains a short overview of the available interfaces and their typical applications.

REST web service

The REST web service is the basis for the integration of signoSign/Universal and must always be used to generate a viewer instance, load a document and request the URL of the viewer in order to display it in a browser or a web view. The appearance and behaviour of the viewer instance can also be configured.

In addition, the web service offers functions to access the configured database.

The web service enables flexible integration with almost any programming language. signoSign/Universal does not require a direct connection to other systems; all data are exchanged via web interfaces.

Exchanging documents with third-party systems

The REST web service can be used to configure a URL via which signoSign/Universal can load a document in the viewer instance, as well as a URL to which signoSign/Universal can upload an edited document when saving it. This may be necessary if the REST client does not have access to the documents because they are to be created and processed on a third-party system. In this case, cookies can be set via which signoSign/Universal can also provide application information such as an authorisation.

More info here.

Plug-in interface

An integrator can be used to transfer and receive user-specific documents and configurations to and from the backend via the plug-in interface. The interface is particularly well-suited to situations in which the customer’s application and signoSign/Universal can be directly or indirectly connected with one another via a shared database, for example. Documents and configurations can then be exchanged directly between the systems.

This type of integration requires the interface to be implemented in Java. This custom implementation then replaces the supplied default integration that accesses the supplied database and some of the static configuration parameters. This makes the default integration partially or fully obsolete.

JavaScript functions and events

The frontend offers a range of JavaScript functions via which the program can control the viewer if it is embedded into another web application via an iFrame. This allows the signing process to be started or the file to be saved, for example. In addition, the surrounding application can be informed of certain events and respond to these.

The special feature of an iFrame integration is that the surrounding application can be blocked and that it retains control until the work in signoSign/Universal has been completed.

Licensing

By default, signoSign/Universal is supplied without a licence key entered. The full functionality of the application can be used without restriction in this state, but any signature images or pages rendered are watermarked.

• The host name
• The maximum number of processor cores used
• The number of concurrent viewers

If the licence verification fails or an invalid licence key is entered, a corresponding error message will appear when opening a document in signoSign/Universal. This behaviour is designed to prevent the application from being used in demo mode inadvertently.

A licence key can be set in the settings.properties file, as a Java system property or as an environment variable.

Licence attribute – host name

The computer name entered on the licence is compared with the output of the Java function InetAddress.getLocalHost().getHostName().

Licence attribute – processor cores

The number of processor cores used entered on the licence may not be lower than the actual number of cores used by the operating server.

Licence attribute – number of concurrent uses of the viewer

The number of concurrent uses entered on the licence refers exclusively to the documents displayed in the Viewer. Access to data sets or resources of the web service interface is not included in concurrent use of the viewer.

Configuration parameters

The global server settings are specified in a standard Java properties file. The application contains a file with default settings that can be either edited directly in the file or overloaded with an external properties file (see also externalPropertiesFile). Changes to the settings only come into effect after the application has been restarted.

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

This section describes the possible settings in the properties file and how these settings can be configured.

Environment and system variables

Every setting in the properties file can also be configured/overwritten by Java system properties and environment variables. The points in the variable names can be replaced by underscores (optional).

Format:
signotec.ssu. [SETTING]

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

• Environment variables with points are not permitted in every operating system. We generally recommend replacing all points with underscores. signotec.ssu.business.licenseKey - > signotec_ssu_business_licenseKey
• We recommend using the Java system properties as the call for the environment variables can vary between different Java servers.

Outsourcing configuration

The settings should be stored separately from the web application to simplify maintenance of the application in the future. User-defined settings should be specified in an external properties file instead of editing the default settings in the delivery package. Create a copy of the default settings and specify the storage location of the copy using the ‘signotec_ssu_externalpropertiesfile’ setting.

export signotec_ssu_externalpropertiesfile=/myConfigFolder/ssu/settings.properties

The default settings will load initially when starting signoSign/Universal and these will then be expanded/overwritten by the external settings.

Web settings

The following settings are possible in settings.properties with the prefix "web.".

renderQualityPercents

This setting allows the resolution (maximum 72 ppi) and, in turn, the visual quality of the rendered document pages to be configured in per cent. A higher quality can have a negative impact on the speed of the application.

ssmPublicUrl

Describes the public signoSign/Universal URL. This should be configured if the Java server on which signoSign/Universal is being run is not accessed directly (for example, if a load balancer is being used).

showLeaveUnchangedDialog

This setting defines whether a dialog box is displayed when leaving an unchanged document that notifies the user that no changes have been made to the document.

signatureFieldsOrderMode

This setting defines the order in which the signature fields are jumped into in the Viewer when the signing process for all fields is started by clicking the Sign button or the signature process is started through the automatedSignStartMode setting.

hardwarePadsOnly

This setting defines whether documents can only be signed with signature pads, or with the mouse or a touch device as well. If this option is enabled and no signature device is detected, all signature fields in the document will be hidden. This option is ignored when using signoSign/Universal apps.

disableMouseSignature

This setting determines whether signatures with the mouse pointer are disabled.

serialPadSearchType

This setting defines whether to search for serial pads and at which ports of the client device. Serial devices are not searched for by default.

wssDomainPort

This setting defines the domain names and the port from which the WebSocket of the signoPAD API/Web can be addressed. This setting is ignored if the add-on for Internet Explorer (ActiveX Pad Server) is used. You can find more information on this in the signoPAD API/Web documentation.

signatureColor

This setting defines the pen colour of the signature.

photoAllowedInApp

signoSign/Universal apps allow signatures to be inserted into a document together with a photo. This setting determines whether this option is available during the signature processes.

logoutUrl

In the logout process (signoSign/Universal logout button), the server attempts to redirect the client to several URLs in the following order. The URL that was sent with the referer request parameter when the document was loaded is used. If no referer has been transferred, the client is redirected to the logout URL.

Visibility of the toolbar buttons

The visibility of many of the toolbar buttons can be configured. A button can be configured to be visible, to be displayed in the submenu only, to be displayed in the header provided there is space available or to be displayed in the header as a matter of priority, which means that this button is moved to the submenu as a last resort.

saveBeforeExport

This setting defines whether a document is saved before it is exported from the Viewer (by clicking the Export button). All other settings that influence the saving process such as saveImportedDocuments are factored in.

saveImportedDocuments

This setting determines whether or not non-persistent documents (that were not loaded from the persistence) become persistent during the save process. This is also always used if a URL to remote storage is defined.

signPadDocumentView

Determines whether an excerpt of the document is displayed around the signature when capturing a signature with a signing device (see also signPadDocumentViewScalingFactor, signPadDocumentViewMarginLeft and signPadDocumentViewMarginTop)

signPadDocumentViewScalingFactor

This setting adjusts the scaling factor for the document excerpt on the signature device. It is an integer value that specifies the scaling in per cent.

signPadDocumentViewMarginLeft

This setting displays the left-hand edge of the signature field in the document excerpt. The larger the value, the greater the distance of the field from the left-hand edge.

signPadDocumentViewMarginTop

This setting displays the upper edge of the signature field in the document excerpt. The larger the value, the greater the distance from the upper edge.

autoShowDocumentOnPad

This setting defines whether the document display on the signature device is to be started automatically when the viewer is opened. Autostart is only launched if a signotec Delta device has been found and signoPAD API/Web is installed on the client. This function is enabled by default.

clientDebugLogging

This setting enables debug logging on the client side via JavaScript. All outputs are written in the browser console for information purposes. We recommend disabling this option in live operations to improve performance.

idleTimeout

This setting specifies the time period after which a document loaded by the user is closed by the server.

Permitted values:
All positive Integer values. 0 means that the timeout function is disabled.

captureBiometricData

This setting enables the capturing of biometric data during the signature capture. If this function is enabled, additional properties of the signature such as time taken and pen pressure are captured.

mockMode

In mock mode, started signatures are immediately confirmed with randomly generated points. The use of signature pads is disabled in this mode, but the same sequence of events is triggered in the application as if a signature device is connected. In addition, all form fields in this process are populated with the value 1 to avoid conflicts with the mandatory fields.

padCertificationAuthorities

This setting can be used to specify a PEM file that contains one or more certificate chains from certification authorities. The order of the certificates in the file can be freely selected. If a file is specified, signoSign/Universal checks whether the signature certificate stored in the signature device has been signed by one of the contained certificates. If this is not the case, then no signatures can be captured. This function is disabled by default.

This setting acts as a guarantee that only signing devices with known signature certificates can be used.

Business settings

The following settings are possible in settings.properties with the prefix "business.".

licenseKey

The licence key for signoSign/Universal can be entered here. Only change this value if you have consulted signotec. The application cannot be used without a valid licence key. The application runs in evaluation mode if no key is entered.

Persistence settings

These settings are read from the persistence layer and are ignored if a custom implementation is defined via the implementationClassName setting.

The following settings are possible in settings.properties with the prefix "persistence.".

implementationClassName

This setting enables the implementation of the persistence to be replaced by a custom implementation.

The value is the full class name with the user-defined implementation. The class must be public, must contain a public constructor without parameters and must implement the de.signotec.ssu.persistence.facade.SsuPersistenceModel interface.

pathToDocumentConfigFile

The storage location of document types. The default value is ./documentconfig.cfg.

referrerUrl

This setting specifies the URL to be redirected to if the Back button is clicked in the Viewer. Should the value be empty and no URL to go back to is defined, the Back button is not displayed.

useDocumentLocking

This setting determines whether a document can be opened by multiple users simultaneously. This function is disabled by default.

formFieldProtectMode

This setting controls which form fields are locked or marked as read-only when capturing a signature. This function never locks signature fields and never unlocks form fields that have already been locked.

Form or signature fields specified in the ‘signature field lock dictionary’ of a PDF are always locked independently of this function.

signatureFieldAddingAllowed

This setting defines whether signature fields may be added manually. This function is enabled by default.

signatureBackgroundTransparent

This value specifies whether the background of the rendered signature image is transparent.

signatureTextEnabled

This setting defines whether the signature text, such as the timestamp (see persistence.signatureText) for example, is to be added into the image of the signature and be visible in the document.

signatureText

This setting can contain any text that is added to the signature field in addition to the signature when signing. @SIGNTIME and @LOCATION can be added as placeholders that are replaced by real values.

If the setting is left empty, a pre-set timestamp is generated in a pre-set format corresponding to the language setting of the calling browser.

signatureTextDateTimeFormat

This setting sets the timestamp format by replacing ‘@SIGNTIME’ with ‘signatureText’, if included. The format string must adhere to the rules of Java SimpleDateFormat.

signatureTextHorizontalAlign

A signature text can be added to every signature field. These settings allow you to define the alignment of the text.

signatureTextVerticalAlign

A signature text can be added to every signature field. These settings allow you to define the alignment of the text.

documentSharing

This setting defines whether the function for sharing the document is enabled. If this function is disabled, the toolbar button is disabled/greyed out. The visibility of the toolbar button is configured using web.sharingButtonVisibility.

documentSharingEditablePassword

This setting defines whether the password of a shared document can be edited before the process is carried out. This function is enabled by default.

automatedSignStartMode

This property allows you to specify whether and how the signature capture is automatically started when a document is opened.

automatedSaveMode

This property allows you to specify whether and when a document is saved automatically.

allowSignfieldSelection

This setting defines whether the signature capture for a signature field can be started by clicking on the signature field. If this function is disabled, the signatures can only be captured in the predetermined order by using the ‘Sign’ button.

usePadEncryption

This setting controls whether the captured data of a signature are encrypted in the signotec signature device or in the backend of the web application. This means it only affects signatures captured with signature devices.

Certificates

signoSign/Universal requires both a certificate for the encryption of the signature and a certificate with a private key for signing the document. See also the Certificates section. Encryption in the signature device is controlled using the persistence.usePadEncryption setting.

Please note
A demo certificate is used with the default settings. Proprietary certificates should always be used in live operation.

useCertificateDataProperties

This setting defines whether an encryption certificate and a signature certificate are to be used globally for all users or whether the certificates are loaded from a central keystore.

keystoreBiometric

This setting defines the absolute storage location of the keystore from which the encryption certificate is loaded.

biometricKeyStoreType

This setting defines the type of the keystore as JKS, PKCS12, WINDOWS-MY and so on. The default value is the JRE standard type (JKE) or the type defined by the system property keystore.type. See also keystoreBiometric.

biometricKeyStorePassword

This setting defines the password for the keystore. Use an empty value if a password parameter of null must be transferred for the keystore implementation when the KeyStore.load() method is called.
The default value is biometricKeyStorePassword. See also keystoreBiometric.

biometricAlias

The setting for the alias of the encryption certificate in the keystore. See also keystoreBiometric.

keystoreSigning

This setting defines the absolute or storage location of the keystore from which the signature certificate and the private key are loaded.

signingKeyStoreType

This setting defines the type of the keystore as JKS, PKCS12, WINDOWS-MY and so on. The default value is the JRE standard type JKS or the type defined by the system property keystore.type.
See also keystoreSigning.

signingKeyStorePassword

This setting defines the password for the keystore. Use an empty value if a password parameter of null must be transferred for the keystore implementation when the KeyStore.load() method is called. See also keystoreSigning.

signingAlias

This setting defines the alias of the signature certificate and the private key in the keystore. See also keystoreSigning.

signingPrivateKeyPassword

This setting defines the password for the private key in the keystore. Use an empty value if a password parameter of null must be transferred for the keystore implementation when the KeyStore.load() method is called.
See also keystoreSigning.

Hibernate settings

The database connection is defined in the hibernate section of settings.properties. If a user-defined database is not specified, signoSign/Universal will attempt to start and use an H2 database. The storage location for this database depends on the hibernate.connectionUrl setting.

connectionDriverClassName

The JDBC driver class. Used for the hibernate.connection.driver_class hibernate property.

connectionUrl

The JDBC URL to the database instance. Used for the hibernate.connection.url hibernate setting.

dialect

Hibernate uses this property to generate the corresponding SQL for the selected database. Used for the ‘hibernate.dialect’ hibernate property.

connectionUsername

The database username. Used for the ‘hibernate.connection.username’ hibernate property.

connectionPassword

The database password. Used for the ‘hibernate.connection.password’ hibernate property.

Deployment settings

These settings relate to the additional functions provided by signoSign/Universal.

The following settings are possible in settings.properties with the prefix ‘deployment.’.

devTools

This refers to a Boolean flag that decides whether signoSign/Universal provides the following content:

• Rest API Showcase
• Rest API Swagger UI
• Technical documentation
• Process debug page

restapi settings

These settings related to the Rest API provided.

The following settings are possible in settings.properties with the prefix ‘restapi.’.

whiteList

A comma-separated list of host names and IP addresses, the content of which decides whether a requesting client is granted access to the Rest API or not. The asterisk symbol (‘*’) acts as a wildcard character here.

Einstellungen smtp

These settings affect the sending of emails. SignoSign / Universal uses the Javamail API for this.

host

The host name of the SMTP server to use.

user

User name to be used for the SMTP server.

password

Password to be used for the SMTP server.

userDisplayName

The display name that is displayed in a mail as the sender instead of the mail address.

auth

Determines whether the Javamail API authenticates using the AUTH command.

startTlsEnable

Determines whether a TLS-protected connection is established before the transmission of login data.

port

The port to be used for SMTP.

pdfFont-realFont.properties

Open signosignuniversal-[PLATTFORM]-[VERSION].ear/lib/ssu-business-[VERSION].jar/pdfFont-realFont.properties (version for application server) or signoSignUniversal.war/WEB-INF/lib/ssu-business-[VERSION].jar/pdfFont-realFont.properties (version for servlet container).

This property file allows font names that are used in PDF documents but cannot be displayed in browsers or apps to be mapped. This occurs either when short forms of standard font names specific to PDF are used in the PDF document (these are already mapped), or when font names have been used that browsers and apps do not recognise when the PDF was generated (also includes an example).

Share document (sharing cases)

A document that is saved in signoSign/Universal can be shared with external persons using the sharing case function. The person does not need to be registered in signoSign/Universal.

What is a sharing case?

A sharing case is an element that is permanently saved in the database. It can be created, edited and deleted. A sharing case is linked to a document. Any number of sharing cases can be created per document.

If a sharing case exists for a document, then the document can be opened, edited and saved in signoSign/Universal viewer without authentication. Access can be password protected (optional).

Creating a sharing case

signoSign/Universal viewer offers a toolbar button with which a sharing case can be created for the open document. The visibility of the button is defined using the web.sharingButtonVisibility setting. The button is displayed as disabled if the Sharing Case function is disabled using the persistence.documentSharing setting.

Sharing cases can be created, edited and deleted using the REST API sharingcases resource. Sharing cases created by signoSign/Universal viewer can also be edited.

Opening a sharing case

A sharing case is opened with a special URL. The URL can be called any number of times and is valid until the sharing case has been deleted.

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

Completing a sharing case

A shared document is considered complete once the associated link is called up, the document is changed and saved. The time at which the shared document was saved is recorded.

If SMTP settings have been stored and the user name of the sharing user corresponds to a valid e-mail address, the user will be informed of the completion of the process with a corresponding e-mail.

Configuration of document types

A document type is a group of documents that are always handled in the same way by signotec software. This includes automatically inserting signature fields when loading a document, for example. These types of document properties can be defined either centrally through document configurations or decentrally by inserting SGN keywords into a PDF.

SGN/PDF documents

SGN documents are a file type developed by signotec. In terms of technical structure, it is a valid PDF in which a character string with a certain syntax is written in its Keyword field of the metadata.

A certain application behaviour can be defined decentrally in individual PDF documents by inserting SGN keywords. The signotec keywords listed below (SGN Keywords) are currently evaluated by signoSign/Universal.

• Some combinations of SGN keywords are not possible or are mutually exclusive and therefore all newly created documents should be tested in advance.
• The document to be imported with SGN keywords must have the file extension .SGN.

List of SGN keywords

It is possible to control the behaviour of signoSign/Universal using the SGN keywords. These need to be entered in the Keywords field in the SGN/PDF documents to be signed. This field appears in every PDF document and can be freely filled.

/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}

Compulsory keywords

Keyword – sgnsignatures

The sgnsignatures keyword has the following description: If signature fields with a fixed position (inserted by means of sgnsignature_<N>) are used, the total number of signature fields/signature positions entered must be specified here. If signature fields are defined using search text (inserted by means of sgnsignaturekw_<N> or sgnsignaturekw_r<N>), the number of sgnsignaturekw_ or sgnsignaturekw_r keywords used must be specified here. This is necessary because the total number of signature fields resulting from the search terms is unknown at the beginning of the signature capture process.

sgnsignatures{3}

Keyword – sgnsignature_N

This keyword defines a signature field to be signed. It enables the electronic signing of a SGN/PDF document with a digital signature in a defined position and on a defined page. Up to N signatures can be inserted into the document. N must be a number and can currently be a maximum of 30.

• The value for N can also be used to determine the order of the signatures.
• A maximum of ten signatures can be inserted on one document page.
• A maximum of 30 signatures in total can be inserted into a document.
• The <Option> parameter can be used to define whether the signature field must be signed (mandatory field) or can remain empty.

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

Keyword – sgnsigner_N

This keyword allows the displayed title line to be changed in the relevant signature capture dialog box. The assignment to the related signature field is made via the N value.

Example showing how to change the title line when inserting the first and third signature:

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

Keyword – sgnsignaturekw_N

This keyword defines a signature field without a fixed position. Its position is defined using a text contained in the document. This text is searched and the signature field is inserted at the first hit location. It is offset relative to the hit location.

Example of a signature field to be created using search terms.

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

Keyword – sgnsignaturekw_rN

This keyword defines an unspecified number of signature fields without fixed positions. Their positions are defined by the hit locations of a text in the document. This text is searched and the signature field is inserted at every hit location. All signature fields are offset by the same values relative to the hit locations.

The structure and documentation of the parameters are identical to those of the keyword sgnsignaturekw_N and can be imported from there.

Document configuration

As well as the SGN keywords, which are used to define information relating to a desired behaviour in a document decentrally, the document configuration also enables the program to define these types of settings via the REST web service or centrally in a configuration file.

The name and the location of the configuration file is defined in the settings. If a path to a configuration file has been defined and this file is missing, it will still not lead to an error message. The file must only be populated with a valid JSON structure if it exists. Otherwise, an error will occur when the application starts.

• The documentation concerning the JSON structure is a part of the default implementation of the persistence. This can be changed as described in the corresponding section.

Structure of the document configuration file

The document configuration file must contain a JSON array. This contains JSON structures, each of which contains a separate document configuration. When a document is loaded, all available configurations are iterated through and the first one that meets all of the conditions is applied to the document to be loaded.

The file is read when the application is started. signoSign/Universal will not start if the content of the file does not contain a valid JSON array or a JSON element in the array contains an error when the application is launched. Every individual attribute that a document configuration can contain is described below.

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

Structure of a document configuration

The JSON structure transferred to the application is converted as is into an object that can be used by signoSign/Universal. All possible document configuration attributes are listed below. However, distinctions are still made between selection conditions and actual configurations for the attributes.

Selection conditions

A document configuration contains attributes that act as conditions as to whether or not a configuration is applied to a document. Any number of condition attributes can be specified in a configuration. A configuration is only then applied to a document if all the conditions for a document are met.

documentFileNamePattern

Example: A configuration that is applied to a document, the transferred file name of which begins with "abc".

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

documentIdPattern

Example: A configuration that is applied to a document, ID of which begins with "1".

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

• The document ID may be a non-numeric value if an alternative persistence implementation is used.

documentIdTarget

Example: A configuration that is applied to a document with the ID 2.

[
     {        
         "documentIdTarget": "2"
     }        
]        

documentOriginTypes

• 1 – for templates
• 2 – for editable documents based on templates
• 4 – for all editable documents
• 8 – for imported documents
• 16 – for documents opened via a Sharing Case

[
     {        
         "documentOriginTypes": 9
     }        
]        

Configuration attributes

These are attributes of the configuration that actually influence how the document is handled in the Viewer.

signatureFieldMask

Example: Shows the user "User1" the signature field with the tab order 0 on page 1 and the signature field with the name "SIGNATURE1" when the document is loaded

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

signatureFields

Example: Two signature fields are inserted when the document is loaded. A static field on page 1 and a dynamic field where the text "searchtext" occurs.

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

• Either the pageNumber and the tabOrder or the fieldName must be defined to identify a form field. If both are specified, the fieldName takes precedence.

Example:

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

Example:

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

REST API

signoSign/Universal has a REST API for integration. This section will focus less on the technical application of the API and more on the underlying concept.

A list of all available API calls plus structure and documentation can be found in the Swagger-UI.

• Using the Viewer
• Managing persistent documents (only when using the configured database)
• Managing shared documents
• Managing keystores (certificates)

The individual areas will be discussed in greater detail later.

Authorisation (generating an instancetoken)

To use an API, a so-called instancetoken must be requested from the server. This token is a unique character string. This must then be provided in every subsequent request to the API in the authorisation header of the request.

• An instancetoken is always linked to an instance of a Viewer object.
• A Viewer can only ever have one document loaded at a time.
• A user can request multiple instancetoken.
• An instancetoken remains valid until it is actively made invalid.

There is no specification as to how an existing application must integrate this schema. An example would be that the document pool requests an instancetoken when a user logs in and only becomes invalid when the user logs out. That means a viewer would be generated per user. It would also be possible to request a new instancetoken for each process, but it would then have to be ensured in each case that an obsolete instancetoken was invalidated.

Using the Viewer

• generated – by requesting an instancetoken
• prepared – by loading documents or applying configurations
• Called – by creating and calling an access URL
• and removed – by revoking the instancetoken

If not removing a Viewer by revoking the instancetoken the instancetoken and the associated Viewer may continue to be used.

Preparing the Viewer

As soon as a Viewer has been instantiated, it can be configured and a document can be loaded. The preparation can be divided into two areas:

• Preparation of the viewer itself, for example:
  • modifying the configuration
  • loading a saved document from the persistence
  • loading a temporary document by transferring a file
  • loading a temporary document by transferring a URL
  • adding, modifying and deleting cookies to communicate with third-party systems (for example, remote saving)
• Preparation of a loaded document, for example
  • inserting dynamically positioned signature fields
  • inserting statically positioned signature fields

Please note:
A Viewer can only ever have one document loaded at a time. As soon as another document is loaded, the old document is overwritten together with any document-related settings.

Calling the Viewer

Managing persistent documents

Does not work when using a custom persistence implementation.

The API allows you to manage persistent documents in the configured database. Documents in the database can be loaded directly into the Viewer using their numeric ID.

• persisting a document
• deleting n documents
• requesting binary data of a document
• requesting metadata of n documents
• requesting all subprocesses of a document

Managing shared documents (sharing cases)

Does not work when using a custom persistence implementation.

Shared documents can also be managed via the API.

• Creating a new sharing case
• Requesting all of a user’s sharing cases
• Requesting a sharing case using the database ID
• Adjusting a sharing case using the database ID

Managing keystores (certificates)

Does not work when using a custom persistence implementation or a global keystore.

signoSign/Universal requires two difference certificates; one for digital signatures and one for the encryption of biometric data. These certificates must be made available to signoSign/Universal in keystores.

• Uploading a keystore containing the necessary certificates
• Assigning certificates to a user within a keystore with a certain purpose

Purposes of certification
Assigning a certificate to a user always fulfils a certain purpose. Assigning a certificate can fulfil one of the following purposes

SIGNING : used to sign the document digitally. This ensures the integrity of the document. signoSign/Universal requires both a private key and a public certificate here.

ENCRYPTION : used to encrypt the signer’s biometric data. This ensures the traceability of a signature. signoSign/Universal only requires a public certificate here; the associated private key should be stored in a separate, safe location.

• Uploading a keystore
• Deleting a keystore
• creating an assignment of a certificate to a user with a certain purpose
• requesting assignments
• requesting all assignments to a user
• adjusting an assignment
• deleting an assignment

Please note:
If a user is not assigned any certificates and one is required, signoSign/Universal creates the relevant certificates itself.

User roles and the user name parameter

Some functions have a username parameter. This parameter allows functions to be executed in the name of this user. For example, user A can download a document from user B. However, this is only possible is user A has both the administrator role and the document-access role.

If the username parameter is left empty, it will be assumed that this value is the name of the user making the request. An access violation occurs if a user without the administrator role transfers the parameter and this does not match the name of the user performing the action.

Requesting detailed document information

Information on a document can be requested as soon as it has been loaded in the Viewer.

The resource [GET]/viewer/document/information is used for this purpose.

• General information on the document such as
  • the document ID
  • the total number of signature fields
  • the total number of signed signature fields
  • the total number of signed mandatory signature fields
  • the total number of form fields
  • the total number of form fields that have been filled out
  • the total number of mandatory form fields that have been filled out
  • the number of pages
• Information on all signature fields
  • the HTML ID below which the signature field is displayed in the Viewer
  • the horizontal position of the page in pixels
  • the vertical position of the page in pixels
  • the width in pixels
  • the height in pixels
  • the name of the signature field in the PDF
  • a Boolean value stating whether the signature is mandatory
  • a Boolean value stating whether the field is displayed in the Viewer
• Rendered images of the pages as Base64 strings
• The current state of the document in binary data

Exchanging documents with third-party systems

Remote saving allows a loaded document to be uploaded directly into a third-party system via the Save button. To do this, a remote saving URL must be transferred via [PATCH]/viewer/configuration. Two requirements are imposed on the server here:

• it must be able to accept a multipart upload
• it must send a response containing the following content upon successful completion:

  {"remoteSavingResponse":"REMOTE_SAVING_SUCCESSFUL"} 
  

  and a response containing the following content in the event of an error:

  {"remoteSavingResponse":"REMOTE_SAVING_FAILED"} 
  

• it must be able to give authorisation through cookies (if authorisation is required)

Setting cookies to communicate with third-party systems is described here.

Communicating with third-party systems

Certain situations require signoSign/Universal to send requests to third-party servers. Remote saving is a specific example of this. This is when a document that is to be saved is uploaded to another server as a multipart upload.

The REST API allows cookies to be attached to a Viewer that are also sent in all requests to other systems. Only cookies that are defined for the domain in the cookie are sent.

All cookies are stored until they are explicitly deleted or the instancetoken to which they belong is revoked.

Plug-in interface

The Java interface SsuPersistenceLayer is the interface to the persistence. signoSign/Universal uses it as a data source for documents, sharing cases, certificates and settings.

Default

The default implementation uses a relational database that can be defined using the hibernate settings, all configuration parameters that begin with the prefix persistence and the document configuration. Alternatively, selected data can be loaded from other sources, such as certificates from a hardware security module (HSM). For more details, please refer to the information on certificates in the persistence settings section.

User-defined

• User-specific or dynamic application configuration
• Use of a custom document source or file
• User-specific or dynamic document configuration
• Modify the lock function of loaded documents
• Modify the Share document function to customer requirements
• Use of a custom source for certificates
• Definition of a signature time independent of the server time (via a time server, for example)
• Evaluation and validation of URL parameters that have been provided when calling the viewer

Packetising custom Java code as a jar

    public class MySsuPersistenceLayerImpl extends SsuPersistenceLayerImpl {

        @Override
        PCRSaveDocumentFile saveDocumentFile(PCSaveDocumentFile persistenceBean) throws SsuPersistenceException {
            if (persistenceBean.getNumOfUnsignedMandatorySigFields() > 0) {
                throw new SsuPersistenceException("The Document can only be saved if all mandatory Signature Fields have been signed.")
            }
            return super.saveDocumentFile(persistenceBean);
        }   
    }

Libraries
The classes of the persistence and the libraries required are located in the integration/ssu-persistence-[VERSION]-with-dependencies.jar fatjar of the delivery package. No other libraries need to be integrated. The JavaDoc of the persistence is located in the integration/ssu-persistence-[VERSION]-javadoc.jar file.

Packetising
The user-defined code must be packetised in a jar with Java 8. The jar only contains the user-defined code. The web application already contains all of the fatjar classes.

Configuring the classpath

Activating the implementation

Public JavaScript functions

If signoSign/Universal is called in an iFrame from a surrounding application, there are a number of publicly documented functions in JavaScript code that can be executed via the iFrame element.

For example, the following snippet of code executes the save function:

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

The Viewer provides the following functions:

JavaScript events

If signoSign/Universal is embedded in another application as an iFrame, the surrounding application can be informed of certain events.

Depending on the event, the behaviour of signoSign/Universal can be influenced by calling the preventDefault method of the object transferred to the event within the defined event handler.

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

SSUMessageEvent

Executed when signoSign/Universal displays information or an error message.

Default behaviour:
signoSign/Universal displays the message that appears as a separate dialog box.

PreventDefault():
The message that appears is not displayed in a dialog box in signoSign/Universal. The surrounding application can handle the message itself.

SSUSignaturePerformedEvent

Executed when a signature is captured and sent to the server.

SSUDocumentSavedEvent

Executed as soon as the save process has been carried out.

SSUUpdateFormFieldsEvent

Executed when form fields changed by the user are synchronised with the backend.

Default behaviour:
All user entries are transferred to the server and written in the server-side representation of the document.

PreventDefault():
Prevents synchronisation between the frontend and backend. The entries are not inserted into the document.

SSUPadOpenedEvent

Executed as soon as a connection to a signature device has been opened.

SSUPadClosedEvent

Executed as soon as a connection to a signotec signature device has been closed.

SSUPadStateChangedEvent

Executed as soon as the status of the opened pad changes. A signature device can have one of the following statuses:

Certificates

When a signature is being processed, the captured data are encrypted and the document is signed after the signature has been inserted. The encryption requires a certificate containing a public key (public key certificate). A complete key pair is required for the signing, that is, a public key certificate and the private key matching the public key of the certificate.

A certificate can be used globally for all users, generated automatically per user or managed flexibly via the REST API. The certificates and keys must be made available to signoSign/Universal for the operations named above and saved by signoSign/Universal. However, signoSign/Universal cannot be used to manage certificates and keys as it only provides limited access to the saved data, if at all.

Please note
signoSign/Universal uses global demo certificates by default. These must be replaced by trusted certificates for live use. See also the Global certificates section.

Java Cryptography Architecture

The certificates and keys are loaded via the Java Cryptography Architecture (JCA). All formats that can be loaded with the class java.security.KeyStore can also be processed by signoSign/Universal. Loading a certificate generally requires the following settings:

• A keystore type that defines the format of the keystore
• A keystore file matching the type
• The name/alias of the certificate in the store
• The passwords needed to load the store and its elements.

Global certificates

To use an encryption certificate and a signature certificate for all users globally, the useCertificateDataProperties key must be enabled in the server settings and defined in the certificates’ sources.

        
    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
        
    

Demo certificates
The global keystores signoSign/Universal uses by default are located next to the Properties file for the server settings. The keystores each contain a key pair and self-signed certificate. The biometricalias certificate from the keystoreBiometric.jks keystore is used for encryption. The signingalias key pair from the keystoreSigning.jks store is used for the signing. The password for both keystores is password.

The demo certificates and keys are only pre-set to Evaluation by signoSign/Universal and must be replaced by trusted certificates for live use!

[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

User-specific certificates

If neither global certificates nor certificates configured via the REST API are used, signoSign/Universal will generate a keystore with encryption and signature certificates for each user.

    
    persistence.useCertificateDataProperties = false
    
    

Hardware security module

A JCA/JCE provider from the manufacturer is required to use a hardware security module (HSM). The provider is normally located in a JAR library, and signoSign/Universal must be given access to it. signoSign/Universal automatically uses the functionality of the provider if the name specified by the provider is used as the keystore type.

Configuration example
An example for the server settings if

• the manufacturer specifies the keystore type "custom.store"
• the keystore file is in /var/ssu/customStore
• the name/alias of the encryption certificate is "encryptionCert"
• the name/alias of the signature certificate is "signingCert"
• a password is not required

        
    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 =