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

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

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.

Audit logs

signoSign/Universal offers logging for documents and workflows. The audit logs contain various types of information on changes in the document or workflow. This information remains saved in the database regardless of the document or workflow. The audit logs for the documents and workflows can be called via the REST API.

User Management

User management is not performed directly within the application itself, but two different approaches are available.

The first approach is to configure OIDC (OpenID Connect) within the application. This allows the users to be managed through the corresponding provider, where user roles and permissions are defined by an external identity provider.

Alternatively, users can be provided through the server's security realm. In this case, user information and access rights are directly managed on the server. In both cases, users must be assigned appropriate roles in order to use the application.

For user management, the REST resources Users or User are available. These resources enable various actions, such as modifying user settings or retrieving data necessary for the operation of the application. It is also possible to delete users. However, it should be noted that deleting a user only resets their user account and does not prevent them from continuing to use the application.

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

Settings – web

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 from which the signoSign/Universal application can be accessed by the server. This URL is used in particular for REST calls that do not need to be implemented from a public interface. They reduce public traffic and facilitate load balancing.

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 the 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 signing 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. 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 signing 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.

legacySignatureImage

This setting specifies whether capturing a signature via the signoPAD API/Web generates a raster or a vector graphic and incorporates it into the PDF.

accentColor

This setting specifies the accent colour for the document pool, the Viewer and e-mails sent by the server.

favicon

This setting specifies the favicon for the document pool.

logo

This setting specifies the logo for the document pool and e-mails sent by the server.

dynamicSignatureStrokes

Specifies whether signatures are captured with dynamic or constant stroke widths.

web.proposeNewViewer

This setting controls the option for the user to try an experimental version of the viewer when opening it, which is currently in a testing phase.

web.documentSharingLeaveUrl

This setting controls which URL the user is redirected to as soon as a shared document is exited.

web.defaultViewer

This setting determines whether the new or the old viewer is to be used as the default.

web.postSaveAction

Defines an additional action that is performed after saving a document.

Settings – business

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.

Settings – persistence

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

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. If no URL to go back to is defined, the Back button is not displayed. When the URL is called, two parameters are attached.

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.

documentSharingRejectable

Setting whether shared documents can be rejected by the recipients or not. In the event of a rejection, the recipient must specify a reason, which is communicated to the sender by e-mail, if a valid SMTP configuration present.

documentSharingDeferrable

Setting whether shared documents can be saved by recipients without finalising them. The process is not finalised or ended and can be called up again at a later time.

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.

mailTemplatesLocation

Setting to define the directory of the mail templates.

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.

Passwords

The following settings are available for custom setting of the desired password policy.

passwords.length

Setting for specifying the minimum length for entered passwords

passwords.requireDigit

The setting specifies whether passwords need to contain numbers.

passwords.requireUppercase

The setting specifies whether passwords need to contain upper case letters.

passwords.requireLowercase

The setting specifies whether passwords need to contain lower case letters.

passwords.requireSpecial

The setting specifies whether passwords need to contain special characters.

passwords.allowedSpecialCharacters

Setting for specifying the permitted special characters.

allowedAuthenticationMethods

Setting for specifying the permitted authentication methods.

Settings – hibernate

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.

Settings – deployment

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
• Process debug page

pool

Determines whether signoSign/Universal provides a frontend for managing documents. If the server is running, the pool application can be found under ../signoSignUniversal/pool

Settings – restapi

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.

Settings – smtp

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.

sender

An e-mail address that is used as sender for all e-mails sent by signoSign/Universal.

Settings – ltv

The long term validation (LTV) settings for signatures.

A signature without LTV requires an online service of the certificate issuer 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.

Settings – tsa

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.

Settings – jobs

The following settings determine the behaviour of jobs in signoSign/Universal.

Please note:
If documentLifeTimeInterval is set, documentLifeTimeCreation and/or documentLifeTimeModification must also be set. The same applies vice versa.
The document is always deleted at the earliest possible point in time.

documentLifeTimeInterval

This setting determines the interval at which a check is performed to see which documents need to be deleted.

documentLifeTimeCreation

This setting determines the duration in days that must have passed since the document was created at the time of the check in order for a document to be deleted.

documentLifeTimeModification

This setting determines the duration in days that must have passed since the document was last edited at the time of the check in order for a document to be deleted.

Settings – pool

The following settings determine the behaviour of the ‘signoSign/Universal Document Pool’ application.

preferredSmsService

The preferred service provider for sending text messages.

sendMailMethodForDocumentSharing

Specifies whether an e-mail is sent via the set SMTP server of transferred to the local e-mail client via mailto .

allowSameSharingAndTanMethod

Specifies whether the same method can be used for sharing TAN and recipients.

showUserSettings

Decides whether or not the user settings feature is displayed in the pool.

showDocumentTypes

Decides whether or not the document types feature is displayed in the pool.

whiteList

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

Settings – SMS

signoSign/Universal uses an external service for sending text messages. This section describes the setting of the supported services that you can use.
See also pool.preferredSmsService

Settings – sms77

The following settings are used to call the text message service of sms77 e. K.

apiKey

The API key for authentication of the text message service provider. You can create and display this key in the development area of sms77.io.

label

The label is attached to the SMS to make it easier to assign to statistics. Placeholders can be used to be able to use certain information in the label.

• {USER_INDENT} : This placeholder get replaced by the username of the person that started the sharingcase or workflow.
• {DOCUMENT_ID} : This placeholder gets replaced by the document ID of the document.
• {SC_ID} : This placeholder gets replaced by the ID of the sharingcase.
• {SC_COMMENT} : This palceholder gets replaced by the comment of the sharingcase.
• {WF_ID} : This placeholder gets replaced by the ID of the workflow.
• {ACCESS_ID} : This placeholder gets replaced by the access ID of the sharingcase or workflow.

Settings – sipgate

The following settings are used to call the text message service of sipgate GmbH.

token

The personal access token (PAT) for authentication of the text message service provider. The token requires the scope sessions:sms:write for sending text messages and the scope sms:read for reading out the extension this is to be used.
See also https://www.sipgate.io/rest-api/authentication#personalAccessToken.

tokenId

The token ID of the personal access token for authentication of the text message service provider.

smsId

The ID of the extension from which the message is sent.
See also https://github.com/sipgate-io/sipgateio-sendsms-java#web-sms-extensions.

Settings telekom

The following settings are used to call the text message service of Deutsche Telekom AG.

apiKey

The API key for authentication of the text message service provider. You can create and display this key in the development area of vonage.

secret

The secret for authentication of the text message service provider. You can create and display this key in the development area of vonage.

sender

The sender that is used when sending the SMS and is displayed to the recipient.

client-ref

The client-ref is attached to the SMS to make it easier to assign to statistics. Placeholders can be used to be able to use certain information in the client-ref.

• {USER_INDENT} : This placeholder get replaced by the username of the person that started the sharingcase or workflow.
• {DOCUMENT_ID} : This placeholder gets replaced by the document ID of the document.
• {SC_ID} : This placeholder gets replaced by the ID of the sharingcase.
• {SC_COMMENT} : This palceholder gets replaced by the comment of the sharingcase.
• {WF_ID} : This placeholder gets replaced by the ID of the workflow.
• {ACCESS_ID} : This placeholder gets replaced by the access ID of the sharingcase or workflow.

account-ref

The account-ref is attached to the SMS to make it easier to assign to statistics. Placeholders can be used to be able to use certain information in the account-ref.

• {USER_INDENT} : This placeholder get replaced by the username of the person that started the sharingcase or workflow.
• {DOCUMENT_ID} : This placeholder gets replaced by the document ID of the document.
• {SC_ID} : This placeholder gets replaced by the ID of the sharingcase.
• {SC_COMMENT} : This palceholder gets replaced by the comment of the sharingcase.
• {WF_ID} : This placeholder gets replaced by the ID of the workflow.
• {ACCESS_ID} : This placeholder gets replaced by the access ID of the sharingcase or workflow.

Settings – auth

The following settings are used to configure the authentication of users. As standard, the authentication mechanism of the servlet container or application servers is used. Alternatively, Single Sign On (SSO) with OpenID Connect (OIDC) can be used.

Please note:

• Mobile apps for Android and iOS are not compatible with Single Sign On. Use the setting auth.type = REALM to used signoSign/Universal via the apps.
• The setting of the key web.ssmPublicUrl is essential for use of Single Sign On.

type

Specifies the type of authentication.

realm.forceLowerCaseUsername

If this setting is activated, the user name is case-insensitive. Users "John Smith" and "john smith" share the same data in the system, such as documents. Both users can log in, however, as long as the log-in mechanism allows this, but signoSign/Universal uses the lower case user name internally.

This setting should be activated if the log-in mechanism ignores upper/lower case.

oidc.discoveryUrl

The URL of the OpenID provider metadata of the identity server . The URL generally ends with /.well-known/openid-configuration .

oidc.clientId

The identifier that signoSign/Universal is registered with for the identity server. An application that uses OpenID Connect must be registered with the identity server. This identifier will then be issued and it is needed for the authorisation code flow.

oidc.clientSecret

The secret specified with the identity server that signoSign/Universal uses for the authorisation code flow.

oidc.scope

The scope values that are used for the authorisation code flow. For the fundamental functionality, OpenID Connect requires the value openid .

oidc.usernameClaim

The value (claim) in the token from which the user name is taken. If the value is not present or is empty, it is not possible to log in to signoSign/Universal.

oidc.rolesClaim

The value (claim) in the token from which the user roles are taken. If the value is not present in the token, is empty or is not a JSON array, it is not possible to log in to signoSign/Universal.

oidc.tokenAudience

From the perspective of the identity server, signoSign/Universal is a resource. The OAuth access token is always issued for a resource. This setting can be used to specify a list of valid resources. The signoSign/Universal REST API will only accept the access token if its aud claim value is included in this list. The check is deactivated if no value has been specified.

Important
If the signoSign/Universal REST API is availably publicly, specifying this list is strongly recommended for security reasons. The public REST API should always check whether an access token was issued for the API.

oidc.tokenIssuer

A list of additional trustworthy access token issuers. The issuer from the OpenID provider metadata is always trustworthy. The signoSign/Universal REST API will only accept access tokens if their iss claim value is known.

Settings – remoteSignature

To sign a document in signoSign/Universal using remote signature, the service signotec signoRemoteSignature is required. The connection to the service is established with the following settings. If the settings are not configured, remote signatures are deactivated.

service.baseUrl

This setting determines the service that is to be used for the remote signature.

service.licenseKey

This setting sets the licence key for using the signoRemoteSignature service.

Settings – logging

The following settings configure the logging of the signoSign/Universal application. See also web.clientDebugLogging.

Default settings

If no external settings are used, the Java Logging API (java.util.logging) is used to log to the console with level INFO by default.

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

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

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

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

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

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

config.file

This property can be used to specify a local path of an external configuration file for the Standard Java Logging API (java.util.logging). If this property is not set or if it is empty, the default configuration file logging.properties contained in signoSign/Universal is used.

Example external logging settings

The following example expands the standard settings by logging to a file with the java.util.logging.FileHandler .

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

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

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

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

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

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

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

Configuration - redisson

In order to run the application on a Tomcat server with Redis as the Session Storage, specific configuration steps are required. This configuration needs to be done both within the application itself and on the Tomcat server.

Please note that this feature is currently in an experimental phase and may be subject to changes.

Providing configuration for the application:
It is necessary for the application to have a configuration file provided in either JSON or YAML format. This file contains specific settings for the application, including information for connecting to the Redis instance. Documentation on the content of the configuration file can be found here: https://github.com/redisson/redisson/wiki/2.-Configuration#272-sentinel-yaml-config-format.

Tomcat configuration:
The configuration for Tomcat is best described here: https://redisson.org/articles/redis-based-tomcat-session-management.html

redission.YamlConfigFile / redission.jsonConfigFile

This setting refers to a configuration file for the Redisson API, which can be specified using a relative or absolute path. The configuration file defines the settings and parameters for the Redisson library. Detailed documentation on the file format and available configuration options can be found at the following link: https://github.com/redisson/redisson/wiki/2.-Configuration/.

Settings webhooks

External systems can be informed about specific events in signoSign/Universal via Webhooks. For each type of event, a URL can be defined, which will be called upon the occurrence of the event.

For more detailed information about Webhooks, please refer here.

documentUpdatedEndpoint

This event is triggered when a save operation has been performed. This includes Remote-Saving and the completion of shared documents.

The EventType of the event is: DOCUMENT_UPDATED

documentSharedEndpoint

This event is triggered when a document is shared or when the operation is created.

The EventType of the event is: DOCUMENT_SHARED

workflowProcessStartedEndpoint

This event is triggered when a Workflow Process is started.

The EventType of the event is: WORKFLOW_PROCESS_STARTED

workflowProcessEndedEndpoint

This event is triggered when a Workflow Process is ended. It doesn't matter if the process is aborted or completed.

The EventType of the event is: WORKFLOW_PROCESS_ENDED

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 sharing case is considered completed when the recipient has either finalised or rejected the document. As soon as the recipient opens the document, they can finalise it using the "Finish" button. The only requirement is that all mandatory fields are signed. If the document does not contain any mandatory fields, the recipient can also finalise the document without a signature. If the current configuration allows it, a recipient can also reject a document by stating a reason.

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.

Reject a sharing case

The rejection of documents can either be activated globally via the configuration or for specific documents via a corresponding document type.

Saving a sharing case

It is possible to give the recipient of a shared document the option of continuing to edit the document at a later date. To do this, the document is not finalised but saved temporarily. Caching can be activated either globally via the configuration or for specific documents via a corresponding document type.

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.

Document configuration

The document configuration 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
                        }
                    ]
            }
        ]
        

sharingCaseProperties

In this section of the document configuration, you can influence the behavior of documents during sharing or in a shared state. The following attributes are available.

• Rejecting and deferring operations can also be controlled globally by persistence.documentSharingRejectable and persistence.persistencedocumentSharingDeferrable.

Example:

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

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.

General Information for Understanding

This technical documentation explains the terms and concepts related to instance tokens, sessions, containers, viewers, and access URLs.

Instance Token:
An instance token is a unique string, similar to an API key. It needs to be provided as an authorization method with each request to a protected REST endpoint and serves as an access key to a container.

Container:
A container describes the context of a user on the server. Access to a container can be independent of a session using the instance token. In most cases, it is assumed that a single viewer exists in a container, but it is also possible to have multiple viewers in a container.

Session:
A session describes the browsing context of a browser with the server. It represents the interaction of a user with the application during a specific period of time.

Viewer:
Viewers are always part of a container. They provide a context in which a document can be loaded. In most use cases, it is assumed that a container contains a single viewer. However, it is possible for a container to potentially have multiple viewers.

Loading a Document:
A document is always loaded into a viewer. The document remains loaded until it is actively unloaded, the timeout from the setting web.idleTimeout is reached, the instance token is revoked, or the associated session expires.

Expiration of the session:
A session depends on the timeout specified in web.xml. The default setting is 60 minutes. External calls of shared documents are an exception. Your session ends automatically after 10 seconds when you exit the viewer.

Access URL:
An access URL is a one-time usable URL that connects a session with a viewer container. It is always issued for a specific viewer. By accessing an access URL, the used session is automatically associated with the corresponding viewer container. An access URL should be created immediately before use as it is automatically destroyed after use to ensure maximum security.

An instance token is an important access key to the context of a user on the server. To ensure smooth and secure operation, we recommend the following best practices when working with instance tokens:

Creation of Instance Tokens:
An instance token should always be created for a session. It is advisable to generate an instance token for each session to enable clear mapping.

Consistent Mapping of Instance Tokens and Sessions:
A session should not be associated with different instance tokens. It is important that a session uses only one instance token at a time during its runtime to avoid inconsistent states or access issues.

Active Unloading of Documents:
After completing an operation, documents should be actively unloaded to release resources and reduce memory consumption. This can be done either by manually unloading the document or by revoking the associated instance token.

By following these recommendations, you can ensure consistent and efficient use of instance tokens and avoid potential issues related to session management and document loading.

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 ideally 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 one instancetoken. The Viewers of a second instancetoken can only be opened once 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 uses proprietary codes in addition to standard codes to enable special cases to be handled.

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 makes it possible to send a loaded document directly to another system via HTTP. The URL can be set via PATCH /viewer/configuration with the parameter saveUrl and will then change the saving function in the Viewer. Information about the status of the signature fields is attached with the following URL parameter when a request is made.

• sf: Number of signed fields
• usf: Number of non-signed fields
• smf: Number of signed mandatory fields
• usmf: Number of non-signed mandatory fields
• index (optional): Optional index of the viewer that can be set beforehand via PUT /viewer/meta/index

The following points must be taken into account by the receiving side:

• It must be able to accept a multipart upload (content type: multipart/form-data)
• The PDF is transferred in the field saveFile.
• The external system 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" }

  or alternatively

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

• 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 (POST /viewer/cookie) 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.

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:

SSUSignatureStartEvent

Triggered once a signature process has been started.

Default behaviour:
The signing dialog box is opened.

PreventDefault():
Opening of the signing dialog box is prevented.

SSUFormFieldFocusEvent

Triggered when a form field is focused on.

Default behaviour:
The addressed form field is focused on.

PreventDefault():
Focusing on the form field is prevented.

SSUDocumentLoadedEvent

Triggered once the document is ready/has been loaded in the Viewer. No parameters are transferred to this event.

SSUPageNumberChangeEvent

Triggered if another page in the document is changed to.

Webhooks

Webhooks are a way to be notified about specific events in signoSign/Universal. To achieve this, a URL is provided that signoSign/Universal calls when an event occurs. The content of each webhook call is a JSON object that maps the context in which the event occurred. Depending on the context, the amount of information transmitted varies. For example, when a user saves a document, no SharingCase information is transmitted. However, if the save is part of a Workflow, the Workflow information is transmitted.

In the webhooks section of the settings, you can define a separate URL for each possible event.

Webhook Content

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

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.

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 migration-tool-[VERSION].jar. This jar is located in the subfolder migration 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.
• The used database must be started to enable the migration to be performed. This means that if SSU is used in the preset state, SSU must be started to enable the H2 database to run.

Health check URL

To check the accessibility of the application, the end point:

can be addressed. It returns "HTTP200/ OK" if the application is not available.