Invoice Squeeze Anbindung

Beschreibt die Anbindung von Squeeze für Invoice

• Einrichtung der Verbindung zu Squeeze
• Einrichtung einer sicheren https Verbindung
• Mögliche Fehlerquellen
• Anpassung von Farben der Markierungen

Einrichtung der Verbindung zu Squeeze

• Allgemein

Damit Squeeze in Invoice verwendet werden kann, muss zunächst die Verbindung zu Squeeze eingerichtet werden. Die passenden Konfigurations hierfür befindet sich in der Administrations-Outbar in der Sub-Outbar "Allgemein" unter "Verbindung"-> "Squeeze" bzw. in der Outbar "Squeeze" unter "Verbindung":

Erst wenn in dieser Konfiguration alle Daten valide sind, können Order wie z.B. "Dokumentenklassen" verwendet werden. Vorher ist ein Zugriff auf Daten aus Squeeze nicht möglich.

 

Konfigurationsfelder

Wichtig: Nach jeder Änderung in der Konfiguration muss der Browser-Cache einmal gelöscht werden, da es ansonsten sein kann, dass der Browser falsche Daten im Speicher hat und Funktionalitäten von Squeeze nicht aufgerufen werden können

Squeeze-URL

Gibt die URL zu Squeeze an. Entspricht der URL über welche die normale Squeeze-Oberfläche aufgerufen werden kann (mit "http://" aber ohne "/main.php").

Squeeze-Api-Key

Ohne einen gültigen API-Key kann nicht auf Squeeze nicht zugegriffen werden. Ein API-Key kann über den Button "Neuen API-Key erzeugen" generiert werden, wenn URL, Login und Passwort angegeben wurden.

Squeeze-Login / Passwort

Benutzer und Passwort werden lediglich für die API-Key Generierung benötigt. Die Angaben werden nicht gespeichert und werden beim nächsten Öffnen der Konfiguration wieder leer angezeigt.

Mappentyp (x) und Feldname für Training (x)

Gibt ein Mapping an, welches Feld aus welchem Mappentypen für das Training verwendet werden soll. Die Angabe des Mappentyps entspricht dem technischen Namen in Documents. Der Feldname entspricht dem technischen Feldnamen in dem entsprechenden Mappentypen.

In der Standardauslieferung können die Angaben für zwei Mappentypen  vorgenommen werden. Für den Fall, dass es mehr als zwei Mappentypen gibt, welche mit Squeeze kommunizieren, kann die Anzahl an konfigurierbaren Mappentypen über die Eigenschaft "gadgetConfig" am Documents-Order ("SqueezeGeneralConfig" bzw. "Admin_Squeeze_Configuration") über den Eintrag "trainingFields" verändert werden.

Die maximale Anzahl der konfigurierbaren Mappings ist derzeit auf 20 begrenzt.

 

Funktionalitäten

Neuen API-Key erzeugen

Ein gültiger API-Key wird benötigt, damit die Squeeze-Konfigurationsoberflächen, sowie der Viewer angezeigt werden können. Damit ein neuer API-Key erzeugt werden kann, muss auf das Oberfläche zunächst eine gültige Squeeze-URL, ein Squeeze-Nutzer und und ein Passwort für diesen Nutzer angegeben werden:

Anschließend muss der Knopf "Neuen API-Key erzeugen" gedrückt werden. Wenn die Anmeldedaten korrekt sind, erscheint folgende Meldung:

Bei nicht erfolgreichen Meldung erscheint eine entsprechende Fehlermeldung.

Nach der Erstellung eines neuen API-Keys muss der Cache der Browsers einmal gelöscht werden!

Verbindung prüfen

Über den Knopf "Verbindung prüfen" kann die Verbindung nach Squeeze testet werden. Dafür wird eine gültige URL, sowie ein gültiger API-Key benötigt. Nutzername und Passwort sind für diese Funktionalität nicht notwendig.

Wenn der Test erfolgreich ist, erscheint folgende Meldung:

Wenn die Konfigurationsoberflächen von Squeeze nicht angezeigt werden können, aber der Verbindungstest erfolgreich ist, sollte der Cache des Browsers einmal gelöscht werden.

Einrichtung einer sicheren https Verbindung

Voraussetzungen

Es wird ein Zertifikat und ein privater Schlüssel im PEM-Format (BASE64 kodierte Zeichenkette) benötigt.

Außerdem muss das Zertifikat mit mindestens dem SHA-256 Signaturalgorithmus signiert sein.

All major webrowser vendors ceased acceptance of SHA-1 SSL certificates in 2017.

Microsoft has discontinued SHA-1 code signing support for Windows Update in August 7, 2020.

- Wikipedia (SHA-1)

Ein Zertifikatsspeicher (PFX / PKCS#12) kann ebenfalls verwendet werden.
Dazu muss das Zertifikat in seine Einzelteile (Zertifikat, privater Schlüssel und ggf. der Zertifikatskette) zerlegt werden.

Extraktion eines PFX-Zertifikatsspeicher

Am Ende der Voraussetzungen, steht mindestens das Zertifikat und der private Schlüssel zur Verfügung.
Ein Beispiel eines Zertifikats:

Sobald die Dateien vorliegen kann mit der Einrichtung des Virtuellen Hosts begonnen werden.

Konfiguration Webserver

httpd-vhosts.conf - Konfiguration

Das Zertifikat, den privaten Schlüssel des Zertifikats sowie eine etwaige Zertifikatskette unter dem Apache Konfigurationsordner SQUEEZE\apache\conf\ssl ablegen.

httpd-vhosts.conf - Konfiguration

Der virtuelle Host für den SSL Port *:443 muss in der Datei SQUEEZE\apache\conf\extra\httpd-vhosts.conf eingetragen werden.

Die vhosts.conf Konfiguration muss in der httpd.conf geladen werden, damit die vhosts in der Konfiguration des Webserver berücksichtigt werden (bei SQUEEZE bereits eingerichtet).

<VirtualHost *:443>
  ServerName host.domain.net
  ServerAdmin admin@host.domain.net
  ServerSignature Off
  SSLEngine on
  SSLCertificateFile "conf/ssl/server.crt"
  SSLCertificateKeyFile "conf/ssl/server.key"
  SSLCertificateChainFile "conf/ssl/fullchain.pem"
  # DER FOLGENDE TEIL WIRD NUR BEI EINEM PROXY BENÖTIGT
  # SSLProxyEngine On
  # SSLProxyVerify none
  # SSLProxyCheckPeerCN off
  # SSLProxyCheckPeerName off
  # SSLProxyCheckPeerExpire off
</VirtualHost>

Die Pfade zum Zertifikat, den privaten Schlüssel des Zertifikats sowie eine etwaige Zertifikatskette sind entsprechend zu setzen.

Der host.domain.net  Wert ist durch den entsprechenden Hostnamen zu ersetzen.

Zuletzt den Virtuellen Host (VirtualHost *:80) auskommentieren.

httpd.conf - Konfiguration

Der Webserver muss nun auf den SSL (HTTPS) Port hören.

Dies stellen wir in der Date apache\conf\httpd.conf ein.

#
# Listen: Allows you to bind Apache to specific IP addresses and/or
# ports, instead of the default. See also the <VirtualHost>
# directive.
#
# Change this to Listen on specific IP addresses as shown below to
# prevent Apache from glomming onto all bound IP addresses.
#
#Listen 12.34.56.78:80
Listen 80
Listen 443

Weiter unten in der Konfigurationsdatei müssen wir noch das SSL Modul suchen und dieses einkommentieren.

LoadModule ssl_module modules/mod_ssl.so

Troubleshooting

Die Seite kann auf den Clients nicht aufgerufen werden?

Handelt es sich um eine Intranet-Domäne (*.local bspw.), dann muss die Server FQDN (URL) (https://servername.domäne) in den Internetoptionen der Clients bei den Intranetsites hinzugefügt werden. Sollte dies nicht funktionieren, ist die Seite bei den Vertrauenswürdigen Sites unterzubringen.

Seit den Windows Servern 2019 (und Windows 10) sind die TCP Ports 443, 8443 in der Firewall standardmäßig nicht freigegeben.

Dazu sind also entsprechende eingehende und ausgehende Firewallregeln zu definieren.

Extraktion eines PFX - Zertifikatsspeicher

Wenn das Zertifikat, die Zertifikatskette sowie der private Schlüssel (ohne Passphrase) für den Apache Webserver als Zertifikatsspeicher (PFX / PKCS#12) vorliegt, kann diese Batch (ohne jegliche Gewährleistung) ausgeführt werden, um an die notwendigen Einzelteile zu gelangen.

Dazu werden die OpenSSL Binaries benötigt (seit SQUEEZE 1.10 ausgeliefert).

Setzen der Batch-Variablen

Es müssen im Batch-Script die folgenden Variablen gesetzt werden, damit das Script fehlerfrei arbeiten kann.

SET OPENSSL=D:\DEXPRO\TOOLS\OPENSSL\openssl.exe

SET PFXFILE=D:\DEXPRO\ZERTIFIKATE\ORIGINALS\KUNDENZERTIFIKAT.pfx
SET OUTPUTFOLDER=D:\DEXPRO\ZERTIFIKATE\OUT\
SET OUTPUTFILENAME=KONVERTIERTES_KUNDENZERTIFIKAT

SET REMOVEPASSPHRASE=true

Dabei werden die Pfade zu OpenSSL, dem Ausgabeordner und dem PFX Zertifikatsspeicher (PFX), sowie die Namen der zu erstellenden Zertifikatsbestandteile angegeben. Damit der private Schlüssel von etwa dem Apache Webserver gelesen werden kann, muss der private Schlüssel ohne PEM-Passphrase vorliegen. Dazu kann das Flag REMOVEPASSPHRASE=true gesetzt werden.

Ausführen der Batch

Einfach den Anweisungen der Batch-Datei folgen:

Ergebnis der Batch (Bestandteile des PFX)

Am Ende der Extraktion sind die folgenden Dateien im definierten Ausgabeordner zu finden:

• Das eigentliche Zertifikat (*.crt)
• Der private Key (mit PEM-Passphrase) (*.key)
• Der private Key (ohne PEM-Passphrase) (*_nopass.key)
• Die Zertifikatskette (*_chain.pem).
  Ist diese Datei leer, so gibt es in dem Zertifikatsspeicher keine auszugebende Kette.

Bei allen Dateien müssen im Anschluss die von OpenSSL generierten Informationen entfernt werden:

Batch Script Quellcode

Ohne jegliche Gewährleistung oder Anspruch auf Support.

@ECHO off
ECHO - - - - - - - - - - - - - - - - - - - - - - - - -
REM VARIABLES TO SET!
SET OPENSSL=D:\DEXPRO\TOOLS\OPENSSL\openssl.exe

SET PFXFILE=D:\DEXPRO\ZERTIFIKATE\ORIGINALS\KUNDENZERTIFIKAT.pfx
SET OUTPUTFOLDER=D:\DEXPRO\ZERTIFIKATE\OUT\
SET OUTPUTFILENAME=KONVERTIERTES_KUNDENZERTIFIKAT
REM REMOVE PEM PASSPHRASE? -> TRUE / FALSE
SET REMOVEPASSPHRASE=true

REM START DER EXTRAKTION
ECHO EXTRACTION OF THE INDIVIDUAL COMPONENTS OF A PFX CERTIFICATE STORE
ECHO Setting the variables ...
ECHO 	openssl.exe: [%OPENSSL%]
ECHO 	PFX certificate store: [%PFXFILE%]
ECHO 	Destination folder:  [%OUTPUTFOLDER%]
ECHO 	Destination file name: [%OUTPUTFILENAME%]
ECHO     - - - - - - - - - - - - - - - - - - - - - - -
ECHO Checking the variables ...
if exist %OPENSSL% (
    ECHO 	openssl.exe found
) else (
    ECHO 	openssl.exe [%OPENSSL%] not found - please adjust the path!
	goto ERROREND
)
if exist %PFXFILE% (
    ECHO 	Customer certificate store [%PFXFILE%] found
) else (
    ECHO 	Customer certificate store [%PFXFILE%] not found - please adjust the path!
	goto ERROREND
)
if exist %OUTPUTFOLDER% (
    ECHO 	Destination folder [%OUTPUTFOLDER%] found
) else (
    ECHO 	Destination folder [%OUTPUTFOLDER%] not found - please adjust the path!
	goto ERROREND
)
if "%OUTPUTFILENAME%"=="" (
    ECHO 	No destination filename was specified!
	goto ERROREND
)
ECHO     - - - - - - - - - - - - - - - - - - - - - - -
ECHO Start extraction ...
ECHO PRIVATE KEY EXTRACTION
%OPENSSL% pkcs12 -in %PFXFILE% -nocerts -out %OUTPUTFOLDER%%OUTPUTFILENAME%.key
ECHO CERTIFICATE EXTRACTION
%OPENSSL% pkcs12 -in %PFXFILE% -clcerts -nokeys -out %OUTPUTFOLDER%%OUTPUTFILENAME%.crt
ECHO CERTIFICATE CHAIN EXTRACTION
%OPENSSL% pkcs12 -in %PFXFILE% -cacerts -nokeys -chain -out %OUTPUTFOLDER%%OUTPUTFILENAME%_chain.pem


REM REMOVE PEM PASSPHRASE
IF "%REMOVEPASSPHRASE%"=="true" (
	ECHO REMOVE PEM-PASSPHRASE
	%OPENSSL% rsa -in %OUTPUTFOLDER%%OUTPUTFILENAME%.key -out %OUTPUTFOLDER%%OUTPUTFILENAME%_nopass.key
) ELSE (
	ECHO PEM-Passphrase is not removed
)
GOTO END

:END
ECHO     - - - - - - - - - - - - - - - - - - - - - - -
ECHO EXTRACTION COMPLETED!
ECHO - - - - - - - - - - - - - - - - - - - - - - - - -
PAUSE
EXIT

:ERROREND
ECHO     - - - - - - - - - - - - - - - - - - - - - - -
ECHO EXTRACTION FAILED!
ECHO PLEASE CHECK ALL PARAMETERS!
ECHO - - - - - - - - - - - - - - - - - - - - - - - - -
PAUSE
EXIT

Alternative Konfiguration

Einrichtung des Virtuellen Hosts

# Alternative Konfiguration:
LoadModule ssl_module modules/mod_ssl.so
<VirtualHost *:8443>
  ServerName host.domain.net
  DocumentRoot "${SQZROOT}\htdocs\public"
    <IfModule mod_ssl.c>
      SSLEngine on
      SSLCertificateKeyFile "conf/ssl/package.key"
      SSLCertificateFile "conf/ssl/package.cer"
      SetEnvIf User-Agent ".*MSIE.*" \
      nokeepalive ssl-unclean-shutdown \
      downgrade-1.0 force-response-1.0
    </IfModule>
</VirtualHost>

Der host.domain.net  Wert ist durch den entsprechenden Hostnamen zu ersetzen.

 

Mögliche Fehlerquellen

Konfigurationsoberflächen werden nicht angezeigt

Wenn z.B. beim Öffnen des öffentlichen Ordners "Dokumentenklassen" keine Tabelle angezeigt wird, aber der Verbindungstest zu Squeeze erfolgreich ist, dann liegt das in der Regel an einem falsch gespeicherten Link im Browser-Cache. Hier muss einmal der Cache des Browsers gelöscht werden, dann werden die Konfigurationsoberflächen in der Regel angezeigt.

Als Alternative kann auch der "Inkognito Modus" (Chrome) oder das "private Fenster" (Firefox) für diesen Test benutzt werden. Dabei lädt der Browser in der Regel alle Dateien neu, sobald ein neues Fenster in diesem Modus geöffnet wird. 

Login-Fenster öffnet sich beim Öffnen des Viewers

Beim öffnen des Viewers kann es passieren, dass sich folgendes Fenster öffnet:

Dies kann zwei Gründe haben:

1. Documents und Squeeze werden nicht über die gleiche Domäne aufgerufen. Wenn Squeeze z.B. unter squueze.xyz.de läuft und Documents über localhost aufgerufen wird, kann der Viewer ohne Anmeldung nicht aufgerufen werden. Dies ist ein neueres Sicherheits-Feauture von Chrome und anderen Browsern. 

Behoben werden kann dies, indem Documents auch z.B. über documents.xyz.de aufgerufen wird.

Dies ist der typische Grund für dieses Verhalten.

2. Es wurde kein gültiger API-Key für Squeeze definiert. Dies kann über die Admin-Oberfläche erledigt werden.

Viewer wird als PDF geladen (Besonderheit beim Einsatz von Easy View)

Wenn Easy View auf dem System verwendet wird, kann es sein, dass der Viewer nicht richtig angezeigt wird und stattdessen die squeeze.sqz-Datei als PDF dargestellt wird. In diesem Fall muss die documents.ini um folgenden Eintrag erweitert werden (im Bereich der Konvertierungen):

$convert_pdf.sqz [NONE]

Anschließend muss der Documents Server neu gestartet werden oder am besten der gesamte Server, da die Dokumente vom System vorgehalten werden.

Ohne Neustart müssen alle Dokumente aus dem Order „C:\Windows\Temp\doc5_tmp„ gelöscht werden

Viewer wird nicht geladen (Dateiendung ".sqz" ist dem System unbekannt)

Wenn eine Installation vorliegt in welcher nicht nur Invoice auf einer Documents-Installation vorliegt, kann es passieren, dass der Viewer nicht geladen wird und nur die sqz-Datei angezeigt wird. Dies hängt in der Regel damit zusammen, dass in der "viewer-config.xml" (Standard-Pfad Documents5/tomcat8/webapps/documents/WEB-INF/classes) ein Eintrag fehlt, welcher in Documents festlegt, dass sqz-Dateien mit dem Viewer geöffnet werden sollen.

Hier muss folgender Eintrag hinzugefügt werden:

<viewer name="SiphinitiViewer">
  	<extensions>sqz</extensions>
</viewer>

Anschließend muss eventuell der Tomcat neugestartet werden.

Leerer Trainingswert beim Aufruf des Dokumenten-Trainings

Wenn beim Öffnen des Trainings der Wert für Kreditor leer ist, dann hängt das in der Regel damit zusammen, dass in dem Bereich "Mappentyp/Feldname für Training" (siehe Mappentyp (x) und Feldname (x)) der Konfigurationsoberfläche ein ungültiger Feldname ausgewählt worden ist und kein Wert für das angegebene Feld gefunden werden kann.

Fehlermeldung "Dieses Feld existiert nicht" beim Öffnen des Trainings

Unter Umständen kann beim Öffnen des Trainings folgende Fehlermeldung erscheinen:

Diese Meldung kommt in der Regel daher, dass in dem Bereich "Mappentyp/Feldname für Training" (siehe Mappentyp (x) und Feldname (x)) der Konfigurationsoberfläche ein ungültiger Feldname ausgewählt worden ist.  

Beleg wird nicht nach Documents übergeben und bleibt in der Validierung hängen

Wenn ein Beleg in der Validierung hängenbleibt, obwohl er eigentlich direkt nach Invoice übergeben werden soll, müssen folgende Eigenschaften an der "Stapelklasse" (in der Regel Invoice) gesetzt werden:

• ExportAfterExtraction = 1
• IgnoreMandatoryFieldCheckForExport = 1

Viewer wird bei externen Dokumentenmodus nicht geladen

Bei Anzeige der Dokumente in einem externen Fenster kann es vorkommen, dass das Viewer-Fenster so angezeigt wird:

Dieses Verhalten tritt auf, da otris und der SQUEEZE-Viewer beide "Nachrichten" verschicken und diese bei otris nicht ausreichend abgefangen werden. otris arbeitet jedoch an einer Lösung.

Als Workaround sollte beim externen Dokumentenmodus der Nutzer die "Doppelansicht" in einer Mappe deaktivieren. Dies kann über den Knopf "Doppelansicht öffnen" umgestellt werden. In dieser Ansicht darf der Viewer hier nicht auf "normalen" Feld-Liste angezeigt werden. Ansonsten kann es passieren, dass der Viewer in der externen Ansicht nicht angezeigt wird.

Diese Einstellungsmöglichkeit gibt es seit Documents 5.0e.

Anpassung von Farben der Markierungen

Ab der Invoice-Version (V.1.1.115) sind die folgenden Parameter (SqueezeParam.fieldValidColor, SqueezeParam.fieldNotValidColor und SqueezeParam.fieldAlternativesColor)
in der Datei Documents5\DEXPRO_ClientExits\DexClientExits.jsp bereits vorhanden. Über diese Parameter kann die Standard-Farbe der Markierungen angepasst werden. Ist der Wert leer oder einkommentiert, werden die Standardfarben verwendet.

Außerhalb von Invoice können diese Parameter innerhalb einer beliebigen Datei hinterlegt werden, welche in dem jeweiligen Projekt in den externen Ressourcen hinterlegt ist. Ggf. muss nach einer solchen Änderungen der Browser-Cache geleert werden. Sind die Parameter nicht vorhanden, wird automatisch die Standardfarbe verwendet:

Gültig sind nur in HTML gültige Farbangaben im hexadezimalen Format (z.B. #006B00)

Damit diese Parameter greifen, muss die Datei SqueezeFunctionsLib.js (Documents5\SQUEEZE\www\SqueezeViewer\SqueezeFunctions.js) mindestens in der Version 2.0.27 vorliegen. Vorherige Varianten unterstützen diesen Parameter nicht. Die aktuelle Version der Datei ist im oberen Teil der Datei ersichtlich.

Vorgehensweise für SqueezeFunctions.js-Versionen kleiner 2.0.27

In der Datei Documents5\SQUEEZE\www\SqueezeViewer\SqueezeFunctions.js kann die Farbe der Markierungen in Documents angepasst werden. Die Farbcodes entsprechen Standard HTML Color Codes.

Folgende Farben können gesetzt werden

1. gFieldValid: Farbe für gefüllte Felder (Standard: #59E817)
2. gFieldNotValid: Farbe für nicht gefüllte Felder (Standard: #FF0000)
3. gFieldAlternatives: Farbe für Felder mit Alternativen (Standard: #FFA500)

Nach Änderung der Datei muss ggf. der Browser-Cache geleert werden

Änderungen in dieser Datei werden nach Invoice-Updates eventuell überschrieben und müssen erneut vorgenommen werden.