...

Im Folgenden erhalten Sie eine detaillierte Anleitung, wie Sie beim Update der Software Income Taxes (ehemals GlobalTaxCenter (, GTC) vorgehen sollten. Bitte halten Sie die unten angegebene Reihenfolge bei der Aktualisierung ein. Eine andere Reihenfolge kann zu einem fehlerhaften Systemverhalten nach der Aktualisierung führen.

1) Vorbereitungen

1.1) Systemvoraussetzungen prüfen

Bevor Sie mit dem Update beginnen, überprüfen Sie bitte, ob Applikations- und Datenbankserver noch die Mindestanforderungen erfüllen. Das Wichtigste in Kürze:

• Das verwendete DBMS darf nicht älter als 5 Jahre sein. Sofern Sie MSSQL einsetzen, müssen Sie mindestens die Version 2017 verwenden.
• Der Tomcat-Server muss in der Version 9.0.x (mit Java 17) betrieben werden.

1.2) Web Application Server stoppen

...

1.5) Download das Auslieferungspakets

1.6) Tomcat auf Java 17 umstellen

Im Wenn Sie bereits die Version 22.09.00 oder eine neuere Version im Einsatz haben, können Sie diesen Schritt überspringen.

Im Dokument Upgrade von Java8 auf Java17 ist beschrieben, wie Java 17 installiert und dem Tomcat 9 bekannt gemacht wird. 

Zusätzlich sind dem Tomcat mit der Anwendung "tomcat9w.exe" im Tomcat/bin-Verzeichnis die folgenden Java-Startparameter hinzuzufügen:

--add-opens=java.base/java.util=ALL-UNNAMED

--add-opens=java.base/java.lang.reflect=ALL-UNNAMED

--add-opens=java.base/java.text=ALL-UNNAMED

--add-opens=java.desktop/java.awt.font=ALL-UNNAMED

1.7) Datenbanktreiber im Tomcat hinterlegen

Wenn Sie bereits die Version 22.09.00 oder eine neuere Version im Einsatz haben, können Sie diesen Schritt überspringen.

Aus lizenzrechtlichen Gründen darf AMANA die JDBC-Treiber für MySQL, Microsoft SQL Server und Oracle nicht im GTC- Deployment mit ausliefern.

...

2. Hinterlegen Sie den Treiber im Verzeichnis "<Tomcat-Root>/lib".

1.8)

...

Das GTC arbeitet mit einer neuen SAPJCO-Version. Erkundigen Sie sich ggf. bei der Fachabteilung, ob in Ihrem Unternehmen RfC-Schnittstellen im GTC verwendet werden. Sofern dies der Fall ist, müssen Sie die folgenden Schritte durchführen.

1. Laden Sie von der SAP-Support-Seite den passenden Connector für Ihr System herunter.
2. Tauschen Sie, falls vorhanden, die Datei  "sapjco3{*}.jar" aus dem Verzeichnis "<Tomcat-root>/lib" mit der heruntergeladenen "sapjco3{*}.jar" aus. Ist keine "sapjco3{*}.jar" vorhanden, genügt es die neue Datei einzufügen.
3. Entfernen Sie die alte "sapjco.dll". Diese kann in verschiedenen Verzeichnissen liegen, meistens im "system32"-Verzeichnis von Windows.
4. Fügen Sie die neue "sapjco.dll" in das Verzeichnis "<Tomcat-root>/bin" ein.

1.9) Kerberos-SSO aktualisieren

Sofern in Ihrer Installation Single-Sign-On mit Kerberos umgesetzt wurde, müssen Sie Anpassungen vornehmen.

Mit Java 17 wird schwache Kerberos-Authentifizierung nicht mehr offiziell unterstützt. Detaillierte Informationen zur Konfiguration haben wir in diesem Kapitel zusammengetragen.

Kerberos-SSO unter Java 17

1.10) Konfiguration der Datenbankverbindung im GTC

Zentral im Tomcat (JNDI)

Das bisherige Standard-Deployment des GTC sah vor, dass die Datenbankverbindung bei jeder GTC-Auslieferung in der zur Datenbank passenden repository-Datei kundenspezifisch angepasst wurde. Dieser Prozess ist nun dahingehend vereinfacht, dass das Standard-Deployment mit der JNDI-Datasource "gtcdatasource" konfiguriert ist. Hierzu muss kundenseitig einmalig pro Tomcat die Datei context.xml im Tomcat/conf-Verzeichnis erweitert werden, indem die JNDI-Datasource dort innerhalb des context-Tags definiert wird. Die Verwendung der JNDI-Konfiguration hat den Vorteil, dass die Datenbank-Verbindung nicht mehr innerhalb des GTC-Deployments angepasst werden muss.

<Resource auth="Container" driverClassName="oracle.jdbc.driver.OracleDriver"
        maxTotal="20" maxIdle="10" maxWaitMillis="-1" name="jdbc/gtcdatasource" username="root" password="test" 
        type="javax.sql.DataSource" url="jdbc:oracle:thin:@hostname:1521/gtc" 
/>

Bei Verwendung des Microsoft SQL-Servers sind hierbei Angaben zur Verschlüsselung (encrypt) und zur Vertrauenswürdigkeit (trustServerCertificate) des Server-Zertifikats zu machen:

<Resource	auth="Container" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"     
            maxTotal="20" maxIdle="10" maxWaitMillis="-1" name="jdbc/gtcdatasource" username="root" password="test" 
			type="javax.sql.DataSource" url="jdbc:sqlserver://hostname:1433;DatabaseName=...;encrypt=...;trustServerCertificate=..." 
/>

Im Falle des Microsoft SQL-Servers empfiehlt AMANA zudem eine Installation mit Integrated Security, bei der keine Angaben zu Username und Password in der context.xml hinterlegt werden müssen. Für die Datenbankverbindung wird stattdessen der Account verwendet, unter dem der Tomcat-Dienst ausgeführt wird.

Innerhalb des GTC-Deployments

Anstelle einer JNDI-Datasource kann die Datenbankverbindung wie bisher in der zur Datenbank passenden repository-Datei konfiguriert werden.

...

Konfiguration der Datenbankverbindung

Zentral im Tomcat (JNDI)

Wenn Sie bereits die JNDI-Konfiguration verwenden, können Sie diesen Schritt überspringen.

Das bisherige Standard-Deployment sah vor, dass die Datenbankverbindung bei jeder Auslieferung in der zur Datenbank passenden repository-Datei kundenspezifisch angepasst wurde. Dieser Prozess ist nun dahingehend vereinfacht, dass das Standard-Deployment mit der JNDI-Datasource "gtcdatasource" konfiguriert ist. Hierzu muss kundenseitig einmalig pro Tomcat die Datei context.xml im Tomcat/conf-Verzeichnis erweitert werden, indem die JNDI-Datasource dort innerhalb des context-Tags definiert wird. Die Verwendung der JNDI-Konfiguration hat den Vorteil, dass die Datenbank-Verbindung nicht mehr innerhalb des Deployments angepasst werden muss.

<Resource auth="Container" driverClassName="oracle.jdbc.driver.OracleDriver" name="jdbc/gtcdatasource" username="root" password="test" 
        type="javax.sql.DataSource" url="jdbc:oracle:thin:@hostname:1521/gtc" 
	    maxTotal="200" maxIdle="10" maxWaitMillis="20000" timeBetweenEvictionRunsMillis="10000" testWhileIdle="true" removeAbandonedOnBorrow="true"
/>

Bei Verwendung des Microsoft SQL-Servers sind hierbei Angaben zur Verschlüsselung (encrypt) und zur Vertrauenswürdigkeit (trustServerCertificate) des Server-Zertifikats zu machen:

<Resource auth="Container" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver" name="jdbc/gtcdatasource" username="root" password="test" 
        type="javax.sql.DataSource" url="jdbc:sqlserver://hostname:1433;DatabaseName=...;encrypt=...;trustServerCertificate=..." 
        maxTotal="200" maxIdle="10" maxWaitMillis="20000" timeBetweenEvictionRunsMillis="10000" testWhileIdle="true" removeAbandonedOnBorrow="true"
/>

Im Falle des Microsoft SQL-Servers empfiehlt AMANA zudem eine Installation mit Integrated Security, bei der keine Angaben zu Username und Password in der context.xml hinterlegt werden müssen. Für die Datenbankverbindung wird stattdessen der Account verwendet, unter dem der Tomcat-Dienst ausgeführt wird.

Innerhalb des Deployments

Anstelle einer JNDI-Datasource kann die Datenbankverbindung wie bisher in der zur Datenbank passenden repository-Datei konfiguriert werden.

Bitte beachten Sie, dass in diesem Fall in jedem Deployment sowohl die Datei "repository_mssql.xml", "repository_mysql.xml" oder "repository_oracle.xml" als auch die Datei "repository.xml" angepasst werden müssen. Lesen Sie im Abschnitt "Deployment aktualisieren" die Details dazu.

1.9) Pfadangabe zu Windows (optional)

Sofern sich das Tomcat-Installationsverzeichnis nicht auf dem Laufwerk der Windows-Installation befindet, muss der Pfad zur Windows-Installation explizit angegeben werden. Dazu wird in den Tomcat-Startparametern der folgende Eintrag mit der korrekten Pfadangabe ergänzt:

-Dgtc.runtime.system32=<Pfadangabe zum system32-Verzeichnis>

1.10) SAPJCO aktualisieren (optional, für Systeme mit einer RfC-Anbindung an SAP)

Die Software arbeitet mit einer neuen SAPJCO-Version. Erkundigen Sie sich ggf. bei der Fachabteilung, ob in Ihrem Unternehmen RfC-Schnittstellen in diesem Produkt verwendet werden. Sofern dies der Fall ist, müssen Sie die folgenden Schritte durchführen.

1. Laden Sie von der SAP-Support-Seite den passenden Connector für Ihr System herunter.
2. Tauschen Sie, falls vorhanden, die Datei  "sapjco3{*}.jar" aus dem Verzeichnis "<Tomcat-root>/lib" mit der heruntergeladenen "sapjco3{*}.jar" aus. Ist keine "sapjco3{*}.jar" vorhanden, genügt es die neue Datei einzufügen.
3. Entfernen Sie die alte "sapjco.dll". Diese kann in verschiedenen Verzeichnissen liegen, meistens im "system32"-Verzeichnis von Windows.
4. Fügen Sie die neue "sapjco.dll" in das Verzeichnis "<Tomcat-root>/bin" ein.

1.11) Kerberos-SSO aktualisieren (optional)

Sofern in Ihrer Installation Single-Sign-On mit Kerberos umgesetzt wurde, müssen Sie Anpassungen vornehmen.

Mit Java 17 wird schwache Kerberos-Authentifizierung nicht mehr offiziell unterstützt. Detaillierte Informationen zur Konfiguration haben wir in diesem Kapitel zusammengetragen.

Kerberos-SSO unter Java 17

1.12) Registrierung des Moduls am Portal (optional)

Die folgende Konfiguration muss nur durchgeführt werden, wenn ...

1. Sie die Anwendung in der GTC Suite betreiben (in der Tabelle TSYSTEM steht der Eintrag "USE_SSO" auf dem Wert "12") und
2. Sie bisher eine Version älter als 22.16.04 im Einsatz hatten.

Bisher wurden die Parameter zur Registrierung in der Datenbank in der Tabelle TPORTALCONNECTION gepflegt. Ab sofort wird die Registrierung des Moduls am Portal direkt mit Tomcat-Startparametern vorgenommen.

Die folgenden Parameter sind in jedem Fall notwendig:

-Dincometaxes.url.base=<URL des Moduls>

-Dincometaxes.url.portal=<URL des Portals>

Optional um eine andere API-Adresse anzugeben:

-Dincometaxes.url.api=<URL der API des Moduls>

Optional für die statische Registrierung notwendig (wenn das Modul und das Portal auf einem Tomcat installiert sind):

-Dincometaxes.clientId=<Zeichenfolge aus dem Portal - ClientId>

-Dincometaxes.clientSecret=<Zeichenfolge aus dem Portal - ClientSecret>

Hinweis:

Die URLs müssen immer mit Port angegeben werden, auch wenn es sich um einen Standard-Port (z.B. 80 oder 443) handelt.

1.13) Registrierung des Servicemoduls "Tax Data Hub" (optional)

Die folgende Konfiguration muss nur durchgeführt werden, wenn ...

1. Sie die Anwendung in der GTC Suite betreiben (in der Tabelle TSYSTEM steht der Eintrag "USE_SSO" auf dem Wert "12") und
2. Sie auf das Servicemodul "Tax Data Hub" zugreifen möchten.

Erstellen Sie einen API-Key für das Servicemodul "Tax Data Hub" und fügen Sie diesen als Startparameter im Tomcat ein. Wie Sie dabei vorgehen müssen, ist im verlinkten Kapitel erläutert.

2) Deployment aktualisieren

...

Sofern Sie Anpassungen (web.xml, ApplicationConfig.properties oder Datenbank-Verbindung) im GTC- Deployment vornehmen müssen, entpacken Sie das WAR-Archiv mit 7-zip.

...

Analog zur bisher installierten GTCSoftware-Version, muss dem neuen Deployment bekannt gemacht werden, mit welcher Art von Datenbank es sich verbinden soll. Dazu wird in der zentralen "..\webapps\<gtc-root>\WEB_INF\classes\repository.xml"-Datei ein Verweis auf die richtige Datenbank (MySql, Oracle, MS SQL) angelegt. Danach müssen die Verbindungsparameter in der jeweiligen repository_<xyz>.xml aktualisiert werden. Im einzelnen:

1. Anpassen der Datei "<gtc-root>\WEB_INF\classes\repository.xml":
   Hier teilen Sie dem GTC mitder Anwendung mit, mit welcher Art von Datenbank es sich verbinden soll. Suchen Sie die Zeile: <!ENTITY datasource SYSTEM "repository_mysql.xml"> und ersetzen Sie den Begriff "mysql" ggf. entsprechend Ihrer Datenbankart. Haben Sie Oracle im Einsatz verwenden Sie „oracle“. Verwenden Sie eine MS SQL-Datenbank schreiben Sie „mssql“ (z.B. <!ENTITY datasource SYSTEM "repository_mssql.xml">).
2. Übertragen Sie die Verbindungseinstellungen aus der "repository_mysql.xml", "repository_oracle.xml" oder "repository_mssql.xml" aus der vorherigen Sicherung in das Verzeichnis "<gtc-root>\WEB-INF\classes\" in die gleichnamige Datei des neuen Deployments.

...

Optional haben Sie die Möglichkeit die Aktualisierung der Datenbank manuell durch Skripte durchführen zu lassen. Die Skripte werden wir Ihnen auf Anfrage bereitstellen. Wir benötigen dafür die Versionsnummer des bereits installierten GTCSoftwarepakets. Im Abschnitt 3.2 wird darauf näher eingegangen.

...

Wenn Sie die manuelle Aktualisierung nutzen, führen Sie bitte folgende Schritte aus:

1. Starten Sie das DBMS ihres Datenbank-Servers und wählen sie das Datenbank-Schema aus, das zur GTC- Applikation gehört.
2. Führen Sie die mitgelieferten SQL-Update-Skripte in Sortierreihenfolge der Dateinamen bzw. Versionen auf diesem Schema aus. Nutzen Sie einen Benutzer, der volle Rechte auf der Datenbank hat.
   Beispiel:

...

1. Starten Sie den Web Application Server wie gewohnt über die Kommandozeile oder den Dienste-Manager. Beim Server-Start werden nun u. U. das Update der Datenbank und Autorun-Jobs durchgeführt. Diese sind Teil der Aktualisierung und müssen erfolgreich ausgeführt werden.

   
   

   Warning
   Brechen Sie den Server-Start also nicht ab, auch wenn das Starten länger als gewöhnlich dauert. Kontaktieren Sie im Zweifelsfalle die Hotline.

   
   

2. Nach dem Start des Servers testen Sie den Zugriff auf das GlobalTaxCenter oder informieren Sie Ihre zuständige Fachabteilung, um den Zugriff testen zu lassen, falls Sie selbst keine Zugangsdaten für das GTC habendie Anwendung haben.
3. Wechseln Sie (oder ein berechtigter Vertreter) im Bereich Stammdaten in den Dialog Administration und dort in den Reiter Log und öffnen Sie die Datei "gtc_autorun.log". Prüfen Sie, ob die Autorun-Jobs erfolgreich durchgelaufen sind oder ob Fehlermeldungen angezeigt werden. Im Fehlerfall wenden Sie sich bitte an die Hotline - GlobalTaxCenter Suite und schicken die Log-Dateien "gtc_autorun.log" und „gtc_system.log“ mit.
4. Falls nach der Aktualisierung Fehler in der Webapplikation auftreten, kontaktieren Sie bitte ebenfalls die Hotline - GlobalTaxCenter Suite und senden die Log-Dateien mit.

...

1. In der Test- und Produktivumgebung ist das GTC in ist die Anwendung in der Version 22.00.01 installiert.
2. Sie aktualisieren nun die Testumgebung mit der Version 22.00.03.
3. Ein paar Wochen später bekommen Sie ein neues Auslieferungspaket bereitgestellt und aktualisieren die Testumgebung. Diese hat nun die Version 22.00.07.
4. Die Produktivumgebung läuft immer noch mit der Version 22.00.01.
5. Sie erhalten von der Fachabteilung die Freigabe, das Produktivsystem auf Version 22.00.07 zu aktualisieren.
6. Sie müssen in jedem Fall im ersten Schritt die Skripte der Version 22.00.03 einspielen, bevor Sie mit der Installation der Version 22.00.07 fortfahren. Nur so können Sie verhindern, dass ein Schiefstand in der Datenbank entsteht.

6) TransferClient-Installation und

...

Einbindung (optional)

Sofern mit dem GTC der Anwendung (Modul Tax Return) auch elektronische Versendungen an die Finanzverwaltung durchgeführt werden, muss in regelmäßigen Abständen das Modul TransferClient (TC) aktualisiert werden, da hierüber die Versendungen durchgeführt werden.

Haben Sie das GTC- Modul Tax Return erworben, beinhaltet die Auslieferungsmail auch immer das Installationspaket für das Modul TransferClient. Jedoch ändert sich nicht zwangsläufig mit jeder GTC- Bereitstellung auch die TC-Version. Um unnötige Aufwände auf Ihrer Seite zu vermeiden, prüfen Sie daher bitte vor dem Update, ob sich die bereits installierte TC-Version und die in der Mail bereitgestellte Version unterscheiden. Die Versionsnummer (=Dateiversion) der installierten TC-Version können Sie in den Eigenschaften der Datei TransferClient.exe einsehen:

...

Unterscheiden sich die beiden TC-Versionen, installieren Sie neue TC-Version bitte mit Hilfe der hier verlinkten Anleitung.  Bei Bei der Installation notieren Sie bitte die Web-Service-URL, da diese später im GTC- Administrationsbereich hinterlegt bzw. aktualisiert werden muss.

...

Für die Konfiguration der TC-Verbindung im GTC müssen in der Anwendung müssen die nachfolgend genannten Schritte durchgeführt werden. Für die Konfiguration sind Editier-Berechtigungen für die Bereich Stammdaten / Administration notwendig.

1. Web Service zum TransferClient aktivieren
2. Einrichten des Proxys zwischen GTC Anwendung und TransferClient (optional)
3. Testen der Verbindung zum TransferClient
4. Einrichten des Proxys zwischen TransferClient und Finanzverwaltung (optional)

...

6.2) Proxy zwischen

...

Anwendung und TransferClient (optional)

Der Proxy wird als separater Verbindungsparameter auf der Administrationsseite gepflegt.

...