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 the 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 used as a preconfigured 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, and 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.

Further information is given in the section ‘Communicating with third-party systems’.

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 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 uses of the Viewer

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 external PropertiesFile). 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.".

ssmPublicUrl

Describes the public URL of the signoSign/Universal application. It is used to generate access URLs for the application, for example for links in messaging e-mails of the workflows.

ssmInternalUrl

This property defines a URL on which the signoSign/Universal application is reachable from within the server. This URL is used especially for REST-calls that do not need to be called over a public interface. It reduces public traffic and makes load balancing easier.

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.

supportedCaptureInput

This setting defines a list of permitted input types for a hand-written signature. During capturing, it is checked whether the input type used is included in the list. If the input type is not included, capturing is cancelled with a note regarding the valid input types.

signatureFieldsOrderMode

This setting defines the order in which the signature fields are jumped to 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. First, 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 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.

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 displayed in the document 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:
To encrypt biometric data, signoSign/Universal is supplied with a certificate as standard that is created and managed by a notary. This provides the greatest possible security when dealing with sensitive signature data without you having to deal with key management. In the case of a dispute, the notary can be instructed to decrypt the biometric data. If you would prefer to manage the certificates yourself, please remember to adjust the configuration accordingly before using the system productively. More information is available directly from the signotec sales team.
The document is digitally signed with a demo certificate as standard that needs to be replaced by a trusted certificate for productive use. See also the Global certificates section.

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 JKS or the type defined by the system property keystore.type.

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.

biometricAlias

The setting for the alias of the encryption certificate in the keystore.

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.

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.

signingAlias

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

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.

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 start 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 user name. 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

pool

Decides whether signoSign/Universal provides a frontend for managing documents. When the server is running, the pool application can be found at ../signoSignUniversal/pool

internalDatabase

Specifies whether signoSign/Universal starts the H2 database before the connection is established.

restapi settings

These settings relate to the REST API provided.

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

whiteList

A list of hostnames or IP addresses that are granted access to the REST API. The asterisk symbol (‘*’) acts as a wildcard character here.

SMTP settings

These settings relate to the sending of e-mails. SignoSign/Universal uses the Javamail API for this purpose.

host

The hostname of the SMTP server that is to be used.

user

The user name that is used for the SMTP server.

password

The password that is used for the SMTP server.

userDisplayName

The display name that is displayed in an e-mail as the sender in place of the e-mail address.

auth

Determines whether the Javamail API is authenticated on the basis of the AUTH command.

startTlsEnable

Determines whether a TLS-secured connection is established before the login data are sent.

port

The port that is used for SMTP.

LTV settings

The long term validation (LTV) settings for signatures.

A signature without LTV requires an online service of the certificate authority in order to check the validity of the signature certificate. The validity of an LTV signature can also be checked if the service is not available. All information on validation is created at the time of signing and saved in the PDF.

signoSign/Universal will automatically use LTV if all conditions are fulfilled. The data required for this are mainly created from the certificate chain of the signature certificate. To prevent unnecessary downloads of the chain, the keystore of the certificate should also contain its certificate chain.

required

Determines whether LTV is required for a signature.

TSA settings

The settings for the time stamp authority (TSA) service.

The optional time stamp authority (TSA) service that is used to create a reliable timestamp for the signature. If no service is specified, the local time of the signoSign/Universal server is used.

User name and password are used for the basic authentication. An SSL authentication via certificate (SSL peer authentication) should be set central via the security settings of JVM via system property javax.net.ssl.keyStore .

host

The URL of the TSA service.

user

The optional user name for basic authentication at the service.

password

The password for basic authentication.

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 or finalised.

The URL for the sharing case can be called via the Rest API and takes into account the ssmPublicUrl setting during generation.

Structure of the sharing case URL

Because there may be changes in the structure of the URL, it is always recommended to call the URL via the Rest API. If the Rest API is not intended to be part of an integration, however, the structure of the URL is documented here. Note that such an integration can cause a greater migration workload in the event of updates.

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

Finalising a sharing case

A shared document is considered finalised once the related link has been called, changed and saved. The time at which the shared document was saved is recorded.

If SMTP settings have been saved and the user name of the sharing user corresponds to a valid e-mail address, the user will be sent an e-mail informing them that the process has been finalised.

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 (SGN keywords) listed below 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 {customer}
	/sgnsignature_2 {2 0 166 167 394 238}
	/sgnsigner_2 {consultant}
	/sgnsignature_3 {1 1 266 267 494 338}
	/sgnsigner_3 {tester}
	

Compulsory keywords

Keyword sgnsignatures

The sgnsignatures keyword has the following meaning: If signature fields with a fixed position (inserted by means of sgnsignature_<N> ) are used, the total number of entered signature fields/signature positions must be specified here. If signature fields are defined using search text (inserted by means of sgnsignature_<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 {Please sign here Mr John Doe}
	/sgnsigner_3 {Please sign here Ms Jane Doe}

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 Requester:}

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 tabOrder or 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)
• Managing workflows

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 at least one instance of a Viewer object. In multi-viewer scenarios, the viewers should preferably be created by one instancetoken instead of generating an instancetoken for each viewer.
• A Viewer can only ever have one document loaded at a time.
• A server session can open any number of viewers of an instancetoken in parallel. The viewers of a second instancetoken can only be opened after all viewers of the first instancetoken have been closed.
• A user can request more than one 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 that one instance of a viewer is 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 a Viewer is not removed by revoking the instancetoken, the instancetoken and the associated Viewer may continue to be used. In multi-viewer scenarios, the viewers should preferably be created by one instancetoken instead of generating an instancetoken for each viewer.

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

Please note:
A server session can open any number of viewers of an instancetoken in parallel. The viewers of a second instancetoken can only be opened after all viewers of the first instancetoken have been closed.

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 new sharing cases
• requesting all sharing cases of a user
• 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 is 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 is 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, signoSign/Universal creates the relevant certificates itself if a certificate is required.

User roles and the ownerId

Some functions have an ownerId 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 if user A has both the ssu-user role and the ssu-admin role.

If the ownerId 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 ownerId 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

Proprietary HTTP status codes

In individual cases, the REST-API also uses proprietary codes in addition to the standard codes in order to enable the handling of special cases.

Managing workflows

signoSign/Universal makes it possible to automate workflows with the resource REST API Resource Workflows. A workflow and the data used in it are specified in a template (blueprint) which can then be started any number of times.

Blueprints

A blueprint defines a complete workflow and the data processed within it. A newly created workflow is empty and must be filled with steps. It is then possible to start the blueprint. Every start creates a process. Subsequent changes to the blueprint have no effect on the processes.
Deleting a blueprint deletes the steps and all processes. Blueprints that are linked to an active process cannot be deleted.

Blueprint steps

The blueprint steps define what actions are to be performed and in what sequence. Steps can be performed sequentially, in parallel or in a mixture of the two variants.

Actions

When a step is created, its type specifies the type of action. The REST API provides an endpoint for each type.

• DEMAND_SIGNATURE
  A document folder is shared via e-mail. The documents can be opened in the signoSign/Universal Viewer by following a link in the e-mail and signed.
  POST /workflows/blueprints/{blueprintId}/steps/demandSignature
  POST /workflows/blueprints/steps/{stepId}/demandSignature/documents

Sequence

Indices are used to define the start sequence for the workflow steps. Each step contains an attribute stepIndex and nextStepIndex.

• stepIndex
  The stepIndex attribute specifies when the step is to be performed. An index can be used by several or all steps. The list of indices for all steps together must begin with 1 and continue with consecutive numbers (1, 2, 3, etc.), otherwise it will not be possible to start the blueprint.
• nextStepIndex
  The nextStepIndex attribute specifies that steps with this stepIndex are to be performed afterwards. A step with stepIndex == N is only performed once all steps with nextStepIndex == N have been completed. Steps that are not blocked by a nextStepIndex attribute are started when the blueprint is started.

Document folders

Workflow steps are linked with documents by means of folders ( DocumentFolder ). A folder can contain any number of documents and a document can only be linked to one folder.

As standard, an empty folder is created for each step that involves processing documents. If a document is allocated to the step, a copy of the document is stored in the folder. If two steps are to process the same document, they must use the same folder. The folder can be specified either when the step is created or later on when the document is linked. In each case, the parameter documentFolderId is used.

Processes

A workflow process represents a blueprint that has been started. For each blueprint step, the process contains an event with a copy of the work data of the blueprint step. Subsequent changes to the blueprint do not affect the process or its events.

The REST API can be used to start, query and delete processes. Deletion removes the process and its events, including the work data, such as the documents. Active process cannot be deleted.

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, workflows, certificates and settings.

Default

The default implementation uses a relational database that can be defined using the hibernate settings. The standard implementation is configured via the persistence configuration parameter and 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 fatjar integration/ssu-persistence-[VERSION]-with-dependencies.jar 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

Integration by means of iFrame

signoSign/Universal is often embedded in an existing web application as iFrame. An example of this can be found in when the application is running in our REST API Showcase, if devTools are activated. For this type of integration, signoSign/Universal provides public Javascript methods and events, which are also documented in this section.

General information

If the surrounding web application and signoSign/Universal are operated under the same domain, an iFrame integration should be straightforward. If problems do occur in this scenario, however, the ssmPublicUrl setting may not be set correctly; also bear in mind that most browsers do not permit the mixing of HTTP content on HTTPS pages (and vice versa).

If there are problems with integration, in many cases the browser’s Javascript console can provide information about the cause.

Cross-origin resource sharing

If the surrounding web application and signoSign/Universal are not operated on the same domain, the embedding of signoSign/Universal as iFrame must be permitted at HTTP protocol level. This means that the headers Access-Control-Allow-Origin and Access-Control-Allow-Methods must be added to every HTTP response.

These HTTP headers can be added either by configuring the server or by activating the integrated CORS filter. The configuration of the CORS filter is already included in the web.xml of signoSign/Universal, but it is commented out. The web.xml is located in the WEB-INF folder of the WAR or EAR.

Cookies

The authentication to signoSign/Universal is specified in cookies. For operation in the iFrame, however, the signoSign/Universal cookie is requested from the surrounding web application. If the surrounding web application is running under a domain other than signoSign/Universal, this cookie must explicitly allow the access of external domains.

This behaviour is defined with the SameSite attribute of a cookie and must have the value Lax for iFrame operation. This can generally be configured on the server that is used.

Specially for Apache Tomcat, a context.xml is supplied in the META-INF folder of the signoSign/Universal WAR. The SameSite attribute is preset to Strict.

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 public-key certificate containing a public key. A complete key pair is required for the signing, that is, a public key certificate, its certificate chain 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:
To encrypt biometric data, signoSign/Universal is supplied with a certificate as standard that is created and managed by a notary. This provides the greatest possible security when dealing with sensitive signature data without you having to deal with key management. In the case of a dispute, the notary can be instructed to decrypt the biometric data. If you would prefer to manage the certificates yourself, please remember to adjust the configuration accordingly before using the system productively. More information is available directly from the signotec sales team.
The document is digitally signed with a demo certificate as standard that needs to be replaced by a trusted certificate for productive 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
        
    

Standard certificates
The global keystores signoSign/Universal uses by default are located next to the Properties file for the server settings. The keystores contain a key pair and a self-signed demo certificate for the digital signature and a certificate for encrypting the biometric data that is created and managed by a notary. See also the Certificates section.
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 certificate and its keys are only pre-set to Evaluation by signoSign/Universal and must be replaced by trusted data 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 stored 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 =
        
    

Migration

If a version is updated to with a greater second version number digit, it may be necessary to make changes to the database schema. For such cases, a command line tool is provided to which the currently used version, the version that is being migrated to and the connection data for the database are sent. The program then makes the changes to the database successively up to the desired version.

The tool is run as main class of the ssu-persistence-[VERSION]-with-dependencies.jar. This jar is located in the subfolder integration of the delivery package.

To run the tool, the following command can be used (Windows OS):

The tool queries all required parameters before the start. These are, in sequence:

1. Specification of the currently used version
2. Specification of the version that is being migrated to
3. Connection URL to the database
4. A user name for the database
5. A password for the specified user
6. The package name of the JDBC driver that is to be used
7. Specification of the SQL dialect to be used by Hibernate as package name

Further information on using the migration tool:

• The database user that is used requires the right to change tables of the signoSign/Universal schema.
• The parameters for the database connection can be found in the Hibernate configuration.