Das Positionsanalyse-Modul „VAT-Audit“ repliziert steuerrelevante Belege mithilfe des Java-Connectors JCo aus der SAP-Datenbank in
eine lokale AMANA-Datenbank, um Analysen durchführen zu können. Auf Seite des VAT-Audit sorgt die AMANA-Schnittstelle DataGate für das Lesen und Schreiben der Daten; auf SAP-Seite kommt ein von AMANA angepasster RFC_READ_TABLE Baustein zum Einsatz.
Das in der SAP-Installation enthaltene BAPI (Business Application Programming Interface) „RFC_READ_TABLE“ dient zum Auslesen und Übertragen von SAP Datenbanktabellen. Die Breite der Datensätze ist auf 512 Zeichen beschränkt.
Es wurde zunächst überlegt, diesen Standardbaustein einzusetzen, aber dessen Implementierung ist für eine genaue und performante Analyse von Belegdaten unbrauchbar; man stünde vor der Herausforderung, eine große Anzahl von Datensätzen in Teilstücken über die Schnittstelle zu extrahieren und auf der Clientseite wieder zusammenzufügen.
Die Amana consulting GmbH hat den ABAP Quellcode des RFC_READ_TABLE so verändert, dass Datensätze von bis zu 2 KB übertragen werden können. Des Weiteren wurden Features wie z. B. die Unterstützung einer Order-By-Clause implementiert. Der AMANA-Baustein erhält einen eigenen Namen und eine eigene Function Group; er steht nicht mit dem Original in Konflikt, falls beide Funktionen parallel verwendet werden.
In diesem Dokument wird beschrieben, wie das AMANA BAPI im SAP-System installiert wird, um mit dem VAT-Audit zu kommunizieren.
Das Amana DataGate verwendet für den Remote Function Call (RFC)-Baustein den Standardport 33xx, um eine sichere und standardisierte Kommunikation zwischen den SAP-Systemen und unserer Anwendungen zu gewährleisten.
1. Ausgangslage
- AMANA ABAP "Z_READ_TABLE_RFC" auf allen SAP Servern einspielen (siehe '2.Installation des Bausteins Z_RFC_READ_TABLE')
(technischen) SAP-Account mit Leserechten für den Zugriff über JavaConnector (JCo) auf min. folgende SAP-Tabellen:
Stammdaten
Bewegungsdaten
KNA1
LFA1BKPF
BSEG
BSEC
BSETEine Erweiterung der Liste kann sich durch neue Prüfungen ergeben.
2. Installation des Bausteins Z_RFC_READ_TABLE
Um vom externen System VAT-Audit auf den von AMANA entwickelten Baustein Z_RFC_READ_TABLE zugreifen zu können, sind mehrere Einstellungen und Konfigurationen auf den beteiligten SAP-Servern notwendig. Zunächst wird eine Funktionsgruppe angelegt und schließlich der eigentliche Baustein konfiguriert und aktiviert.
SE80: Erstellen einer Funktionsgruppe
Für das von AMANA ausgelieferte BAPI muss auf dem SAP Server eine Funktionsgruppe ausgewählt werden. Für AMANA Programme kann unter der Transaktion SE80 eine neue Gruppe angelegt werden. Für Customer sind die Präfixe Y und Z reserviert und müssen verwendet werden. Die Gruppe wird als lokales Objekt angelegt.
SE37: Erstellen des BAPI
In der SAP-GUI wird die Transaktion SE37 aufgerufen um dort den AMANA-Baustein Z_RFC_READ_TABLE neu zu erstellen. Für den Baustein kann auch ein anderer Name gewählt werden, allerdings muss dies in Koordination mit AMANA geschehen, da dieser Name die wesentliche Vereinbarung ist, über welche die beiden Systeme VAT-Audit und SAP kommunizieren. Der Baustein wird der Function group Z_AMANA zugeordnet.
SE37 Konfiguration des BAPI
Nach dem Anlegen der Funktion werden die Reiter des Subdialogs nacheinander mit Werten befüllt. Grundeinstellungen (a), Eingabeparameter (b), Ausgabeparameter (c) Tabellen (d), Ausnahmen (e) und nicht zuletzt der Quellcode (f) müssen dem SAP-System bekannt gemacht werden.
a) Auf dem ersten Reiter des Subdialogs, “Eigenschaften”, wird die Option “Remote fähiger Baustein” gewählt.
b) Auf dem zweiten Reiter “Import” werden die Importparameter der Funktion hinterlegt:
c) Der Originalbaustein wurde um den Exportparameter RECORD_COUNT erweitert, der bei gesetztem Eingangsparameter nur die Datensätze zählt
d) Die verwendeten Tabellen werden im Reiter “Tabellen” konfiguriert. Hauptunterschiede zum Original-RFC sind die neue Order-By-Clause sowie die Struktur der Ausgabetabelle: TBL2048 statt TAB512.
e) Die Funktion wirft verschiedene Exceptions, die im Reiter “Ausnahmen” angegeben werden:
f) Schließlich wird der Quellcode der AMANA Implementierung in das Eingabefeld des Reiters Quelltext kopiert. Bereits vorhandener Code wird überschrieben. Anschließend wird die Funktion über das Icon in der Symbolleiste aktiviert.
3. SAP-Benutzer
Für den Datenabzug wird ein technischer SAP-Benutzer benötigt.
Folgende Berechtigungen werden benötigt.
- DDIF_FIELDINFO_GET (Funktionsbausstein)
- RFC1 (Funktionsgruppe)
- RFCPING (Funktionsbausstein)
- RFC_GET_FUNCTION_INTERFACE (Funktionsbausstein)
- RFC_METADATA_GET (Funktionsbausstein)
- SDIFRUNTIME (Funktionsgruppe)
- SYST (Funktionsgruppe)
- Z_AMANA (Funktionsgruppe)
Zusätzlich eine Leseberechtigung für die Prüfungsrelevanten Tabellen (siehe 1. Ausgangslage).
4. Vorbereitung VAT-Server
Damit Seitens des VAT-Audit eine JCO-Verbindung über die Schnittstelle aufgebaut werden kann muss im Tomcat-Server im Lib-Verzeichnis die Bibliothek SAPJCO3.jar und SAPJCO3.dll hinterlegt werden.
Anbindung der Datenbank
Variante 1: Konfiguration JNDI (Datasource) Datenbankverbindung mit Benutzer/Passwort
Kopieren Sie bitte den passenden JDBC Treiber in das lib-Verszeichnis des Apache Tomcat Servers (%TOMCAT_HOME%/lib).
In der context.xml des Apache Tomcat Servers muss innerhalb des <Context> Blockes ein passender Resource-Eintrag für die Datenbankverbindung angelegt werden:
Beispiel Datasource Eintrag für MSSQL:
<Resource name="jdbc/vatauditdatasource" auth="Container"
type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://[SERVER-ADRESS]:[PORT];DatabaseName=[DATABASE_NAME]"
username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
maxWaitMillis="-1"/>
Beispiel Datasource Eintrag für Oracle:
<Resource name="jdbc/vatauditdatasource" auth="Container"
type="javax.sql.DataSource" driverClassName="oracle.jdbc.OracleDriver"
url="jdbc:oracle:thin:@[SERVER-ADRESS]:[PORT]:[INSTANCE]"
username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
maxWaitMillis="-1"/>
Im Datasource Eintrag passen Sie bitte die SERVER-ADRESSE des Datenbankservers, den Datenbanknamen und Benutzer/Passwort entsprechend Ihrer aufgesetzten Datenbank an.
Variante 2: Konfiguration JNDI (Datasource) Datenbankverbindung mit Windows-User
Kopieren Sie bitte den passenden JDBC Treiber in das lib-Verszeichnis des Apache Tomcat Servers (%TOMCAT_HOME%/lib).
Die Datenbankverbindung in der context.xml des Tomcat-Servers kann alternativ über den Windows-User in dessen Kontext der Tomcat läuft aufgebaut werden. Dazu sind folgende Schritte durchzuführen:
Microsoft SSPI Treiber herunterladen (sqljdbc 7.0): https://www.microsoft.com/de-de/download/sqljdbc_7.0
Wichtig hierbei ist verwendete JAVA Version: Bei einem 64-bit JAVA wird x64-Version des Treibers benötigt, bei einem 32-bittigen Java entsprechend die x86-Version.
Der Treiber wird in einer selbstentpackenden EXE geliefert, die bspw. per 7-Zip entpackt werden kann oder alternativ kann der Treiber als tar.gz-Archiv heruntergeladen werden.
Kopieren Sie die sqljdbc_auth.dll aus dem Unterordner "/auth" in das "\windows\system32" Verzeichnis ihrer Windowsinstallation.
- Kopieren Sie aus dem Unterordner des Treibers "/jre8" die Datei sqljdbc42 in das "/bin"-Verzeichnis ihrer installierten JAVA-Version (die vom Tomcat verwendet wird).
In der context.xml des Tomcat-Servers muss ein passender Datasource-Eintrag für die Datenbankverbindung konfiguriert werden:
MSSQL Datasource<Resource name="jdbc/vatauditdatasource" type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver" url="jdbc:sqlserver://[SERVER-NAME]\SQLEXPRESS;DatabaseName=[DATABASE_NAME];Integratedsecurity=SSPI" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>Zudem muss der Windows-User in den "Tomcat Properties" eingetragen werden - siehe Abbildung:
Bitte beachten, dass der Benutzer auch die Berechtigung hat sich als „Dienst“ anzumelden, sonst startet der Tomcat nicht mehr.
TLS-Verbindung zum SQL-Server einrichten
Ab der Treiberversion 10.x von mssql-jdbc (Microsoft SQL-Server) muss eine Verbindung ohne TLS explizit konfiguriert werden, ansonsten geht der Treiber von einer TLS-Verbindung aus und erwartet dafür vorgesehen Zertifikate.
Um diese zu deaktivieren, muss die context.xml des Tomcat-Servers wie folgt erweitert werden:
<Resource name="jdbc/vatauditdatasource" auth="Container"
type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://[SERVER-ADRESS]:[PORT];DatabaseName=[DATABASE_NAME];encrypt=false;trustServerCertificate=true"
username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
maxWaitMillis="-1"/>
Entscheidend sind encrypt=false und trustServerCertificate=true in der url.
Wenn die TLS-Verbindung verwendet werden soll, dann werden folgende Informationen benötigt:
<Resource name="jdbc/vatauditdatasource" auth="Container"
type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://[SERVER-ADRESS]:[PORT];DatabaseName=[DATABASE_NAME];hostNameInCertificate=[HOST_NAME_IN_CERTIFICATE];trustStore=[TRUSTSTORE_LOCATION];trustStorePassword=[TRUSTSTORE_PASSWORD]
username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
maxWaitMillis="-1"/>
Der SQL-Server muss mit einen Zertifikat abgesichert sein und dieses muss sich in einem TrustStore/KeyStore befinden. Sowohl der Pfade zum TrustStore als auch das Passwort werden mitgegeben und zusätzlich der HostName im Zertifikat.
Informationen zu den Parametern:
Informationen zum Konfigurieren:
5. Verbindungstest
Auf der AMANA-Seite der Schnittstelle wird dem VAT-Audit die JCO-Verbindung bekannt gemacht. Der berechtigte Benutzer meldet sich im VAT-Audit (VAT@GTC) an und wechselt in den Dialog Einstellungen Verbindungsparameter. Dort hinterlegt er die Verbindungsdaten für den (technischen) SAP-Benutzer, der die Belegdaten über den RFC replizieren darf.
Neben Benutzername und Passwort sind die Parameter Host, Instanznummer, Client ID (Mandant) und der SAP Router die entscheidenden Einträge.
Über die Schaltfläche „Erweiterter Verbindungstest“ gelangt man in den Dialog, in welchem man den RFC ansprechen kann.
Verbindungstest
Im Erweiterten Verbindungstest der AMANA-Anwendung kann man sowohl den Original-RFC, als auch den durch AMANA angepassten Z_RFC_READ_TABLE ansprechen. Die Eingabeparameter QUERY_TABLE und DELIMITER werden unterstützt. Die Anzahl der zurückgegebenen Datensätze wird auf 100 beschränkt, so dass man den Verbindungstest auch gegen große Datenbanktabellen ausführen kann.
The position analysis module "VAT Audit" replicates tax-relevant documents from the SAP database to a local AMANA database using the Java connector JCo, a local AMANA database, in order to be able to carry out analyses.
On the VAT-Audit side, the AMANA interface DataGate takes care of reading and writing the data; on the SAP side, an RFC_READ_TABLE module adapted by AMANA is used.
The BAPI (Business Application Programming Interface) "RFC_READ_TABLE" included in the SAP installation is used to read and transfer SAP database tables. The width of the data records is limited to 512 characters.
It was initially considered to use this standard module, but its implementation is useless for accurate and performant analysis of document data; one would be faced with the challenge of extracting a large number of records in chunks via the interface and reassembling them on the client side. Amana consulting GmbH has modified the ABAP source code of the RFC_READ_TABLE in such a way that data records of up to 2 KB can be transferred.
Furthermore, features such as the support of an order-by-clause have been implemented. The AMANA module is given its own name and function group; it does not conflict with the original if both functions are used in parallel.
This document describes how to install the AMANA BAPI in the SAP system in order to communicate with the VAT-Audit.
The Amana DataGate utilizes the standard port 33xx for the Remote Function Call (RFC) module to ensure secure and standardized communication between the SAP systems and our applications.
1. Initial situation
- Install AMANA ABAP "Z_READ_TABLE_RFC" on all SAP servers (see '2.Installation of the module Z_RFC_READ_TABLE
(technical) SAP account with read rights for access via JavaConnector (JCo) to at least the following SAP tables:
Master data
Transaction data
KNA1
LFA1BKPF
BSEG
BSEC
BSETAn extension of the list may result from new examinations.
2. Installation of the module Z_RFC_READ_TABLE
In order to be able to access the module Z_RFC_READ_TABLE developed by AMANA from the external system VAT-Audit, several settings and configurations are necessary on the SAP servers involved. First, a function group is created and finally the actual module is configured and activated.
SE80: Creating a function group
For the BAPI delivered by AMANA, a function group must be selected on the SAP server. For AMANA programmes, a new group can be created under transaction SE80. For Customer, the prefixes Y and Z are reserved and must be used. The group is created as a local object.
SE37: Creating the BAPI
In the SAP GUI, transaction SE37 is called to create the AMANA module Z_RFC_READ_TABLE. Another name can also be chosen for the module, but this must be done in coordination with AMANA, as this name is the essential agreement through which the two systems VAT Audit and SAP communicate. The module is assigned to the function group Z_AMANA.
SE37 Configuration of the BAPI
After creating the function, the tabs of the sub-dialogue are filled with values one after the other. Basic settings (a), input parameters (b), output parameters (c) tables (d), exceptions (e) and last but not least the source code (f) must be made known to the SAP system.
a) On the first tab of the sub-dialogue, "Properties", the option "Remote capable module" is selected.
b) The import parameters of the function are stored on the second tab "Import":
c)The original module was extended by the export parameter RECORD_COUNT, which only counts the data records when the input parameter is set.
d) The tables used are configured in the "Tables" tab. The main differences to the original RFC are the new order-by-clause and the structure of the output table: TBL2048 instead of TAB512.
e) The function throws various exceptions, which are specified in the "Exceptions" tab:
f) Finally, the source code of the AMANA implementation is copied into the input field of the Source Code tab. Existing code is overwritten. Then the function is activated via the icon in the toolbar.
3. SAP-User
A technical SAP user is required for the data extract.
The following permissions are required.
- DDIF_FIELDINFO_GET (Functional building block)
- RFC1 (Function group)
- RFCPING (Functional building block)
- RFC_GET_FUNCTION_INTERFACE (Functional building block)
- RFC_METADATA_GET (Functional building block)
- SDIFRUNTIME (Function group)
- SYST (Function group)
- Z_AMANA (Function group)
In addition, a reading authorisation for the examination-relevant tables (see 1. Initial situation).
4. Preparation VAT server
The library SAPJCO3.jar and SAPJCO3.dll must be stored in the lib directory of the Tomcat server so that a JCO connection can be established via the interface on the part of the VAT audit.
Configuration database
Variant 1: Configuration of JNDI (Datasource) database connection with user/password
Please copy the appropriate JDBC driver into the lib directory of the Apache Tomcat server (%TOMCAT_HOME%/lib).
In the context.xml of the Apache Tomcat Server a corresponding resource entry for the database connection must be created within the <Context> block:
Example Datasource entry for MSSQL:
<Resource name="jdbc/vatauditdatasource" auth="Container"
type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://[SERVER-ADRESS]:[PORT];DatabaseName=[DATABASE_NAME]"
username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
maxWaitMillis="-1"/>
Example Datasource entry for Oracle:
<Resource name="jdbc/vatauditdatasource" auth="Container"
type="javax.sql.DataSource" driverClassName="oracle.jdbc.OracleDriver"
url="jdbc:oracle:thin:@[SERVER-ADRESS]:[PORT]:[INSTANCE]"
username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
maxWaitMillis="-1"/>
Please adjust the SERVER-ADRESS of the database server, the database name and the user/password in the Datasource entry according to your database.
Variant 2: Configuration of JNDI (Datasource) database connection with Windows user
Please copy the appropriate JDBC driver into the lib directory of the Apache Tomcat server (%TOMCAT_HOME%/lib).
The database connection in the context.xml of the Tomcat server can alternatively be established via the Windows user in whose context the Tomcat is running. The following steps have to be performed:
Download Microsoft SSPI driver (sqljdbc 7.0): https://www.microsoft.com/de-de/download/sqljdbc_7.0
The used JAVA version is important: A 64-bit JAVA requires the x64 version of the driver, a 32-bit Java requires the x86 version.
The driver is delivered in a self-extracting EXE, which can be unpacked e.g. by 7-Zip or alternatively the driver can be downloaded as tar.gz archive.
- Copy the sqljdbc_auth.dll from the subdirectory "/auth" into the "\windows\system32" directory of your Windows installation.
- Copy the file sqljdbc42 from the subdirectory of the driver "/jre8" into the "/bin" directory of your installed JAVA version (which is used by Tomcat).
In the context.xml of the Tomcat server a corresponding datasource entry must be configured for the database connection:
MSSQL Datasource<Resource name="jdbc/vatauditdatasource" type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver" url="jdbc:sqlserver://[SERVER-NAME]\SQLEXPRESS;DatabaseName=[DATABASE_NAME];Integratedsecurity=SSPI" maxTotal="20" maxIdle="10" maxWaitMillis="-1"/>In addition, the Windows user must be entered in the "Tomcat Properties" - see illustration:
Please note that the user also has the right to log in as a "service", otherwise Tomcat will not start anymore.
Setting up a TLS connection to the SQL server
As of driver version 10.x of mssql-jdbc (Microsoft SQL server), a connection without TLS must be explicitly configured, otherwise the driver assumes a TLS connection and expects certificates provided for this.
To disable this, the context.xml of the Tomcat server must be extended as follows:
<Resource name="jdbc/vatauditdatasource" auth="Container"
type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://[SERVER-ADRESS]:[PORT];DatabaseName=[DATABASE_NAME];encrypt=false;trustServerCertificate=true"
username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
maxWaitMillis="-1"/>
Crucial are encrypt=false and trustServerCertificate=true in the url.
If the TLS connection should be used, then the following information is needed:
<Resource name="jdbc/vatauditdatasource" auth="Container"
type="javax.sql.DataSource" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://[SERVER-ADRESS]:[PORT];DatabaseName=[DATABASE_NAME];hostNameInCertificate=[HOST_NAME_IN_CERTIFICATE];trustStore=[TRUSTSTORE_LOCATION];trustStorePassword=[TRUSTSTORE_PASSWORD]
username="[USERNAME]" password="[PASSWORD]" maxTotal="20" maxIdle="10"
maxWaitMillis="-1"/>
The SQL server must be secured with a certificate and this must be located in a TrustStore/KeyStore. Both the path to the TrustStore and the password are given, as well as the host name in the certificate.
Information about the parameters:
Information about configuring:
5. Connection test
On the AMANA side of the interface, the VAT audit is informed about the JCO connection. The authorised user logs into the VAT-Audit (VAT@GTC) and switches to the connection parameter dialogue under the settings tab. There he stores the connection data for the (technical) SAP user who is allowed to replicate the document data via the RFC.
Besides user name and password, the parameters host, instance number, client ID (client) and the SAP router are the decisive entries.
The button "Extended connection test" leads to the dialogue in which you can address the RFC.
Connection test
In the extended connection test of the AMANA application, one can address both the original RFC and the Z_RFC_READ_TABLE adapted by AMANA. The input parameters QUERY_TABLE and DELIMITER are supported. The number of returned records is limited to 100, so that the connection test can also be performed against large database tables.
