Konfiguration¶

Im Ordner "config" befinden sich drei YAML-Dateien:

config_default.yml: Dient als Standard-Konfigurationsdatei und darf nicht gelöscht oder geändert werden.
config.yml: Diese Konfigurationsdatei dient zur benutzerspezifischen Konfiguration. Hier können Sie Ihren Stempelprozess konfigurieren. Sie können hierfür die Struktur einzelner Punkte aus der config_default.yml kopieren und entsprechend ändern und überschreiben.
config_bates_numbering.yml: Eine beispielhafte Konfiguration für ein Paginiersystem/Nummerierungssystem bzw. eine sogenannte Bates-Nummerierung. Sollten Sie keine Paginierung/Nummerierung benötigen, können Sie diese Konfigurationsdatei ignorieren. Weitere Details finden Sie in der Dokumentation zu Bates-Konfigurationen.

Sie können beliebig viele weitere YAML-Konfigurationsdateien anlegen, um z.B. verschiedene Stempelprozesse abzubilden. Eigene YAML-Konfigurationsdateien können mit dem Parameter -conf beim Start des QStamper-Services eingesetzt werden.

Nachfolgend werden die unterschiedlichen Einstellungsmöglichkeiten erläutert.

Zugangsdaten¶

In der Sektion licensing können die Zugangsdaten für Ihren QStamper-Benutzeraccount angegeben werden. Zudem können Sie einen eigenen Ordner für Ihre Lizenzdateien konfigurieren.

Beispiel config.yml

# licensing settings
licensing:
    # the email used to login on the licensing server
    email: 'info@qstamper.de'

    # the password used to login on the licensing server
    password: 'password'

emailpasswordlicense_file_dir

Datentyp: String
Beschreibung: E-Mail-Adresse um sich auf dem Lizenzserver einzuloggen.
erforderlich

Datentyp: String
Beschreibung: Password um sich auf dem Lizenzserver einzuloggen.
erforderlich

Datentyp: String
Beschreibung: Pfad des Ordners, der Ihre Lizenzdateien enthält.
optional, Standardwert: var\licenses

Allgemeine Einstellungen¶

Unter general können allgemeine, optionale Einstellungen für QStamper angepasst werden. Bei nur einem Stempelprozess sind in dieser Sektion normalerweise keinerlei Anpassungen bzw. individuelle Konfigurationen erforderlich.

Beispiel config.yml

# general settings
general:
    # path to a log file (does not have to exist)
    log_filename: var\log\core_log.log

log_filenametmp_dirtesseract_path

Datentyp: String
Beschreibung: Pfad zur Log-Datei für diese Konfiguration. Bei Verwendung mehrerer Konfigurationen wird empfohlen pro Konfiguration eine eigene Log-Datei zu verwenden.
optional, Standardwert: var\log\core_log.log

Datentyp: String
Beschreibung: Pfad zum temporärem QStamper-Verzeichnis.
optional, Standardwert: var\tmp

Datentyp: String
Beschreibung: Pfad zur OCR-Tesseract-Bibliothek, falls Sie eine andere Tesseract-Version als die mitgelieferte Version verwenden wollen.
optional, Standardwert: lib\tesseract-ocr

Service¶

Unter service kann der QStamper-Service konfiguriert werden.

Beispiel config.yml

# settings for the QStamper service
service:

    # a path to a hotfolder
    hotfolder: hotfolder

    # a path where the stamped files should be moved to
    output_folder: results

    # a path where the failed files should be moved to
    failed_folder: failed

    # a flag indicating whether the input file should be deleted or not
    delete_input_file: True

    # a path where the processed input files should be moved to (only relevant if delete_input_file is false)
    processed_folder: 

    # a flag indicating whether already existing files in the hotfolder should be processed or not (default: True)
    process_existing_files: True      

    # a flag indicating whether an alternative polling method should be used to observe the hotfolder, which can be 
    # useful if file events from the operating system (e.g. ionotify) are not reliable; for example, this may be the   
    # case if folders on mounted network drives are observed (default: False)
    hotfolder_polling: False

hotfolderoutput_folderfailed_folderdelete_input_fileprocessed_folderprocess_existing_fileshotfolder_polling

Datentyp: String
Beschreibung: Pfad zu Verzeichnis, in dem PDF-Dokumente automatisch bei Eingang verarbeitet und gestempelt werden.
optional, Standardwert: hotfolder

Datentyp: String
Beschreibung: Pfad zu Verzeichnis, in dem PDF-Dokumente nach erfolgreicher Bearbeitung abgelegt werden.
optional, Standardwert: results

Datentyp: String
Beschreibung: Pfad zu Verzeichnis, in dem PDF-Dokumente bei fehlerhaften Bearbeitung abgelegt werden.
optional, Standardwert: failed

Datentyp: Boolean
Beschreibung: Ein Boolean-Wert der definiert, ob ein eingehendes Dokument im Hotfolder gelöscht werden soll oder nicht.
optional, Standardwert: True

Datentyp: String
Beschreibung: Pfad zu Verzeichnis, in welches originale Dokumente nach der Verarbeitung verschoben werden soll (Nur relevant wenn delete_input_file: False ist).
optional

Datentyp: Boolean
Beschreibung: Ein Boolean-Wert, der festlegt, ob beim Start des QStamper-Services bereits vorhandene Dokumente im Hotfolder abgearbeitet werden oder nicht. Neu eingehende Dokumente im Hotfolder werden während der Verarbeitung bereits vorhandener Dokumente erkannt und verarbeitet sobald die bereits vorhandenen Dokumente abgearbeitet sind.
optional, Standardwert: True

Datentyp: Boolean
Beschreibung: Ein Boolean-Wert, der festlegt, ob zur Überwachung des Hotfolders ein Polling-Mechanismus verwendet werden soll. Dies kann hilfreich sein, falls Datei-Events vom Betriebssystem nicht zuverlässig ausgegeben werden. Das kann zum Beispiel der Fall sein, wenn ein Hotfolder auf einem Netzwerklaufwerk überwacht wird.
optional, Standardwert: False

Stempelprozess¶

In der Sektion stamper kann der Stempelprozess definiert werden.

Beispiel config.yml

# settings for the stamper process
stamper:
  # type of the stamp: 'qr' (default), 'code128', 'code39', 'image' or 'transparent'
  type: 'qr'

  # page selection (for documents with multiple pages, possible values: an integer as a string from '1' to 'n' or 'last')
  page: '1'
  # page selection fallback: always stamp the first page if the configured page does not exist (if set to false the process will fail if the configured page does not exist)
  first_page_fallback: true

  # page margins (integer, in mm)
  margin_top: 1
  margin_left: 1
  margin_bottom: 1
  margin_right: 1

  # custom stamp size (integer, in mm). For barcodes 'stamp_width' is ignored since the total stamp width is calculated dynamically. 
  # For auto sizing of 'image' stamps you can define only one dimension and set the other dimension to 0. Thus the dimension with the value 0 will be calculated automatically based on the other dimension.
  stamp_width: 
  stamp_height:

  # custom module width for barcodes (float, in mm, default: 0.35)
  stamp_barcode_module_width: 

  # custom padding for QR codes (float, in points, default: 1.75)
  stamp_qr_padding: 

  # image path for the stamp type 'image' (has to be a valid path if the type 'image' is selected)
  stamp_image_path:

  # image proportions are maintained by default with the stamp type 'image', set this to false if you want to distort the image with custom proportions defined by 'stamp_width' and 'stamp_height'
  stamp_image_keep_proportions: True

  # placement strategy ('best_fit_close_to_border', 'best_fit_biggest_area_close_to_border' or 'best_fit_biggest_area_centered')
  strategy: 'best_fit_close_to_border'

  # strategy options, which only apply to the strategy 'best_fit_close_to_border' ('best_fit_option_prefer_top' and/or 'best_fit_option_prefer_margin')
  strategy_options: 
    - 'best_fit_option_prefer_top'
    - 'best_fit_option_prefer_margin'

  # Overprinting enables placing the stamp in areas which are not completely free. Specifiying a value between 1 and 100 for 'overprint_area_max_percentage' enables overprinting 
  # and reduces the required free area by the given percentage (integer). For example, a value of 20 reduces the required free area by 20% to 80% of the stamp area.
  overprint_area_max_percentage: 0    

  # overprinting strategy (options: 'prefer_less_overprinting', which tries to prefer stamp areas with no or less overprinted content; 'ignore_overprinting_percentage', completely ignores the actual overprinted area; 
  # when no value is given, the actual overprinted area is only very weakly taken into account when positioning the stamp)
  overprinting_strategy: ''

  # content of the stamp (required for the stamp types 'qr', 'code128' and 'code39')
  content:
    # content provider ('static', 'cmd', 'filename', 'bates-numbering')
    provider: 'static'
    # configuration for the static content provider
    provider_static:
      content: 'Test'
    # configuration for the filename content provider
    provider_filename:
      # regex pattern to read the content of the stamp from the filename. if no pattern is set, the complete filename is used
      pattern: 'Lieferschein_(.*).pdf'
    # the name of a bates numbering configuration (string, default: empty, defined in the bates numbering configuration file and enabled under 'bates_numbering')
    provider_bates_numbering:     

  # prints the stamp content or a custom content as an additional label above, below or over the stamp
  additional_labels:
    # an additional label above the stamp (increases the height of the stamp, the width of the label is equal to the the stamp width)
    above:  
      # type of the label content ('custom', 'stamp_content' or empty for no additional label)
      type:
      # Custom content of the label, which applies only for the additional label type 'custom'.
      # Linebreaks can be added with \n, variables can be used with <:variable:> 
      # and the current date and time can be printed with qnow("%d.%m.%Y %H:%M:%S") using the 1989 C standard for date format
      custom_content: 
      # the font size of the additional label (float, default: 6.0)
      fontsize: 
      # the font of the text (string, e.g. "Symb" for Symbol, default "Helv" for Helvetica, for more information see the online documentation)
      text_font:          
      # color of the input text (string, hex color code, e.g. "#ff0000")
      text_color: 
      # the alignment of each text line (string, 'left', 'right' or 'center', default: 'center')         
      text_align: 
    # an additional label below the stamp (increases the height of the stamp, the width of the label is equal to the the stamp width)
    below:  
      # type of the label content ('custom', 'stamp_content' or empty for no additional label)
      type:
      # Custom content of the label, which applies only for the additional label type 'custom'.
      # Linebreaks can be added with \n, variables can be used with <:variable:> 
      # and the current date and time can be printed with qnow("%d.%m.%Y %H:%M:%S") using the 1989 C standard for date format
      custom_content: 
      # the font size of the additional label (float, default: 6.0)
      fontsize:  
      # the font of the text (string, e.g. "Symb" for Symbol, default "Helv" for Helvetica, for more information see the online documentation)
      text_font:          
      # color of the input text (string, hex color code, e.g. "#ff0000")
      text_color: 
      # the alignment of each text line (string, 'left', 'right' or 'center', default: 'center')         
      text_align: 
    # additional labels overlaying the stamp (do not effect the width or height of the stamp and can go beyond the stamp's borders)
    overlay:
      # name of the overlay label
      label-name:
        # type of the label content ('custom', 'stamp_content' or empty for no additional label)
        type:        
        # Custom content of the label, which applies only for the additional label type 'custom'.
        # Linebreaks can be added with \n, variables can be used with <:variable:> 
        # and the current date and time can be printed with qnow("%d.%m.%Y %H:%M:%S") using the 1989 C standard for date format
        custom_content:         
        # left position in points (float, default 0.0, relative to the left border of the stamp)
        left: 
        # top position in points (float, default 0.0, relative to the top border of the stamp)
        top: 
        # width in points (float, default: 10.0)
        width:         
        # height in points (float, default: 10.0)
        height:                
        # the font size of the additional label (float, default: 6.0)
        fontsize: 
        # the font of the text (string, e.g. "Symb" for Symbol, default "Helv" for Helvetica, for more information see the online documentation)
        text_font:          
        # color of the text (string, hex color code, e.g. "#ff0000")
        text_color: 
        # the alignment of each text line (string, 'left', 'right' or 'center', default: 'center')         
        text_align: 
        # background color (string, hex color code, e.g. "#ff0000", or empty for a transparent background)
        background_color: 
        # the border width in points (int, default 0)
        border_width:   
        # border color (string, hex color code, e.g. "#ff0000")
        border_color:       
        # top padding in points (float, default: 0.0)
        padding_top:       
        # left padding in points (float, default: 0.0)
        padding_left:          
    # variables which can be used within the custom_content string by using the format <:name-of-the-variable:>
    variables:
        # name of the variable
        my-variable:
          # type of the variable ('filename-regex' or 'stamp-content-regex')
          type:
          # value of the variable (e.g. a regular expression)
          value:

Allgemein¶

Art des Stempels:

type

Datentyp: String
Optionen: 'qr', 'code128', 'code39', 'image', 'transparent'
Beschreibung: Die Art des Stempels (QR-Code, Barcode vom Typ Code128, Barcode vom Typ Code 39, Bild oder ein transparenter Stempel ohne Inhalt).
Standardwert: 'qr'

Seite:

pagefirst_page_fallback

Datentyp: String
Beschreibung: Auswahl der Seite, welche gestempelt werden soll. Eine Nummer von '1' bis 'n' oder 'last', um die letzte Seite auszuwählen.
Standardwert: '1'

Datentyp: Boolean
Beschreibung: Ein Boolean-Wert, der definiert, ob automatisch die erste Seite gestempelt werden soll, falls die ausgewählte Seite unter page nicht existiert. Falls der Fallback nicht aktiv ist, scheitert der Stempelprozess wenn eine ausgewählte Seite nicht existiert. Der QStamper-Service wird bei einem einzelnen gescheiterten Stempelprozess nicht terminiert.
Standardwert: True

Rand, in dem nicht gestempelt wird:

margin_topmargin_leftmargin_bottommargin_right

Datentyp: Integer
Beschreibung: Abstand zum oberen Seitenrand in Millimeter, in dem nicht gestempelt wird.
Standardwert: 1

Datentyp: Integer
Beschreibung: Abstand zum oberen Seitenrand in Millimeter, in dem nicht gestempelt wird.
Standardwert: 1

Datentyp: Integer
Beschreibung: Abstand zum unteren Seitenrand in Millimeter, in dem nicht gestempelt wird.
Standardwert: 1

Datentyp: Integer
Beschreibung: Abstand zum rechten Seitenrand in Millimeter, in dem nicht gestempelt wird.
Standardwert: 1

Stempelgröße:

stamp_widthstamp_height

Datentyp: Integer
Beschreibung: Breite des Stempels in Millimeter (für Barcodes nicht relevant, da die Breite dynamisch auf Basis des Inhalts kalkuliert wird). Bei Verwendung der Stempelart 'image' kann für eine automatische Berechnung der Breite auf Basis der Höhe der Wert auf 0 gesetzt werden, wenn der Wert von stamp_height gleichzeitig gesetzt und größer als 0 ist.
optional, Standardwert abhängig von der Art des Stempels

Datentyp: Integer
Beschreibung: Höhe des Stempels in Millimeter. Bei Verwendung der Stempelart 'image' kann für eine automatische Berechnung der Höhe auf Basis der Breite der Wert auf 0 gesetzt werden, wenn der Wert von stamp_width gleichzeitig gesetzt und größer als 0 ist.
optional, Standardwert abhängig von der Art des Stempels

Konfiguration Barcodes:

stamp_barcode_module_width

Datentyp: Float
Beschreibung: Die Modulbreite von Barcodes in Millimetern. Die Modulbreite definiert die schmalste Breite eines Barcode-Moduls. Dieser Wert hat großen Einfluss auf die resultierende Gesamtbreite eines Barcodes.
optional, Standardwert: 0.35

Konfiguration QR-Codes:

stamp_qr_padding

Datentyp: Float
Default: 1.75
Beschreibung: Äußerer transparenter Rand für QR-Codes in Points. Verkleinert den sichtbaren Bereich eines QR-Codes.
optional, Standardwert: 1.75

Konfiguration Bildstempel:

stamp_image_pathstamp_image_keep_proportions

Datentyp: String
Beschreibung: Pfad zu einer Bilddatei für den Stempel-Typ 'image'. Muss ein valider Pfad sein, ansonsten scheitert der Stempelprozess. Der QStamper-Service wird bei einem einzelnen gescheiterten Stempelprozess nicht terminiert.
optional, Standardwert: 1.75

Datentyp: Boolean
Beschreibung: Ein Boolean-Wert, der für den Stempel-Typ 'image' definiert, ob das Seitenverhältnis des gestempelten Bildes erhalten werden soll. Setzen Sie diesen Wert auf False, falls Sie die Proportionen des gestempelten Bildes mit den Werten stamp_width und stamp_height beliebig verzerren wollen.
Standardwert: True

Platzierungsstrategie:

strategystrategy_options

Datentyp: String
Optionen: 'best_fit_close_to_border', 'best_fit_biggest_area_close_to_border', 'best_fit_biggest_area_centered'
Beschreibung: Platzierungsstrategie zum Aufbringen des Stempels. Die Strategie 'best_fit_close_to_border' präferiert Platzierungen nahe am Rand und in den Ecken. Die Strategie 'best_fit_biggest_area_close_to_border' bevorzugt ebenfalls Platzierungen nahe am Rand und in den Ecken, legt dabei jedoch mehr Wert darauf, dass um den Stempel herum mehr freie Flächen ohne Inhalt liegen. Die Strategie 'best_fit_biggest_area_centered' präferiert große freien Flächen ohne Inhalt und zentriert dabei den Stempel innerhalb der ausgewählten Fläche.
erforderlich, Standardwert: 'best_fit_close_to_border'

Datentyp: List
Optionen: 'best_fit_option_prefer_top', 'best_fit_option_prefer_margin'
Beschreibung: Weitere Optionen, um die Strategie 'best_fit_close_to_border' zu beeinflussen. Alle Optionen garantieren keine bestimmten Platzierungen, sondern sind abhängig von allen möglichen Platzierungen im Dokument und deren interne Bewertung durch den Platzierungsalgorithmus. Wenn die Option 'best_fit_option_prefer_top' gesetzt ist, werden Platzierungen am oberen Seitenrand gegenüber äquivalenten Platzierungen am unteren Seitenrand präferiert. Mit der Option 'best_fit_option_prefer_margin' werden hingegen Platzierungen bevorzugt, die möglichst viel Abstand zum Inhalt des Dokuments haben.

Überdrucken/Überstempeln von Inhalten:

Mit den folgenden Konfigurationsmöglichkeiten kann das Überdrucken/Überstempeln von Inhalten aktiviert werden, so dass Stempel auch in solchen Bereichen platziert werden, die nicht komplett frei sind.

overprint_area_max_percentageoverprinting_strategy

Datentyp: Integer
Beschreibung: Aktivierung des Überdruckens/Überstempelns und Bestimmung der maximal überdruckten Fläche relativ zum Stempel in Prozent. Die Angabe eines Wertes zwischen 1 und 100 aktiviert das Überdrucken/Überstempeln und reduziert die benötigte freie Fläche um den angegebenen Prozentsatz. Ein Wert von 20 verringert beispielsweise die erforderliche freie Fläche um 20% auf 80% der Stempelfläche.
optional, Standardwert: 0 (deaktiviert)

Datentyp: String
Optionen: 'prefer_less_overprinting', 'ignore_overprinting_percentage'
Beschreibung: Auswahl einer Überdrucken-Strategie. Die Strategie 'prefer_less_overprinting' präferiert Platzierungen mit gar keinen oder wenig überdruckten Flächen mit Inhalt. Die Strategie 'ignore_overprinting_percentage' ingoriert die tatsächlich überdruckte Fläche mit Inhalt komplett. Wenn kein Wert angegeben ist, wird die tatsächlich überdruckte Fläche bei der Positionierung des Stempels nur sehr geringfügig berücksichtigt.
optional

Inhalt¶

Unter content wird der Inhalt des Stempels definiert. Für QR-Codes und Barcodes muss ein Inhalt definiert werden.

provider

Datentyp: String
Optionen: 'filename', 'static', 'cmd', 'bates-numbering'
Beschreibung: Möglichkeiten um den Inhalt eines QR-Codes oder Barcodes zu definieren. Mit der Option 'filename' kann der Stempelinhalt mit Hilfe eines RegEx-Befehls über den Dateinamen generiert werden. Mit der Option 'static' kann ein statischer Inhalt über provider_static.content definiert werden. Bei der Option 'cmd' kann ein String beim Aufruf von QStamper mit dem Parameter -c bzw. --content übergeben werden. Mit der Option 'bates-numbering' kann der Zähler eines Paginiersystems/Nummerierungssystems als Stempelinhalt definiert werden. In diesem Fall muss für die Option provider_bates_numbering der Name einer validen Bates-Konfiguration angegeben werden.
erforderlich für QR-Code- und Barcode-Stempel

Statischer Inhalt¶

In der Sektion provider_static kann ein statischer Inhalt für den Stempel definiert werden.

content

Datentyp: String
Beschreibung: Statischer Stempelinhalt als String.

Dateiname¶

Unter provider_filename kann der Inhalt des Stempel über den Dateiname definiert werden. Mit Hilfe eines RegEx-Patterns können Werte aus dem Dateinamen als Stempelinhalt verwendet werden.

pattern

Datentyp: String
Beschreibung: RegEx-Befehl zur Konfiguration des Stempelinhalts aus dem Dateiname des Dokuments.

Paginierung (Bates)¶

Unter provider_bates_numbering kann eine Bates-Konfiguration, also die Konfiguration eines Paginiersystems/Nummerierungssystems angegeben werden. Diese Konfiguration muss sowohl im Stempelprozess unter bates_numbering ausgewählt/aktiviert und in der entsprechenden Konfigurationsdatei (standardmäßig config/bates_numbering_config.yml) definiert sein. Weitere Details finden Sie in der Dokumentation zu Bates-Konfigurationen.

provider_bates_numbering

Datentyp: String
Beschreibung: Name eines validen Paginier-/Nummerierungssystems (Bates-Konfiguration).

Zusätzliche Labels¶

In der Sektion additional_labels können zusätzliche, mehrzeilige Text-Labels mit dokumentenindividuellen Inhalten oberhalb, unterhalb oder innerhalb des Stempels platziert werden.

Überhalb¶

Mit above kann ein zusätzliches Labels überhalb des Stempels platziert werden.

Hinweise

Das Label überhalb des Stempels wird als Teil des Stempels integriert. Damit erhöht es die Gesamthöhe des Stempels, was sich auch auf die benötigte freie Fläche auswirkt. Die Breite des Labels entspricht der Breite des Stempels und hat keinen Einfluss auf die Gesamtgröße des Stempels.
Zu lange Textinhalte werden automatisch auf Basis der Stempelbreite umgebrochen und erhöhen die Gesamthöhe des Stempels.

typecustom_contentfontsizetext_fonttext_colortext_align

Datentyp: String
Optionen: 'custom', 'stamp_content'
Beschreibung: Typ des zusätzlichen Labels überhalb des Stempels. Bei Verwendung des Typs stamp_content wird der Inhalt des QR-Codes oder Barcodes überhalb des Stempels abgebildet. Mit dem Typ custom kann ein benutzerdefinierter Text über custom_content definiert werden.

Datentyp: String
Beschreibung: Benutzerdefinierter Inhalt des Labels überhalb des Stempels (nur für Typ custom). Zeilenumbrüche können mit \n und Variablen mit <:variable:> hinzugefügt werden. Das aktuelle Datum sowie die aktuelle Uhrzeit können mit qnow("%d.%m.%Y %H:%M:%S") unter Verwendung des 1989 C Standards für Datumsformate in das Label eingefügt werden. Falls im Stempelprozess unter bates_numbering Paginier-/Nummerierungssysteme (Bates-Konfigurationen) aktiviert und in einer entsprechenden Konfigurationsdatei definiert sind, können deren aktuelle Zähler mit qbates("name-der-bates-konfiguration") in das Label eingefügt werden.

Datentyp: Float
Beschreibung: Schriftgröße für das Label.
optional, Standardwert: 6.0

Datentyp: String
Optionen: Siehe Schriftarten.
Beschreibung: Die Schriftart für das Label.
optional, Standardwert: 'Helv'

Datentyp: String
Beschreibung: Die Schriftfarbe für das Label als hexadezimaler Farb-Code.
optional, Standardwert: '#000000' (schwarz)

Datentyp: String
Optionen: 'left', 'right', 'center'
Beschreibung: Die horizontale Textausrichtung des Labels.
optional, Standardwert: 'center'

Unterhalb¶

Mit below kann ein zusätzliches Labels unterhalb des Stempel platziert werden.

Hinweise

Das Label unterhalb des Stempels wird als Teil des Stempels integriert. Damit erhöht es die Gesamthöhe des Stempels, was sich auch auf die benötigte freie Fläche auswirkt. Die Breite des Labels entspricht der Breite des Stempels und hat keinen Einfluss auf die Gesamtgröße des Stempels.
Zu lange Textinhalte werden automatisch auf Basis der Stempelbreite umgebrochen und erhöhen die Gesamthöhe des Stempels.

typecustom_contentfontsizetext_fonttext_colortext_align

Datentyp: String
Optionen: 'custom', 'stamp_content'
Beschreibung: Typ des zusätzlichen Labels unterhalb des Stempels. Bei Verwendung des Typs stamp_content wird der Inhalt des QR-Codes oder Barcodes überhalb des Stempels abgebildet. Mit dem Typ custom kann ein benutzerdefinierter Text über custom_content definiert werden.

Datentyp: String
Beschreibung: Benutzerdefinierter Inhalt des Labels unterhalb des Stempels (nur für Typ custom). Zeilenumbrüche können mit \n und Variablen mit <:variable:> hinzugefügt werden. Das aktuelle Datum sowie die aktuelle Uhrzeit können mit qnow("%d.%m.%Y %H:%M:%S") unter Verwendung des 1989 C Standards für Datumsformate in das Label eingefügt werden. Falls im Stempelprozess unter bates_numbering Paginier-/Nummerierungssysteme (Bates-Konfigurationen) aktiviert und in einer entsprechenden Konfigurationsdatei definiert sind, können deren aktuelle Zähler mit qbates("name-der-bates-konfiguration") in das Label eingefügt werden.

Datentyp: Float
Beschreibung: Schriftgröße für das Label.
optional, Standardwert: 6.0

Datentyp: String
Optionen: Siehe Schriftarten.
Beschreibung: Die Schriftart für das Label.
optional, Standardwert: 'Helv'

Datentyp: String
Beschreibung: Die Schriftfarbe für das Label als hexadezimaler Farb-Code.
optional, Standardwert: '#000000' (schwarz)

Datentyp: String
Optionen: 'left', 'right', 'center'
Beschreibung: Die horizontale Textausrichtung des Labels.
optional, Standardwert: 'center'

Overlay / Innerhalb¶

Mit overlay können beliebig viele zusätzliche Labels innerhalb des Stempel platziert werden. Solche sogenannten Overlay-Labels überlagern den restlichen Stempel-Inhalt und werden relativ zum linken oberen Eck des Stempels positioniert.

Hinweise

Overlay-Labels haben keinen Einfluss auf die Höhe oder Breite des Stempels und können über den Rand des Stempels hinausgehen. Dabei besteht bei falscher Konfiguration die Gefahr, dass Inhalte des Dokuments überdruckt werden.
Wenn der Textinhalt größer als die Höhe und Breite des Overlay-Labels ausfällt, wird der Text nicht dargestellt. Ein automatischer Zeilenumbruch, wie bei den zusätzlichen Labels oberhalb und unterhalb erfolgt nicht.

Zur Erstellung eines Overlay-Labels muss ein YAML-Schlüssel mit einem beliebigen alphanumerischen Namen im overlay-Objekt definiert werden. Die Konfiguration des Overlay-Labels erfolgt mit den folgenden Schlüssel-Wert-Paaren innerhalb des selbst definierten YAML-Objekts.

Beispiel-Konfiguration Overlay-Labels

# prints the stamp content or a custom content as an additional label above, below or over the stamp
additional_labels:
    # additional labels overlaying the stamp (do not effect the width or height of the stamp and can go beyond the stamp's borders)
    overlay:
        # name of the overlay label
        my-organization:
            # type of the label content ('custom', 'stamp_content' or empty for no additional label)
            type: 'custom'       
            # Custom content of the label, which applies only for the additional label type 'custom'.
            # Linebreaks can be added with \n, variables can be used with <:variable:>, 
            # the current date and time can be printed with qnow("%d.%m.%Y %H:%M:%S") using the 1989 C standard for date format
            # and a bates numbering counter can be added with qbates("name-of-the-bates-numbering-configuration")
            custom_content: 'Beispielfirma GmbH'        
            # left position in points (float, default 0.0, relative to the left border of the stamp)
            left: 10.0
            # top position in points (float, default 0.0, relative to the top border of the stamp)
            top: 8.0
            # width in points (float, default: 10.0)
            width: 60.0        
            # height in points (float, default: 10.0)
            height: 10.0               
            # the font size of the additional label (float, default: 6.0)
            fontsize: 8.0
            # the font of the text (string, e.g. "Symb" for Symbol, default "Helv" for Helvetica, for more information see the online documentation)
            text_font: 'hebo'         
            # color of the text (string, hex color code, e.g. "#ff0000")
            text_color: '#cdcdcd'
            # the alignment of each text line (string, 'left', 'right' or 'center', default: 'center')         
            text_align: 'left'
            # the border width in points (int, default 0)
            border_width: 1  
            # border color (string, hex color code, e.g. "#ff0000")
            border_color: '#000000'       
            # top padding in points (float, default: 0.0)
            padding_top:  2.0     
        invoice-number:
            # type of the label content ('custom', 'stamp_content' or empty for no additional label)
            type: 'custom'       
            # Custom content of the label, which applies only for the additional label type 'custom'.
            # Linebreaks can be added with \n, variables can be used with <:variable:> 
            # and the current date and time can be printed with qnow("%d.%m.%Y %H:%M:%S") using the 1989 C standard for date format
            custom_content: 'Rechnungsnummer: <:invoice-number:>'        
            # left position in points (float, default 0.0, relative to the left border of the stamp)
            left: 10.0
            # top position in points (float, default 0.0, relative to the top border of the stamp)
            top: 16.0
            # width in points (float, default: 10.0)
            width: 60.0        
            # height in points (float, default: 10.0)
            height: 10.0               
    # variables which can be used within the custom_content string by using the format <:name-of-the-variable:>
    variables:
        # name of the variable
        invoice-number:
            # type of the variable ('filename-regex' or 'stamp-content-regex')
            type: 'stamp-content-regex'
            # value of the variable (e.g. a regular expression)
            # returns the invoice number without the prefix (examplary invoice number: "RE-123123")
            value: '(?<=RE-)\d+'

typecustom_contentlefttopwidthheight

Datentyp: String
Optionen: 'custom', 'stamp_content'
Beschreibung: Typ des Overlay-Labels. Bei Verwendung des Typs stamp_content wird der Inhalt des QR-Codes oder Barcodes überhalb des Stempels abgebildet. Mit dem Typ custom kann ein benutzerdefinierter Text über custom_content definiert werden.

Datentyp: String
Beschreibung: Benutzerdefinierter Inhalt des Overlay-Labels (nur für Typ custom). Zeilenumbrüche können mit \n und Variablen mit <:variable:> hinzugefügt werden. Das aktuelle Datum sowie die aktuelle Uhrzeit können mit qnow("%d.%m.%Y %H:%M:%S") unter Verwendung des 1989 C Standards für Datumsformate in das Label eingefügt werden. Falls im Stempelprozess unter bates_numbering Paginier-/Nummerierungssysteme (Bates-Konfigurationen) aktiviert und in einer entsprechenden Konfigurationsdatei definiert sind, können deren aktuelle Zähler mit qbates("name-der-bates-konfiguration") in das Label eingefügt werden.

Datentyp: Float
Beschreibung: Relative Positionierung des Labels zum linken Rand des Stempels in Points.
optional, Standardwert: 0.0

Datentyp: Float
Beschreibung: Relative Positionierung des Labels zum oberen Rand des Stempels in Points.
optional, Standardwert: 0.0

Datentyp: Float
Beschreibung: Breite des Labels in Points.
optional, Standardwert: 10.0

Datentyp: Float
Beschreibung: Höhe des Labels in Points.
optional, Standardwert: 10.0

Hinweis zur Breite und Höhe von Overlay-Labels

Wenn der Textinhalt größer als die Höhe und Breite des Overlay-Labels ausfällt, wird der Text nicht dargestellt. Ein automatischer Zeilenumbruch, wie bei den zusätzlichen Labels oberhalb und unterhalb des Stempels erfolgt nicht.

fontsizetext_fonttext_colortext_alignbackground_colorborder_widthborder_colorpadding_toppadding_left

Datentyp: Float
Beschreibung: Schriftgröße für das Label.
optional, Standardwert: 6.0

Datentyp: String
Optionen: Siehe Schriftarten.
Beschreibung: Die Schriftart für das Label.
optional, Standardwert: 'Helv'

Datentyp: String
Beschreibung: Die Schriftfarbe für das Label als hexadezimaler Farb-Code.
optional, Standardwert: '#000000' (schwarz)

Datentyp: String
Optionen: 'left', 'right', 'center'
Beschreibung: Die horizontale Textausrichtung des Labels.
optional, Standardwert: 'center'

Datentyp: String
Beschreibung: Die Hintergrundfarbe für das Label als hexadezimaler Farb-Code (leer für transparenten Hintergrund).
optional

Datentyp: Integer
Beschreibung: Breite des Rahmens für das Label (0 für keinen Rahmen).
optional, Standardwert: 0

Datentyp: String
Beschreibung: Die Farbe des Rahmens für das Label als hexadezimaler Farb-Code.
optional, Standardwert: '#000000' (schwarz)

Datentyp: Float
Beschreibung: Innerer Abstand des Textinhalts zum oberen Rand des Labels in Points zur Feinjustierung der Darstellung/Positionierung.
optional, Standardwert: 0.0

Datentyp: Float
Beschreibung: Innerer Abstand des Textinhalts zum linken Rand des Labels in Points zur Feinjustierung der Darstellung/Positionierung.
optional, Standardwert: 0.0

Variablen¶

In der Sektion variables können zusätzliche Variablen definiert werden. Variablen können innerhalb von custom_content mit <:name-of-the-variable:> benutzt werden.

typevalue

Datentyp: String
Optionen: 'filename-regex', 'stamp-content-regex'
Beschreibung: Typ der Variable. Mit Hilfe von RegEx-Befehlen können Sie beim Typ filename-regex Werte aus dem Dateinamen als Variablen definieren und in den custom_content Ihrer Labels einfügen. Analog dazu können mit dem Typ stamp-content-regex Werte aus dem Stempelinhalt als Variablen definiert werden.

Datentyp: String
Beschreibung: Wert der Variable (z.B. ein RegEx-Befehl)

Formularfelder / PDF-Widgets¶

Über widgets können beliebig viele interaktive Eingabefelder, sogenannte PDF-Widgets, innerhalb des Stempels platziert werden. Diese Eingabefelder können digital in einem PDF-Viewer oder automatisiert im weiteren Prozess ausgefüllt werden. Eingabefelder überlagern den restlichen Stempel-Inhalt und werden relativ zum linken oberen Eck des Stempels positioniert.

Aktuell werden Text-Eingabefelder und Checkboxen unterstützt.

Zur Erstellung eines Formularfeldes muss ein YAML-Schlüssel mit einem beliebigen alphanumerischen Namen im widgets-Objekt definiert werden. Dieser Name kann anschließend bei einer automatisierten Verarbeitung mit dem Prefix q: referenziert werden (Beispiel: q:name-of-my-checkbox). So können eingegebene Werte aus den Formularfeldern ausgelesen werden.

Die Konfiguration der Formularfelder erfolgt mit den folgenden Schlüssel-Wert-Paaren innerhalb des selbst definierten YAML-Objekts.

Beispiel-Konfiguration Formularfelder / PDF-Widgets

 # add PDF widgets/form fields relative to the left top corner of the stamp
widgets: 
    # name of the widget (can be referenced using the prefix "q:", e.g. "q:my-widget")
    name-worker:
        # type of the widget (string, 'text' or 'checkbox')
        type: 'text'
        # left position in points (float, default 0, relative to the left border of the stamp)
        left: 65.0
        # top position in points (float, default 0, relative to the top border of the stamp)
        top: 96.0
        # width in points (float)
        width: 94.0
        # height in points (float)
        height: 11.0      
        # label (string)
        label: 'Name in Druckbuchstaben' 
        # value (string)
        value: 'Max Mustermann'
    # name of the widget (can be referenced using the prefix "q:", e.g. "q:my-widget")
    special-service-checkbox:
        # type of the widget (string, 'text' or 'checkbox')
        type: 'checkbox'
        # left position in points (float, default 0, relative to the left border of the stamp)
        left: 88.35
        # top position in points (float, default 0, relative to the top border of the stamp)
        top: 57.5
        # width in points (float)
        width: 9.8
        # height in points (float)
        height: 9.75  
        # label (string)
        label: 'Spezialleistung durchgeführt'

Allgemein¶

Text-Eingabefelder¶

Die folgenden Einstellungen gelten nur für Text-Eingabefelder und werden für Checkboxen ignoriert.

text_maxlentext_fonttext_fontsizetext_color

Datentyp: Integer
Beschreibung: Maximale Zeichenlänge des Eingabetextes (standardmäßig unbeschränkt).
optional

Datentyp: String
Optionen: Siehe Schriftarten.
Beschreibung: Die Schriftart des Eingabetextes und Platzhalters.
optional, Standardwert: 'Helv'

Datentyp: Float
Beschreibung: Schriftgröße des Eingabetextes und Platzhalters (variabel je nach PDF-Viewer, wenn nicht definiert).
optional

Datentyp: String
Beschreibung: Die Schriftfarbe für das Label als hexadezimaler Farb-Code.
optional, Standardwert: '#000000' (schwarz)

Auswahl Paginierung (Bates)¶

Unter bates_numbering können Paginier-/Nummerierungsysteme (Bates-Konfigurationen) für diesen Stempelprozess ausgewählt werden. Die angegebenen Namen der Bates-Konfigurationen müssen in einer entsprechenden, separaten Konfigurationsdatei (standardmäßig config/bates_numbering_config.yml) definiert sein. Weitere Details finden Sie in der Dokumentation zu Bates-Konfigurationen.

Alle hier ausgewählten Bates-Konfigurationen werden bei jedem erfolgreichen Stempelprozess inkrementiert, auch wenn der Wert/die Nummer des Paginier-/Nummerierungssystems im Stempel nicht ausgegeben wird. Hiervon ausgenommen sind Paginier-/Nummerierungssysteme (Bates-Konfigurationen), die über ihre Konfiguration deaktiviert sind.

Im Folgenden Beispiel werden die zwei Bates-Konfigurationen 'default' und 'incoming-invoices' für den Stempelprozess aktiviert.

Beispiel-Konfiguration zur Auswahl von Bates-Konfigurationen

# configure bates numbering which can be used within the stamp content, the additional labels and the widgets (currently only one number per document is supported)
bates_numbering:
    # the name of the bates numbering configurations used in the stamping process defined by this configuration file (string, default: 'default', you can use multiple
    # bates numbering configurations which have to be defined in the bates numbering configuration)
    configurations: 
        - 'default'  
        - 'incoming-invoices'

configurationsconfig_filedatabase_dir

Datentyp: List
Beschreibung: Namen von Paginier-/Nummerierungssystemen (Bates-Konfigurationen), die in der entsprechenden Konfigurationsdatei (standardmäßig config/bates_numbering_config.yml) definiert sein müssen. Die Zähler aller hier aufgeführten Bates-Konfigurationen werden bei jedem erfolgreichen Stempelprozess erhöht, insofern die Bates-Konfiguration nicht in der entsprechenden Konfigurationsdatei deaktiviert ist.

Datentyp: String
Beschreibung: Der Pfad zur Konfigurationsdatei, in der Paginier-/Nummerierungsysteme (Bates-Konfigurationen) definiert sind.
optional, Standardwert: 'config\config_bates_numbering.yml'

Datentyp: String
Beschreibung: Der Pfad zu einem Ordner, in dem die JSON-Datenbanken der Paginier-/Nummerierungsysteme (Bates-Konfigurationen) gespeichert werden sollen.
optional, Standardwert: 'var\bates'

Geschützter Bereich¶

Unter protected_area kann ein geschützter Bereich definiert werden, in dem nie gestempelt wird.

Beispiel-Konfiguration geschützter Bereich

# settings for a protected area 
protected_area:

    # the position of the protected area ('top_left', 'top_right', 'bottom_left', 'bottom_right')
    position: 

    # the width of the protected area in millimeters
    width:

    # the height of the protected area in millimeters
    height:

positionwidthheight

Datentyp: String
Option: 'top_left', 'top_right', 'bottom_left', 'bottom_right'
Beschreibung: Die Position des geschützten Bereichs.

Datentyp: Integer
Beschreibung: Die Breite des geschützten Bereichs in Millimeter.

Datentyp: Integer
Beschreibung: Die Höhe des geschützten Bereichs in Millimeter.

Erweiterte Einstellungen¶

In der Sektion advanced können fortgeschrittene Einstellungen konfiguriert werden. Diese Einstellungen können weitreichende Auswirkungen haben und sollten nur nach Rücksprache angepasst werden.

Beispiel config.yml

# advanced settings: do not touch if you don't know what you're doing
advanced:

  # preprocessing: upscaling factor, heavily influences the performance and has also an impact on OCR
  preprocessing_upscaling_factor: 6

preprocessing_upscaling_factorkernel_heightkernel_width

Datentyp: Integer
Beschreibung: Im Preprocessing von Dokumenten wird das Dokument hochskaliert, um besser Inhalte erkennen zu können, die nicht überstempelt werden sollen. preprocessing_upscaling_factor bestimmt den Faktor der Skalierung und beeinflusst stark die Performance sowie die Verarbeitungsdauer von Dokumenten. Der Wert sollte nur angepasst werden, wenn QStamper auf Geräten mit geringer CPU-Performance verwendet wird oder falls Probleme bei der Erkennung von Inhalten auftreten.
Standardwert: 6

Datentyp: Integer
Beschreibung: Höhe des Kernels in Points. Wird zur Erkennung von freien Flächen verwendet.

Datentyp: Integer
Beschreibung: Breite des Kernels in Points. Wird zur Erkennung von freien Flächen verwendet.

Schriftarten¶

Es können z.B. für zusätzliche Labels oder Formularfelder / PDF-Widgets verschiedene Schriftarten verwendet werden. Diese eingebetten Schriftarten müssen von jedem PDF-Viewer unterstützt werden.

Die folgende Tabelle gibt einen Überblick über die möglichen Schriftarten, deren Bezeichner und Abkürzungen, die zur Bestimmung der Schriftart in der Konifugration verwendet werden können.

Method	Description
`courier`	Courier
`courier-oblique`	Courier-Oblique
`courier-bold`	Courier-Bold
`courier-boldoblique`	Courier-BoldOblique
`helvetica`	Helvetica
`helvetica-oblique`	Helvetica-Oblique
`helvetica-bold`	Helvetica-Bold
`helvetica-boldoblique`	Helvetica-BoldOblique
`times-roman`	Times-Roman
`times-italic`	Times-Italic
`times-bold`	Times-Bold
`times-bolditalic`	Times-BoldItalic
`symbol`	Symbol
`zapfdingbats`	ZapfDingbats
`helv`	Helvetica
`heit`	Helvetica-Oblique
`hebo`	Helvetica-Bold
`hebi`	Helvetica-BoldOblique
`cour`	Courier
`coit`	Courier-Oblique
`cobo`	Courier-Bold
`cobi`	Courier-BoldOblique
`tiro`	Times-Roman
`tibo`	Times-Bold
`tiit`	Times-Italic
`tibi`	Times-BoldItalic
`symb`	Symbol
`zadb`	ZapfDingbats