Table of Contents

Vorwort

Wir möchten Sie herzlich als Kunden des AMANA Tax Portal und DAC 6 willkommen heißen.

Im Folgenden geben wir eine Anleitung zur erstmaligen Installation des ATP auf einem Tomcat-Applikationsserver. Falls sich Ihre Anforderungen für die Installation von den hier gemachten Annahmen unterscheiden, beraten wir Sie gern, um Ihnen die Integration des ATP in Ihrem Unternehmen zu erleichtern.

Prüfung der Vorbedingungen

Infrastruktur

Bitte prüfen Sie mit Hilfe des Dokuments Systemanforderungen, ob die bei Ihnen gegebene Infrastruktur aktuell ist. Sollte dies nicht der Fall sein, passen Sie die Infrastruktur bitte an, bevor Sie mit der ATP-Installation beginnen.

Installation der Datenbank

...

Preamble

We would like to welcome you as a customer of AMANA DAC 6.

In the following we provide instructions for the initial installation of the DAC 6 on a Tomcat application server. If your requirements for the installation differ from the assumptions made here, we will be happy to advise you to facilitate the integration of DAC 6 in your company.

Checking the preconditions - infrastructure

Please use the System requirements document to check whether your infrastructure is up to date. If this is not the case, please update the infrastructure before you start with the DAC 6 installation.

Installation of database

The steps for setting up are kept general at this point in order to do justice to the different configurations of the database systems.

Create a new database schema on the database server.
Create a database user with permission to "INSERT", "UPDATE", "DELETE", "ALTER", "CREATE" on this database.
1. In SQL Server, the user needs the database roles db_datareader, db_datawriter and a role for executing stored procedures, e.g.: db_executor:
  CREATE ROLE db_executor

...

1. GO

...

1. GRANT EXECUTE TO db_executor

...

Automatisch
Über die integrierte Datenbankmigration (siehe Konfiguration des "Tomcat 8.5" Punkt 2b)
Manuell
Manuelle Einspielung der im Installationspaket enthaltenen Datenbankskripte

...

Installation des Web Application Servers

Wir gehen im Folgenden von einer Installation auf einem Windows-Betriebssystem aus. Eine Installation auf einem Unix-artigen System unterscheidet sich lediglich in den Pfaden und dem unter 1) und 2) beschriebenen Installationsvorgang.

Warning

Wir empfehlen für den Betrieb von ATP und DAC 6 die Verwendung von zwei separaten Applikationsservern.

Hierbei müssen Sie sicherstellen, dass die Applikationsserver unterschiedliche Portnummern nutzen.

Dies ist bei der Installation konfigurierbar.

Installation des JDK

Installieren Sie ein passendes JDK und erstellen die Systemvariable „JAVA_HOME“, die auf das Installationsverzeichnis zeigt.

Installation des "Tomcat 8.5"

Installieren Sie Apache Tomcat 8.5 in ein Verzeichnis Ihrer Wahl. Im weiteren Verlauf wird das Verzeichnis „C:\Server\Tomcat“ angenommen.

Wir empfehlen, die Einträge für das Startmenü zu installieren, um die Konfiguration zu vereinfachen.
Die Ports, welche der Tomcat verwendet, können nach Ihren Anforderungen angepasst werden.

Konfiguration des "Tomcat 8.5" nach der Installation

...

Tab „General“: Stellen Sie den Start des Dienstes auf automatisch.
Falls Sie die automatische Datenbankmigration aus den Applikationen nutzen wollen, fügen Sie bitte zusätzlich folgende Parameter im Feld "Java Options" ein:
1. "-Datp.db.migration=auto" für den ATP
2. "-Ddac6.db.migration=auto" für DAC 6
Tab „Java“: Im Feld "Initial Memory Pool" tragen Sie "512" ein
Tab „Java“: Im Feld "Maximum Memory Pool" tragen Sie ca. die Hälfte des verfügbaren physikalischen Arbeitsspeichers ein. Als Minimum empfehlen wir jedoch "2048". Bedenken Sie bitte bei 32-Bit-Systemen die Beschränkung des Arbeitsspeichers auf ca. 3,5 GB. Die hier gemachten Speichereinstellungen beeinflussen die Performance und Lauffähigkeit der Applikation. Unter Umständen sind diese bei wachsender Benutzung im Laufe der Zeit anzupassen.

...

Microsoft SQL Server - https://docs.microsoft.com/en-us/sql/connect/jdbc/microsoft-jdbc-driver-for-sql-server
Oracle - https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html
MySQL - https://dev.mysql.com/downloads/connector/j/

...

"jdbc/portaldatasource" für den ATP
"jdbc/dac6datasource" für DAC 6

...

1. GO
Make sure that the application server can connect to the database with this user.
Please ensure that a current JDBC driver package, suitable for your DBMS and the Java version used, is in the lib directory of the Tomcat.
The database schema is automatically created and updated when the application is started.
Make sure that the user who imports the DB scripts has all rights on the this database.

Installation of the Web Application Server

In the following we assume an installation on a Windows operating system. An installation on a Unix-like system differs mainly in the paths.

Note
We recommend the use of two separate application servers for the operation of Portal and DAC 6. Here you must ensure that the application servers use different port numbers. This can be configured during installation.

Installation of the JDK

Install a suitable JDK 17 and create the system variable "JAVA_HOME", which points to the installation directory.

Installation of the "Tomcat 9"

Install Apache Tomcat 9 in a directory of your choice. We recommend installing Tomcat to a drive other than "C:", in the further process the directory "D:\Server\Tomcat" is assumed.

We recommend installing the entries for the start menu to simplify the configuration.

The ports used by the Tomcat can be adapted according to your requirements.

Configuration of the "Tomcat 9"

Memory

After installation, run the application "->Startmenu->Tomcat->"configure tomcat" and perform the following steps:
1. Tab "General": Set the start of the service to automatic.
2. Tab "Java": Enter "512" in the field "Initial Memory Pool".
3. Tab "Java": In the field "Maximum Memory Pool" enter approximately half of the available physical memory. For example, 2048 for 4096 MB RAM. For 32-bit systems, please bear in mind the limitation of the working memory to approx. 3.5 GB. The memory settings made here affect the performance and runability of the application. They may need to be adjusted over time as usage increases.

HTTPS

Make the necessary connector settings in the „D:\Server\Tomcat\lib\server.xml" configuration file to ensure communication via https. A reference to a valid key store for identifying DAC 6 to other applications must be maintained.

Connection to the database

Database driver

Copy the database driver that matches your database server into the "\lib" directory in the Tomcat installation directory.

Microsoft SQL Server - Microsoft JDBC Driver for SQL Server - JDBC Driver for SQL Server

Configuration

Configure the database connection as a JNDI connection in Tomcat:

Open the "context.xml" file in the "\conf" directory of the Tomcat.

Add a new "Resource" XML tag with appropriate attributes for your DBMS and name "jdbc/dac6datasource".
Example "Resource" XML tag for MSSQL

Code Block

language	xml

<Resource name="jdbc/dac6datasource" auth="Container" type="javax.sql.DataSource"
               maxTotal="100" maxIdle="30" maxWaitMillis="10000"
               username="dac6" password="dac6" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
               url="jdbc:sqlserver://localhost:1433;databaseName=dac6" />

...

When using a Microsoft SQL Server

...

database driver with version greater than 10.x.x without encryption, the parameter “url” of the tag “resource” must be extended by “;encrypt=false (in this example url="jdbc:sqlserver://localhost:1433;databaseName=taxdatahub;encrypt=false")”

Windows authentication

(Optional for Microsoft SQL Server)

From the JDBC driver package, the appropriate “*.dll”-file must also be copied from the folder “auth” into the directory “System32” of the system.
Example path: .\sqljdbc_8.2.2.0_deu\sqljdbc_8.2\deu\auth\x64\mssql-jdbc_auth-8.2.2.x64.dll

...

The Windows user must be entered in Tomcat
1. The user needs permissions on the server of the Tomcat to run the Tomcat service as well as write permissions in the Tomcat folder for logs.
2. The user needs permissions on the database server.
3. The user needs the above-mentioned permissions on the database schema.
The connections in the context.xml must correspond to this example:
Code Block
language xml
<Resource name="jdbc/dac6datasource" type="javax.sql.DataSource"

...

         maxTotal="100" maxIdle="30" maxWaitMillis="10000

...


         driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"

...


         url="jdbc:sqlserver://[SERVER-NAME];DatabaseName=[DATABASE_NAME];Integratedsecurity=true"/>

Einrichtung der Deployments

Die folgenden Schritte richten die Webapplikationen ATP und DAC 6 auf dem "Tomcat 8.5"-Applikationsserver ein.

Kopieren und entpacken Sie die war-Dateien aus dem Auslieferungspaket in das „\webapps“-Verzeichnis im Tomcat-Installationsverzeichnis. Sie können das Paket selbstverständlich zunächst an einen anderen Ort editieren, um dort die Konfiguration vorzunehmen, und nach Fertigstellung nach „\webapps“ kopieren.
Nun konfigurieren Sie folgende Dateien unterhalb dieses Ordners:
1. "\WEB_INF\classes\META-INF\persistence.xml":
  1. Bei Verwendung einer JNDI-Verbindung
    1. Keine Anpassung in der "persistence.xml"-Datei notwendig
  2. Bei direkte Angabe der Datenbankverbindung
    1. Löschen Sie die Zeile mit dem XML Tag "<non-jta-data-source>" vollständig
    2. Kommentiern Sie den "<properties>" XML Block ein
    3. Kommentieren Sie den Block für Ihr eingesetztes DBMS ein und die anderen Blöcke aus
    4. Passen Sie IP/Hostname des Datenbankservers, den Datenbanknamen und Benutzer/Passwort entsprechend den unter dem Punkt „Datenbank“ gewählten Parametern an.
2. "\migration\sql\common\V20200113100000000__Insert_TSETTING.sql":
  1. Ändern Sie die URL zum Wert "OPENID_ATP_PATH"
  2. Hier muss die URL angegeben werden, unter der das ATP in Ihrem Netzwerk öffentlich erreichbar ist.
    1. Z.B. "http://demo.amana.de/atp"
  3. Ändern Sie die URL zum Wert "OPENID_DAC6_PATH"
  4. Hier muss die URL angegeben werden, unter der das DAC 6 in Ihrem Netzwerk öffentlich erreichbar ist.
    1. Z.B. "http://demo.amana.de:8080/dac6"
  5. Nur so kann sichergestellt werden, dass sich DAC 6 ordnungsgemäß beim ATP registrieren kann und letztendlich die Weiterleitung funktioniert.
3. "\migration\sql\common\V20200515000000000__Insert_TSETTING.sql":
  1. Ändern Sie die URL zum Wert "API_ATP_PATH"
  2. Hier muss die URL angegeben werden, unter der das ATP in Ihrem privaten Netzwerk erreichbar ist.
    1. Z.B. "http://servername/atp"
  3. Ändern Sie die URL zum Wert "API_DAC6_PATH"
  4. Hier muss die URL angegeben werden, unter der das DAC 6 in Ihrem privaten Netzwerk erreichbar ist.
    1. Z.B. "http://servername:8080/dac6"
  5. Nur so kann sichergestellt werden, dass DAC 6 und ATP untereinander kommunizieren können.

Start und Aktivierung

Starten Sie nun den Tomcat Applikationsserver, auf dem Sie das ATP installiert haben, entweder unter den Systemdiensten oder mit der „Configure Tomcat“ Applikation.
Warten Sie bis der Server gestartet wurde.
Öffnen Sie einen unterstützten Browser und geben folgendes in die Adressleiste ein (beachten Sie den bei der Installation des Tomcats gewählten Port): "http://<IP-Adresse oder Hostname der Applikationsservers>:<Portnummer des Applikationsservers>/atp"
Es sollte nun eine Login-Seite laden, dort können Sie sich – Benutzer: superuser ; Passwort: test – einloggen und ihr Passwort ändern.
Navigieren Sie zum Dialog "Aktivierung".
Kopieren Sie den von uns per E-Mail an Sie versandten Aktivierungsschlüssel in das Eingabefeld "Schlüssel" und klicken Sie auf "Aktivierung hinzufügen".
In der Tabelle sollte nun das aktivierte Modul "DAC6" aufgelistet sein.
Starten Sie nun den Tomcat Applikationsserver, auf dem Sie das DAC 6 installiert haben, entweder unter den Systemdiensten oder mit der „Configure Tomcat“ Applikation.
Prüfen Sie, ob im ATP-Applikationsmenüs der Eintrag DAC 6 dargestellt wird und das Modul im Bereich Module mit den korrekten URL-Pfaden angezeigt wird.
Sollte bei einem der vorherigen Punkte ein Fehler auftreten, prüfen Sie bitte die unter Einrichtung der Applikation eingetragenen Parameter und nehmen Kontakt mit uns auf.
Überprüfen Sie abschließend die Inhalte der Log-Dateien "atp_system.log" und "atp_dbmigration.log" sowie "dac6_system" und "dac6_dbmigration.log" auf ERROR-Meldungen. Nehmen Sie bei Auffälligkeiten bitte ebenfalls Kontakt mit uns auf.

Manuelle Modulregistrierung

Nach Absprache mit AMANA kann es sein, dass die Registrierung des DAC 6 Moduls am ATP manuell erfolgen soll. In diesem Fall führen Sie bitte folgende Schritte durch:

...

Connection to the module Portal

The registration of the module on the portal is carried out directly with Tomcat java option parameters. The following parameters are necessary in any case:

-Ddac6.url.base=<URL of the module DAC 6>

-Ddac6.url.portal=<URL of the module Portal>

Optional to specify a different API address:

-Ddac6.url.api=<API URL of the module DAC 6>

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

Manual module registration

After consultation with AMANA, it may be that the registration of the DAC 6 module in the Portal is to be carried out manually. In this case, please carry out the following steps:

Java option in the DAC 6 Tomcat

If necessary, stop the DAC 6 Tomcat.
Please add the following parameter in the field "Java Options": "-Ddac6.manual.registration=true".

Register the DAC 6

...

module in the portal

Navigate in the portal to Administration → Modules.
Click on "Create".
Under "Module name" select the entry "DAC 6"

...

.
Enter the DAC 6 root URL under "Root URL"

...

(e.g.: "http://servername:8080/dac6")

...

.
Enter the DAC 6 login URL under "Login URL"

...

. This is usually the root URL + "/login" (

...

e.

...

g.: "http://servername:8080/dac6/login")

...

.
Enter the URL to the DAC 6 API under "Api URL"

...

. This is usually the root URL + "/

...

api" (

...

e.

...

g.: "http://servername:8080/dac6/

...

api").

...

Click on "Save".
Copy the new value under "Client ID"

...

into any text editor for temporary storage.
Copy the new value under "Secret" into the same text editor for temporary saving.
Click on "Back".

Enter "Client ID"

...

and "Secret"

...

Ersetzten Sie in folgendem Datenbankstatement den Ausdruck ${ClientId} durch die zwischengespeicherte "Client ID" und führen es gegen die DAC 6 Datenbank aus:

Code Block

language	sql

INSERT INTO TSETTING (SETTINGKEY, SETTINGVALUE, SETTINGTYPE) VALUES('OPENID_CLIENTID', '${ClientId}', 2);

Ersetzten Sie in folgendem Datenbankstatement den Ausdruck ${Secret} durch das zwischengespeicherte "Secret" und führen es gegen die DAC 6 Datenbank aus:

Code Block

language	sql

INSERT INTO TSETTING (SETTINGKEY, SETTINGVALUE, SETTINGTYPE) VALUES('OPENID_CLIENTSECRET', '${Secret}', 2);

...

Abschließende Bemerkungen

Die Software kann nun den Fachabteilungen zur Benutzung oder fachlichen Tests übergeben werden.

Zum Abschluss noch einige Anmerkungen:

...

as Tomcat Runtime Parameter

-Ddac6.clientId=<Character String from the portal - ClientId>

-Ddac6.clientSecret=<Character String from the portal - ClientSecret>

DAC 6 Restart Tomcat

Communication with Transfer Service ELMA

If you want to use the Transfer Service to the German Tax Authority of AMANA for the automatic transfer of the declaration to the tax authorities, an additional parameter is necessary.
This parameter activates the regular retrieval of the processing logs.

-Ddac6.scheduler.autostart=true

In a setup with several Tomcats and a load balancer, the parameter should only be set for one Tomcat, as otherwise competing accesses and errors can occur during retrieval.

Communication with other GTC Suite modules (API key)

For secure communication with other modules in the GTC Suite, an API key has to be generated. You can access the documentation via this link.

Deployment setup

The following steps set up the DAC 6 module on the "Tomcat 9" application server.

Copy and unpack the war file from the delivery package into the "\webapps" directory in the Tomcat installation directory. You can, of course, first edit the package to another location to do the configuration there and copy it to "\webapps" when finished.
If you use JNDI (recommended by AMANA) for the data connection, no further adjustments are necessary.
When specifying the database connection directly, proceed as follows:
1. Edit the file "\WEB_INF\classes\META-INF\persistence.xml".
2. Delete the line with the XML tag "<non-jta-data-source>" completely.
3. Comment out the "<properties>" XML block.
4. Comment in the block for your DBMS and comment out the other blocks.
5. Adjust the IP/host name of the database server, the database name and user/password according to the parameters selected under the item "Database".

Use of Self-Signed Certificates

If you have integrated a self-signed TLS/SSL certificate in Tomcat, it can happen that HTTP requests from this module to other modules cannot be carried out. In this case, enter the following parameter in the "Java Options" field in Tomcat. This explicitly allows the use of self-signed certificates in the application. This configuration is generally not recommended for productive systems.

-Ddac6.api.allowSelfSignedCertificat=true

Start

Start the Tomcat application server on which you have installed the service module, either under System Services or with the "Configure Tomcat" application.
Wait until the server has started.
Whether the service module has been configured correctly and is accessible from other modules can be checked via the module view of the portal. To do this, log in to the portal with administration rights and click on Modules in the Administration tab.
The service module appears in the list and is indicated by a green traffic light. If the traffic light is yellow, check the connection properties to see whether the corresponding paths have been maintained correctly and check whether the https connection has been maintained correctly.

Concluding remarks

The software can now be handed over to the departments for use or professional testing.

Finally, a few comments:

We would like to recommend that you make a regular backup of the database, as this contains the data of the application.
The deployment does not have to be backed up constantly. Here it is sufficient to have the status ready when a version is delivered.

Page Comparison

Versions Compared

Old Version 10

New Version Current

Key

Vorwort

Prüfung der Vorbedingungen

Infrastruktur

Installation der Datenbank

Preamble

Checking the preconditions - infrastructure

Installation of database

Installation des Web Application Servers

Installation des JDK

Installation des "Tomcat 8.5"

Konfiguration des "Tomcat 8.5" nach der Installation

Installation of the Web Application Server

Installation of the JDK

Installation of the "Tomcat 9"

Configuration of the "Tomcat 9"

Memory

HTTPS

Connection to the database

Database driver

Configuration

Windows authentication

Einrichtung der Deployments

Start und Aktivierung

Manuelle Modulregistrierung

Connection to the module Portal

Manual module registration

Java option in the DAC 6 Tomcat

Register the DAC 6

module in the portal

Enter "Client ID"

and "Secret"

Abschließende Bemerkungen

as Tomcat Runtime Parameter

DAC 6 Restart Tomcat

Communication with Transfer Service ELMA

Communication with other GTC Suite modules (API key)

Deployment setup

Use of Self-Signed Certificates

Start

Concluding remarks