Configuration of document types | signotec Knowledge Base

A document type is a set of rules for documents with certain common characteristics. For example, you can define that when a document with the name pattern ’*_contract.pdf’ is opened, a signature field is always created at position X/Y on page Z. Document types are therefore rules and behaviors for specific documents.

Document types can be provided system-wide as a file in JSON format using the setting persistence.pathToDocumentConfigFile.
They can be set individually for each user via the REST API with the appropriate permissions.
They can be set for all users of a tenant via the REST API.

On a technical level, there is always a document configuration behind a document type, also referred to as DocumentConfiguration (see also under ’Schemas’ in the Swagger UI).
However, a document configuration can also be used in other places to determine the behavior of documents in certain cases.

For example, a document configuration can be transferred when sharing a document in order to influence automatic saving or to determine a form field assignment in a workflow.

Document configuration

This article explains the technical structure of a document configuration. The use cases were discussed in the previous article. Both in a file and in the REST API, the document configuration is always transferred in JSON format. The following section describes how to set up a document configuration using the example of a file provided for the setting persistence.pathToDocumentConfigFile.

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 loading a document, 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.

Structure of the JSON array in the document configuration file:

JSON

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

This applies if the specified character string matches the file name of the document to be loaded. The asterisk symbol (*) acts as a wildcard character here.

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

JSON

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

documentIdPattern

This applies if the specified character string matches the document ID of the document to be loaded. The asterisk symbol (*) acts as a wildcard character here.

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

JSON

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

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

documentIdTarget

This applies if the specified character string matches the document ID of the document to be loaded.

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

JSON

[
     {        
         "documentIdTarget": "2"
     }        
]

documentOriginTypes

This refers to a bit mask and is specified as an integer value between 1 and 31. Here, the attribute allows configurations to be applied to documents of certain origins.

The following values exist:

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

Example: A configuration that is applied to templates and imported documents

JSON

[
     {        
         "documentOriginTypes": 9
     }        
]

Configuration attributes

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

allowedSigningMethods

This attribute specifies the permitted signing methods for a document. The signatureFieldProperties element can be used to further restrict these methods for each signature field.

Example: A configuration that allows signing exclusively via touch and electronic pen.

JSON

[
     {        
         "allowedSigningMethods": ["PEN","TOUCH"]
     }        
]

signatureFieldMask

These are key-value pairs that determine which signature fields are displayed and available for signing to the calling user. In this case, the key is the calling username to which the mask is to apply. The value is a character string and contains identifiers for signature fields that are separated by a semicolon (;). An identifier for signature fields consists of either a page number and tab order or the technical signature field name.

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

JSON

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

signatureFields

Here you have the option of setting a field to static or dynamic. The attribute is a JSON array. This can contain dynamic ("@type":"dynamic",) and static ("@type":"static",) signature fields. Static signature fields are positioned in the document using fixed parameters. Dynamic signature fields can be positioned in the document relative to a position of text. Each signature field comprises a number of attributes. These consist of general and type-dependent attributes.

General signature field attributes

Attribute	Description	Range of values
@type	Defines the type of the signature field	`‘dynamic,‘ ‘static‘`
option	0 = position does not have to be signed. 1 = position must be signed. (Mandatory field)	`1, 0`
width	Defines the width of the signature field.	`Integer > 0`
height	Defines the height of the signature field.	`Integer > 0`
signer	Defines the name of the signature field.	`String`

Static signature field attributes

Attribute	Description	Range of values
posX	Horizontal position of the signature field. 0 corresponds to the upper edge of the page.	`Integer >= 0`
posY	Vertical position of the signature field. 0 corresponds to the left-hand edge of the page.	`Integer >= 0`
pageNumber	The number of the page on which the signature field is placed. 1 corresponds to the first page.	`Integer > 0`

Dynamic signature field attributes

Attribute	Description	Range of values
offsetX	Horizontal offset of the signature field based on the position of the keyword text in the document.	`Integer`
offsetY	Vertical offset of the signature field based on the position of the keyword text in the document.	`Integer`
keyword	Search term (character string). The PDF document is searched for this search term and the coordinates of the first hit location are returned. It must be an individual character string (without spaces) and must be surrounded by double inverted commas. All pages are searched.	`String`
recursive	A Boolean value that determines whether only the first occurrence of the <keyword> text is assigned a signature field or all occurrences of the text.	`true, false`

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.

JSON

[
    {        
      "signatureFields":[
         {
            "@type":"static",
            "option":0,
            "signer":"signer",
            "posX":500,
            "posY":20,
            "width":200,
            "height":50,
            "pageNumber":1
         },         
         {
            "@type":"dynamic",
            "option":0,
            "signer":"string",
            "offsetX":20,
            "offsetY":45,
            "width":200,
            "height":50,
            "keyword":"searchtext",
            "recursive":false
         }
      ]
    }        
]

formFieldProperties

This attribute is a JSON array. It defines additional behavior for individual or groups of form fields of certain types. It consists of general and type-dependent attributes.

Form field attributes: general

Attribute	Description	Range of values
@type	Specifies the type of the form field for which the additional properties are to be applied.	`‘signature,‘ ‘checkbox,‘` `‘formfield‘`
fieldName	Specifies the form field to which the defined properties should be applied. An asterisk (`*`) can be used as a wildcard to address multiple fields at once.	`String`
tabOrder	The tab order value of the form field for which the additional properties are to be applied. The tab order begins with 0.	`Integer`
pageNumber	The page number of the form field to which the additional properties are to be applied. The page number begins with 1.	`Integer > 0`
shown	This defines whether the field in question should be displayed when the document is loaded. If only certain fields are displayed due to the configuration, all other fields in the document are automatically hidden—and vice versa. This rule only includes elements that have the `shown` attribute set.	`true, false`

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

Form field attributes: signatures

Attribute	Description	Range of values
allowedSigningMethods	Specifies the permitted signing methods for this signature field.	A list with the following possible values `MOUSE, TOUCH, PEN, PAD, SIGNME, CLICK`
confirmationText	A text that a signatory must confirm before they can sign. When using a signotec signing device, the text is displayed on the screen before the signature is made. The appropriate length of the text varies depending on the model. Texts that are too long are truncated.	`String`

Attribute

Description

Range of values

allowedSigningMethods

Specifies the permitted signing methods for this signature field.

A list with the following possible values

MOUSE, TOUCH, PEN, PAD, SIGNME, CLICK

confirmationText

A text that a signatory must confirm before they can sign.

When using a signotec signing device, the text is displayed on the screen before the signature is made. The appropriate length of the text varies depending on the model. Texts that are too long are truncated.

String

Example:

JSON

[
    {
        "formFieldProperties":[
            {
                "@type":"signature",
                "fieldName":"string",
                "tabOrder":0,
                "pageNumber":0,
                "shown":true
                "confirmationText":"Lorem ipsum dolor sit amet, consetetur sadipscing elitr."
            }
        ]
    }
]

Form field attributes: Checkboxes

Attribute	Description	Range of values
padSelectionSignatureField	signoPAD API/Web (version 1.4.1 and later) allows you to transfer checkboxes to a hardware pad so you can set them there. This field lets you define whether the checkbox is to be inserted via the signature device and in front of which signature field. A signature field is specified either via the signature field name or page number and tab order. The process takes place together with the first signature if an empty character string is transferred. Checkboxes connected to a signature field in this way are no longer inserted into the document in a destructive way when it is saved. Checkboxes connected to a signature are saved incrementally together with the corresponding signature. In addition, the form field information of this type of checkbox is also included in the encrypted signature data themselves.	`String`
padSelectionText	If a checkbox for setting on a hardware pad is to be defined, it is necessary to also transfer a text to be displayed together with the checkbox on the signature device. The possible length of the text is dependent on the signature device used as the specified text is scaled on the display. In other words: The more text to be displayed, the smaller the font. If several checkboxes are defined for a signature, they will appear on the display together, if possible. If this is not possible for technical reasons, the entries will be spread over multiple pages. ‘\n’ is used for a line break in the text.	`String`
checkRequiredToSignSignatureField	A signature field can also be specified here, just as it can for the padSelectionSignatureField value. The corresponding checkbox must be ticked to be able to start the signing process for the specified signature field. The procedure described for the first signing process applies if an empty character string is specified. If this checkbox is also configured for entry on a hardware pad, the validation process to determine whether the corresponding checkbox is ticked only runs after confirmation has been given in the dialog box on the hardware pad.	`String`
checkRequiredToSignSignatureFieldText	If the checkRequiredToSignSignatureField value has been defined, this value is displayed as a notification in the Viewer and the signing process is canceled if the corresponding checkbox has not been ticked.	`String`
showIndex	An index that determines the sequence for displaying the checkbox on the pad.	`Integer`

Example:

JSON

[
    {
        "formFieldProperties":[
            {
                "@type":"checkbox",
                "fieldName":"CheckBoxFormFIELD",
                "tabOrder":0,
                "pageNumber":0,
                "padSelectionSignatureField":"signFIELD",
                "padSelectionText":"Lorem ipsum dolor sit amet, consetetur.",
                "checkRequiredToSignSignatureField":"signFIELD",
                "checkRequiredToSignSignatureFieldText":"Lorem ipsum dolor sit amet",
                "showIndex":0
            }
        ]
    }
]

sharingCaseProperties

In this area of the document configuration, you can influence the behavior of documents when they are released or shared. The following attributes are available.

Attribute	Description	Range of values
completionCallbackURL	A URL to which the client navigates when the user has completed the process. The user has no choice as to whether to remain in the document or download the document once the process is complete.	A URL as a `string`
rejectable	Determines whether the process can be rejected by the recipient. If a process is rejected, it is no longer considered active and cannot be accessed again via the URL.	`boolean`
deferrable	Determines whether the recipient can save the process without rejecting it or whether it is rejected. A temporarily saved process is still considered active.	`boolean`
showDataProcessingAgreement	This setting defines whether the recipient of a process is shown a dialog box before processing, which must be confirmed before the document can be processed. The confirmation is stored in the document’s audit log. If rejection (`rejectable`) of the process is permitted, the dialog can be canceled and the user can read the document. Any attempt to edit the document will bring up the dialog box again. If rejection is permitted, Cancel is replaced by Reject and immediately calls up the Reject dialog box.	`boolean`
dataProcessingAgreementTitle	Defines the title of the dialog box controlled by `showDataProcessingAgreement`.	`String`
dataProcessingAgreementText	Defines the text of the dialog controlled by `showDataProcessingAgreement`. The text may contain HTML. The HTML used is cleaned up before use.	`String`, HTML possible.
autoSignStartMode	Automatically starts the signing process when the shared document is opened. See also the setting persistence.automatedSignStartMode.	`NEVER`, `FIRST_FIELD`, `FIRST_MANDATORY_FIELD`, `NAMED_FIELD`
autoSignStartFieldName	Defines the name of the signature field used to automatically start the signature when `autoSignStartMode` = `NAMED_FIELD`.	`String`
mailSubject	Sets the subject of the email when the user shares a document. If this property is not specified, the system uses the default text for the subject.	`String`
mailMessage	Sets the message of the email when the user shares a document. The text may contain HTML. The HTML is cleaned up before sending. If this property is not set, the system uses the default text for the email message.	`String`, HTML possible.
mailSignatureText	Sets the signature of the email when the user shares a document. The text may contain HTML. The HTML is cleaned up before sending. If this property is not set, the system uses the default text for the email signature.	`String`, HTML possible.

Rejecting and temporarily saving processes can also be controlled globally by persistence.documentSharingRejectable and persistence.persistencedocumentSharingDeferrable.

You can set a placeholder for the sender of the email with {USERNAME} for both the email message and the email signature. This placeholder is then replaced by the document owner’s username.

Example:

JSON

[
    {
        "sharingCaseProperties":[
            {
                "completionCallbackURL":"https://signotec.com",
                "rejectable":true,
                "deferrable":false,
                "showDataProcessingAgreement": true,
                "dataProcessingAgreementTitle": "Title",
                "dataProcessingAgreementText": "Please <b>confirm<b>....",
                "autoSignStartMode": "NEVER",
                "mailSubject": "Subject",
                "mailMessage": "Hello,<br/>this can be <b>HTML<b>....",
                "mailSignatureText": "Best regards,<br/>{USERNAME}"
            }
        ]
    }
]