Configuration of document types

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

Structure of the JSON array in the document configuration file:

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

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

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

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.

[
     {        
         "documentIdTarget": "2"
     }        
]        

documentOriginTypes

This is a bit mask specified as an integer value between 1 and 31. This attribute makes it possible to apply configurations to documents with a specific origin.

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

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

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

signatureFieldMask

This is a key-value pair that determines which signature fields are displayed and available for signing to the calling user. The key here is the calling user name 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

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

signatureFields

Here you have the option of setting a field statically or dynamically. 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

Static signature field attributes

Dynamic signature field attributes

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

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

Form field attributes: general

Form field attributes: Signatures

Example:

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

Form field attributes: checkboxes

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 area of document configuration, you can influence the behaviour of documents when they are released or in a shared state. The following attributes are available.

Example:

[
    {
        "sharingCaseProperties":[
            {
                "completionCallbackURL":"https://signotec.com",
                "rejectable":true,
                "deferrable":false,
                "showDataProcessingAgreement": true,
                "dataProcessingAgreementTitle": "Title",
                "dataProcessingAgreementText": "Please <b>confirm<b>....",
                "autoSignStartMode": "NEVER"
            }
        ]
    }
]