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, including structure and documentation, can be found in the Swagger UI.

The API is divided into the following areas:

• Using the Viewer

• Managing persistent documents

• Managing shared documents

• Managing keystores

• Managing workflows

The individual areas will be discussed in greater detail later.

General explanatory information

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, comparable to an API key. It must be provided as an authorisation means each time a protected REST endpoint is called and acts 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 gained independently of a session using the instance token. In most cases, it is assumed that there is a single Viewer in a container, but it is also possible to have multiple Viewers in a container.

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

Viewer:
Viewers are always part of a container. They provide a context into which a document can be loaded. In most use cases, it is assumed that a container contains a single Viewer. However, it is possible that a container may potentially contain multiple Viewers.

Loading a document:
A document is always loaded into a Viewer. The document remains loaded until it is actively unloaded, the instance token is revoked or the associated session expires.

Session expiry:
A session depends on the timeout defined in web.xml. The default setting is 60 minutes. External calls to shared documents are an exception. Your session will automatically end after 10 seconds when you exit the Viewer.

Access URL:
An access URL is a single-use URL that connects a session to a Viewer container. It is always issued for a specific Viewer. Calling up an access URL automatically establishes a connection between the session being used and the corresponding Viewer container. An access URL should be created immediately before use, as it is automatically destroyed after use to ensure maximum security.

Recommendations:
An instance token is an important access key to a user’s context on the server. To ensure smooth and secure operation, we recommend the following best practices when handling 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 allocation.

Consistent allocation of instance tokens and sessions:
A session should not be linked to different instance tokens. It is important that a session only uses one instance token at a time during its lifetime to avoid inconsistent states or access problems.

Active unloading of documents:
Once a process has been completed, documents should be actively unloaded to free up 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

The concept for using the Viewer is defined as such that an instance is...

• generated – by requesting an instancetoken.

• prepared – by loading documents or making 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

Calling the Viewer

A Viewer generated through an API can only be accessed via a URL that can be retrieved with a call to the API. This access URL is a URL to signoSign/Universal containing a generated character string that grants one-time authorised access to the Viewer. When calling, the session of the calling client is logged in using the access data with which the instancetoken was also requested. The client remains logged in until an explicit logout is carried out or the instancetoken is revoked. Calling the URL automatically invalidates this. Please also note that any number of URL can be created for an instance.

Managing persistent documents

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.

The API provides the following functions here:

• persisting a document

• deleting n documents

• querying binary data of a document

• querying metadata of n documents

• querying all subprocesses of a document

Managing shared documents (sharing cases)

Shared documents can also be managed via the API.

The API provides the following functions here:

• creating new sharing cases

• querying 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)

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.

This concept has two steps:

• Uploading a keystore containing the necessary certificates.

• Assigning certificates to a user within a keystore with a certain purpose.

Certificate purposes:
Assigning a certificate to a user always serves a specific 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.

The API provides the following functions here:

• uploading a keystore

• deleting a keystore

• creating an assignment of a certificate to a user with a certain purpose

• querying assignments

• querying all assignments to a user

• adjusting an assignment

• deleting an assignment

User roles and the ownerId

Some functions have a parameter ownerId. 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 the rights ssu.user.documents, ssu.tenant.users and/or ssu.tenants.users.

If the ownerId parameter is left empty, it will be assumed that this value is the name of the user making the request. If a user without the appropriate permissions passes the parameter and it does not correspond to the name of the executing user, an access violation occurs.

Querying detailed document information

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

The resource GET /Viewer/document/information is used for this purpose.

The following information can be retrieved:

• 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

HTTP status codes

The REST API generally uses standard codes. An important paradigm concerns the handling of the codes 403-Forbidden and 404-Not Found. To prevent users from discovering external resources by trial and error, the API usually returns the status 403 instead of 404.
In individual cases, proprietary codes are used 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 process and the data used in it are defined in a plan (blueprint), which can then be started as often as required.

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. A blueprint has a revision number. When a process is started, this is saved together with the process. If the blueprint is then changed, the revision number of the blueprint is increased, but not that of the process, to allow interim changes to the blueprint to be recognised. Deleting a blueprint deletes the steps and all processes. Blueprints that are linked to an active process cannot be deleted. Blueprints are always assigned to a user and also have the following properties:

• The revision number is increased whenever changes are made to the blueprint.

• The HIDDEN flag, which controls whether the blueprint is listed when all available blueprints are retrieved.

• The AUTODELETE flag, which controls whether the blueprint is deleted once the last process of the blueprint has been deleted.

Blueprint steps

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

Actions

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

• DEMAND_SIGNATURE
  A document folder is shared via email. The documents can be opened and signed via a link in the email in signoSign/Universal Viewer.
  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 defines when the step is to be executed. 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 defines that the steps with this stepIndex should be executed afterwards. A step with stepIndex == N is only executed once all steps with nextStepIndex == N have been completed. Steps that are not blocked by a nextStepIndex attribute are started when the blueprint is launched.

Placeholders in blueprints

When defining a blueprint, specific values can also be replaced by placeholders. To do this, simply replace the specific value with a keyword that begins and ends with ‘@@’. For example, the name of a recipient can be replaced by ‘@@RECIPIENT@@’.

For documents, the placeholder flag is used to indicate that this document must be transferred in order to start a process.

Document folders

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

By default, 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.

The endpoint for starting a process requires

• name: Name of the process. Does not have to be unambiguous.

• parameters: A map containing all placeholders used in the blueprint and their specific values.

• documents: This is a list of documents that have been defined as placeholders in the blueprint. The allocation is made via the file name. For the placeholder document ‘abc.pdf’, a document named ‘abc.pdf’ must therefore be included in the list.