...

Below you will find detailed instructions on how to proceed when updating the Income Taxes module (formerly known as GlobalTaxCenter, GTC) software. Please follow the order given below (first database and then deployment) when updating. A different order can lead to incorrect system behaviour after the update.

1) Preparations

1.1) Check system requirements

Before you start the update, please check whether the application and database servers still meet the minimum requirements. The most important in brief:

...

1.2) Stopping the web application server

1. Stop the web application server (e.g. Tomcat) in the usual way using either the command line or the Service Manager.
2. Delete the contents of the “work” directory in the Tomcat installation.

1.3) Performing a database backup

As a first step, you should create a database backup that can be restored (rolled back) if the update fails. For information on how to do this, please refer to the user manual of your database management system.

1.4) Save old deployment

1. In the subdirectory "\webapps" of the Web Application Server, you can find the deployment installed so far (usually with the name "\gtc" or "\ROOT").
2. Rename this directory (e.g. "\gtc_<version>_old") and then move it to a directory outside the "\webapps" directory. Under no circumstances may the backuped deployment remain in the "\webapps" directory. This would lead to serious errors later on in the update process. 

1.5) Download the delivery package

Download the installation package via the link given to you in the delivery mail. Place it in a temporary folder. We will provide you with the deployment package as a war file.

If it is necessary to adapt contents in the package, the file must be unpacked with 7-zip beforehand. Alternatively, rename the file gtc.war to gtc.zip, then you can use Windows Explorer for this.

1.6) Switch Tomcat to Java 17

If you already had a Income Taxes version 22.09.00 or newer installed, you can skip this step.

...

1.7) Store database driver in Tomcat

If you already had a Income Taxes version 22.09.00 or newer installed, you can skip this step.

...

2. Place the driver in the directory "<Tomcat-Root>/lib".

1.8)

...

The Income Taxes is working with a new SAPJCO version. Check with the department whether RfC interfaces are used in the Income Taxes in your company. If this is the case, you must carry out the following steps.

1. Download the suitable connector for your system from this offical SAP-Site.
2. Delete any old sapjco{*}.jar from this directory: "<Tomcat-root>/webapps/<gtc-root>/WEB-INF/lib".
3. Paste the new sapjco{*}.jar in this directory:  "<Tomcat-root>/lib". If an old sapjco{*}.jar exists in this folder replace it with the new one.
4. Delete the old sapjco{*}.dll from the system. It can be in different locations, but in most cases it is in the system32 folder from Windows.
5. Paste the new sapjco{*}.dll in this directory: "<Tomcat-root>/bin"

If you get any problems with this please contact our hotline.

1.9) Update Kerberos SSO configuration (optional)

If single sign-on with Kerberos has been implemented in your installation, you must implement adjustments.

With Java 17, weak Kerberos authentication is no longer officially supported. In this chapter we provide detailed information on the configuration.

Kerberos-SSO when using Java 17

1.10) Configuration of the database connection in the Income Taxes module

Central in Tomcat (JNDI)

If you are already using the JNDI configuration, you can skip this step.

The previous standard deployment of the Income Taxes module provided that the database connection was customized for each Income Taxes delivery in the repository file matching the database. This process is now simplified to the extent that the standard deployment is configured with the JNDI datasource "gtcdatasource". For this purpose, the customer must expand the context.xml file in the Tomcat/conf directory once per Tomcat by defining the JNDI datasource there within the context tag. Using the JNDI configuration has the advantage that the database connection no longer has to be adapted within the Income Taxes deployment.

...

...

Configuration of the database connection in the Income Taxes module

Central in Tomcat (JNDI)

If you are already using the JNDI configuration, you can skip this step.

The previous standard deployment of the Income Taxes module provided that the database connection was customized for each Income Taxes delivery in the repository file matching the database. This process is now simplified to the extent that the standard deployment is configured with the JNDI datasource "gtcdatasource". For this purpose, the customer must expand the context.xml file in the Tomcat/conf directory once per Tomcat by defining the JNDI datasource there within the context tag. Using the JNDI configuration has the advantage that the database connection no longer has to be adapted within the Income Taxes deployment.

<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" />

When using the Microsoft SQL server, information on the encryption (encrypt) and the trustworthiness (trustServerCertificate) of the server certificate must be provided:

<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="20200" maxIdle maxIdle="10" maxWaitMillis maxWaitMillis="-120000" name timeBetweenEvictionRunsMillis="jdbc/gtcdatasource10000" usernametestWhileIdle="roottrue" password removeAbandonedOnBorrow="testtrue" 
        type="javax.sql.DataSource" url="jdbc:oracle://hostname:3306/gtc" 
/>

When using the Microsoft SQL server, information on the encryption (encrypt) and the trustworthiness (trustServerCertificate) of the server certificate must be provided:

<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=..." 
/>

In the case of the Microsoft SQL server, AMANA also recommends an installation with Integrated Security, in which no username and password details need to be stored in the context.xml. Instead, the account under which the Tomcat service is run is used for the database connection.

Within the Income Taxes deployment

Instead of a JNDI datasource, the database connection can be configured as before in the repository file matching the database.

...

/>

In the case of the Microsoft SQL server, AMANA also recommends an installation with Integrated Security, in which no username and password details need to be stored in the context.xml. Instead, the account under which the Tomcat service is run is used for the database connection.

Within the Income Taxes deployment

Instead of a JNDI datasource, the database connection can be configured as before in the repository file matching the database.

Please note that in this case both the file "repository_mssql.xml", "repository_mysql.xml" or "repository_oracle.xml" and the file "repository.xml" must be adapted in each deployment. Read the section "Update Deployment" for details.

1.9) Path to Windows (optional)

If the Tomcat installation directory is not located on the drive of the Windows installation, the path to the Windows installation must be specified explicitly. To do this, the following entry is added to the Tomcat start parameters with the correct path:

-Dgtc.runtime.system32=<path to the system32 directory>

1.10) Update SAPJCO (optional, for systems with a RfC connection to SAP)

The Income Taxes is working with a new SAPJCO version. Check with the department whether RfC interfaces are used in the Income Taxes in your company. If this is the case, you must carry out the following steps.

1. Download the suitable connector for your system from this offical SAP-Support-Site.
2. Delete any old sapjco{*}.jar from this directory: "<Tomcat-root>/webapps/<gtc-root>/WEB-INF/lib".
3. Paste the new sapjco{*}.jar in this directory:  "<Tomcat-root>/lib". If an old sapjco{*}.jar exists in this folder replace it with the new one.
4. Delete the old sapjco{*}.dll from the system. It can be in different locations, but in most cases it is in the system32 folder from Windows.
5. Paste the new sapjco{*}.dll in this directory: "<Tomcat-root>/bin"

If you get any problems with this please contact our hotline.

1.11) Update Kerberos SSO configuration (optional)

If single sign-on with Kerberos has been implemented in your installation, you must implement adjustments.

With Java 17, weak Kerberos authentication is no longer officially supported. In this chapter we provide detailed information on the configuration.

Kerberos-SSO when using Java 17

1.12) Registering the module on the portal (optional)

The following configuration must only be carried out if ...

1. you operate the application in the GTC Suite (in the table TSYSTEM the entry "USE_SSO" is set to the value "12") and
2. you have been using a version older than 22.16.04.

Up to now, the parameters for registration were maintained in the database in the table TPORTALCONNECTION. From now on, the registration of the module at the portal is carried out directly with Tomcat start parameters.

The following parameters are necessary in any case:

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

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

Optional to specify a different API address:

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

Optional for static registration required (if the module and portal are installed on a Tomcat):

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

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

Notice:

The URLs must always be specified with port, even if it is a standard port (e.g. 80 or 443).

1.13) Registering the service module "Tax Data Hub" (optional)

The following configuration must only be carried out if ...

1. you operate the application in the GTC Suite (in the table TSYSTEM the entry "USE_SSO" is set to the value "12") and
2. you want to access the service module "Tax Data Hub".

Create an API key for the "Tax Data Hub" service module and insert it as a start parameter in Tomcat. How to proceed is explained in the linked section.

2) Update deployment

...

If you know of any other modifications to the deployment (e.g. in the "web.xml" file), please copy these too by editing the respective file.

3) Update database

The database update can be done automatically or manually.

...

Optionally, you have the possibility to update the database manually by scripts. We will provide you with the scripts on request. We need the version number of the already installed Income Taxes module for this. This is described in more detail in section 3.2.

3.1) Automatic update of the database

Please make sure to have a current database backup at hand, so it can be restored if needed (see section 1.4).

...

2021-10-22 15:12:57 [INFO ] ###################### Migration successful ######################
2021-10-22 15:12:57 [INFO ] ScriptLocationPath: C:\Tomcat 9.0_GTC\webapps\ROOT\migration/sql
2021-10-22 15:12:57 [INFO ] ConfigLocationPath: C:\Tomcat 9.0_GTC\webapps\ROOT\migration/flywayConfig.properties
2021-10-22 15:12:57 [INFO ] CSVPlaceholderPath: C:\Tomcat 9.0_GTC\webapps\ROOT\migration/FlywayPlaceholders.csv
2021-10-22 15:12:58 [INFO ] ############################################
2021-10-22 15:12:58 [INFO ] Current version: 20211001100000000_DELETE FROM TFLAGCONFIGURATION
2021-10-22 15:12:58 [INFO ] Pending Scripts: No pending scripts
2021-10-22 15:12:58 [INFO ] ############################################

3.2) Manual update of the database

...

• 01_MSSQL_8.3.02_8.4.04.sql
• 02_Insert_Reporting_MSSQL.sql
• etc.

4) Final steps

1. Start the Web Application Server as usual from the command line or the Service Manager. Autorun jobs may now be executed when the server is started. These are part of the update and must be executed successfully.

   
   

   Warning
   Do not cancel the server start, even if it takes longer than usual. If in doubt, please get in touch with the Hotline GlobalTaxCenter.

   
   

2. After starting the WAS server, test the access to the GlobalTaxCenter or inform your responsible department to have the access tested if you do not have access data for the Income Taxes module yourself.
3. Change (or an authorized representative) in the Masterdata area to the Administration dialogue and there to the Log tab and open the file "gtc_autorun.log". Check whether the autorun jobs have run successfully or whether error messages are displayed. In case of an error, please contact the Hotline GlobalTaxCenter and send the log files "gtc_autorun.log" and "gtc_system.log".
4. If errors occur in the web application after the update, please also contact the Hotline GlobalTaxCenter and send the log files.

5) Transfer to other instances

If you are working with different instances (development, test, integration, production, ...) please be careful that you are doing the same steps in each instance.

...

1. In the testing and production environment the Income Taxes module is installed in version 22.00.01.
2. Now you update the testing environment with version 22.00.03.
3. A few weeks later you will receive a new delivery package and update the testing environment. This now has the version 22.00.07.
4. The production environment still runs with version 22.00.01.
5. You receive the permission from the business department to update the production system to version 22.00.07.
6. In any case, you must first import the scripts of version 22.00.03 before you continue with the installation of version 22.00.07. This is the only way to prevent an inconsistency in the database.

6) TransferClient installation and integration into the Income Taxes module (optional)

If the Income Taxes module (Tax Return module) is also used for electronic transfers to the german tax authorities, the TransferClient (TC) version must also be updated at regular intervals. In this case, the Income Taxes module update provides a second installation package for the TC. This package has to be installed according to the instructions. During the installation the Web Service URL should be noted, because it has to be stored/updated in the administration area of the Income Taxes module.

...

1. Activate Web Service to TransferClient
2. Setting up the proxy between Income Taxes module and TransferClient (optional)
3. Testing the connection to the TransferClient
4. Setting up the proxy between TransferClient and tax authorities (optional)

6.1) Activate Web Service to TransferClient

The following configuration must be carried out so that the Elster transmission is available as a web service. On the administration page, the connection to the TC is added. (The TC must be started as a web service).

...

6.2) Proxy between Income Taxes module and TransferClient

The proxy is maintained as a separate connection parameter on the administration page.

6.3) Connection test to the TransferClient

Now the connection to the TC can be tested by clicking on the gear symbol (in the front of the line). A message is then displayed whether the test was successful or not.

6.4) Proxy between TransferClient and tax authorities

The proxy is maintained as a separate connection parameter on the administration page.

...