Download ELSTER Modules for PIPO with ERiC libraries

Configuration Document
The new ELSTER solution is designed and developed to wrap native OS libraries that are provided by
the German tax authorities (ERiC). It is using completely different approach from technical point of
view to distribute the ELSTER payload that is sent from the HR or FI business system.

PROJECT STRUCTURE
The new ELSTER SCA file contains the following components :
1. fi~elster_appl.sda – This SDA file is the ELSTER application itself. It contains two projects. Web
part, that is responsible for deploying and loading the native libraries, and the ELSTER modules.
2. fi~eric_lib.sda – This is java library that wraps the ERiC api. It is used from the ELSTER modules to
call the native libraries API.
3. fi~eric_win.sda – This SDA contains the native ERiC libraries that must be deployed in order to
have successful transfer of the ELSTER payload to the German tax authorities. This library triggers
offline deployment. This means, that the cluster will be automatically restarted during deployment !
4. fi~jna_lib.sda – JNA java library used by the fi~eric_lib.sda to wrap the native libraries.
All this components must be deployed in order to have a working solution. Also, the start of the
application must be without errors.
When the deployment and start is successful, you will see the elster application started successfully
in NWA.

APPLICATION LIFECYCLE
1. DEPLOY: On this stage the ELSTER SCA is triggered for deployment. Since the deployment is offline
the system will be restarted.
2. STARTING: The starting mechanism is handled by the WEB part. The class that implements the
logic is “com.sap.fin.elster.web.ContextListenerImpl”, so In order to troubleshoot any potential issues
regarding the start of the application we need to run XPI Inspector traces with example 100 (Custom)
with “com.sap.fin.elster” and since the WEB application is using the ERiC wrapper we need
“com.sap.fin.eric.wrapper” as well. You can see example trace below.
2.1. Example with fresh deploy of the libraries or update. Please note that in order to extract any files
on the file system, the “Archive hash” and the “logged hash” values must be different.
Page 1 of 17
2021.11.02
Configuration Document
2.2 Example with native libraries that are already deployed. Please take in mind that this error occurs
on two conditions. The ericapi.dll is really missing for some reason or, more likely, the ericapi.dll is
already loaded in the JVM (not an issue at all). More information from the java documentation:
UnsatisfiedLinkError – if either the filename is not an absolute path name, the native library is not
statically linked with the VM, or the library cannot be mapped to a native library image by the host
system.
Other issue, for example wrong libraries for the current OS also occurs with UnsatisfiedLinkError,
however the error message is different.
Also during the starting phase, the Datenartversionmatrix.xml is build to objects and stored in a local
cache that will be used durng runtime.
3. STARTED – The application is started without errors and the native libraries are loaded by the
JVM. Please not that once the native libraries are loaded, they can not be unloaded from the JVM. For
update of the libraries the JVM must be restarted.
4. MESSAGE PROCESSING – The application is already started and it is processing messages. The
message processing. More information about message processing troubleshooting can be found in in
the MESSAGE PROCEESING part of this document.
5. STOPPED – The application is stopped either by user interaction or because it has failed to start. 6.
UNDEPLOYED – Best possible state, because no application = no issues.

FILE SYSTEM
When the application is deployed and starting, it is trying to extract the contents of the eric_win
library on the file system. The files extracted has the following structure:
Page 2 of 17
2021.11.02
Configuration Document
Certificates folder – The all mighty and powerful ERiC API can use certificates that are only stored on
the file system. And because of that, one every message we export the required certificate from the
NW keystore and place it in the “certificates” folder. The certificate is in PFX format has the XI
message ID for file name.
Eric.log file – This file contains all logs that the ERiC API is writing. It is very useful if the message fails
during validation or any other ERiC specific issues.

MESSAGE PROCESSING
The new ELSTER solution is very flexible. It can use the data provided by the partner system but does
not rely on it. What does this mean?
There are three possible scenarios that can be handled by the modules. The module chain and the
configuration are always the same.
1. Plain ELSTER payload.
2. rfc:FI/HR_DE_B2A_ELSTER_XI xmlns:rfc=”urn:sap-com:document:sap:rfc:functions
3. BASE 64 Encoded ELSTER payload in new format, that is part of the RFC format in point 2. – The
real productive scenario!!!
In order to have a working scenario we need to have successfully build ERiC context. This context
represents this and can be seen in the traces of every message.
ERiC Context:
======================================================
Eric API Path: C:\usr\sap\ASD\J02\j2ee\os_libs\eric\win\ericapi.dll
Eric Log Path: C:\usr\sap\ASD\J02\j2ee\os_libs\eric
Datenart Version: UStVA_2019
Verfahren: ElsterAnmeldung
Proxy: null:null
Proxy Username: null
Certificate Path: C:\usr\sap\ASD\J02\j2ee\os_libs\eric\certificates\7ee98b68-456c-11e9-9d93000001c6051a
Detailed log: false
Test ID: false
Connection Timeout: 120
Response Timeout: 120
Page 3 of 17
2021.11.02
Configuration Document
Print Directory: C:\usr\sap\ASD\J02\j2ee\eric
======================================================












Eric API Path: This is the path to the “ericapi” file on the file system. Without this file we can
not use the ERiC API;
Eric Log Path: This is the directory where the ERiC library will create the eric.log file. If this
folder is missing or there are issues with the permissions the message processing will fail.
Datenart Version: To use the ERiC API we need to tell it wat is the datenart version of our
ELSTER payload. The ELSTER module determine the datenart version differently in the
different scenarios. For scenario 1 and 2. The datenart version is extracted from the ELSTER
payload with the help of the Datenartversionmatrix.xml
If you run XPI inspector traces with example 100 and all *.elster.* and *.eric.* locations. In the
3rd scenario the datenart version is provided by the HR/FI system as part of the new format.
Verfahren: This is the type of the ELSTER payload. It is used to determine additional
processing steps. E.g. whether or not the payload can be printed in PDF format and other
ERiC specific stuff that are not visible by the end user.
Proxy: Proxy configuration, host and port. E.g. proxt:8080
Proxy Username: Username, if needed, for the proxy authentication
Certificate path: The path to the PFX file that is extracted from the keystore. The certificates
are provided either in the module or application configuration or from the payload in
scenario 3.
Detailed log: Debug traces for the ERiC library (eric.log file)
Test ID: Whether or not the ERiC library should put test marker in the payload
Print Directory: This is the directory where (if set) the payload will be printed in PDF format.
When the context is built successfully is all up to ERiC to validate and send the payload. If
there are any errors the ERiC API is returning error codes. Further information can be found
in the eric.log file.
CONFIGURATION CHANGES TO BE DONE IN PI
Actual data sending is carried by the ERiC application and not by the SOAP receiver channel anymore,
which is why to SOAP receiver must point to the own host. This also lead to scenario changes as there
is no need for 4 separate receivers and their 4 corresponding SOAP receiver channels. Follow the
configuration described in SAP Note 2745249 – Implementation of ELSTER modules using the ERiC
libraries (check the attachment in the SAP Note):
1. Remove the RFC_To_Elster operation mapping for FI scenarios.
The operation mapping RFC_To_Elster must be removed from the scenario If it’s not removed it can
lead to message processing errors described in KBA 2887097 – Elster ERiC errors –
org.xml.sax.SAXParseException; lineNumber: 1; columnNumber: 50; The processing instruction
target matching “[xX][mM][lL]” is not allowed. The following steps describe how to remove the
mapping:
1.1. Assign the receiver inbound Elster_In interface to your receiver component (example:
ElsterServer1) with the set party (example:Clearing_house)
1.2. Remove the receiver interface line in the ICO’s receiver interfaces tab or if you use a classical
scenario, remove it from the interface determination tab.
1.3. Add back a receiver interface with in the ICO’s receiver interfaces tab or if you use a classical
scenario, add it from the interface determination tab by selecting the interface only without the
mapping.
Page 4 of 17
2021.11.02
Configuration Document
2. Keep the RFC sender channel untouched and make the changes on SOAP receiver channel:
2.1. Change the target URL to:
http://[NW_Java_Server_HTTP_host]:[NW_Java_Server_HTTP_port]/ELSTER/elster-echo
This is needed because with the introduction of ERiC application, the actual data sending is carried by
the ERiC application and by the SOAP receiver channel anymore, which is why to SOAP receiver must
point to the own host.
Any reference to the old URLs like below is incorrect and will cause message processing
failure,e.g:
http://62.157.211.58/Elster2/EMS –> http://datenannahme1.elster.de/Elster2/EMS
http://62.157.211.59/Elster2/EMS –> http://datenannahme2.elster.de/Elster2/EMS
http://80.157.84.22/Elster2/EMS –> http://datenannahme3.elster.de/Elster2/EMS
http://80.157.84.22/Elster2/EMS –> http://datenannahme4.elster.de/Elster2/EMS
2.2. Checking the Module Sequence
The SOAP Receiver Communication Channel must have the same Module and Module Parameter
settings. In the XPI Inspector trace file, click on the name of one of the SOAP Receiver Communication
Channels. The sequence of the Modules must look like this:
For HCM module configuration:
1. sap.com/com.sap.fin.xi.elster/ElsterHCMSendModule
2. sap.com/com.sap.aii.af.soapadapter/XISOAPAdapterBean
3. sap.com/com.sap.fin.xi.elster/ElsterHCMReceiveResponseModule
For FI module configuration:
1. sap.com/com.sap.fin.xi.elster/ElsterSendModul
2. sap.com/com.sap.aii.af.soapadapter/XISOAPAdapterBean
3. sap.com/com.sap.fin.xi.elster/ElsterReceiveResponseModul
Page 5 of 17
2021.11.02
Configuration Document
If the used modules and their order is not exactly the same as above, it can lead to message
processing errors highlighted in KBA 2887677 – Elster ERiC errors – got unexpected document
type:DOC_TYPE_UNKNOWN.
The usage of sap.com/com.sap.fin.xi.elster/ElsterHCMConvertRFCToElster or
AF_Modules/XMLAnonymizerBean is deprecated and should be removed.
2.3. Remove the receiver determination rules and the additional receivers for FI scenarios.
Remove the receiver determination rules in the corresponding Integration Configuration’s (ICO)
receiver tab or in case of classical scenario in the Receiver Determination object. No rules are
required and only one receiver and therefore one receiver channel is needed. The ERiC application
will send the data to the 4 Clearinghouses. Make sure to change the receiver component to be one of
the previously used ones like ElsterServer1 and use this as the only one receiver without any receiver
determination rules.
If there receiver determination rules are not followed it can lead to message processing errors
described in KBA 2890604 – Elster ERiC errors – PI ERROR 01 VERSION
com.sap.engine.interfaces.messaging.api.exception.RetryControlException: Receiver Determination
did not find any receivers at all.
2.4. Remove the proxy settings from the channel configuration and move them to module parameters
or application properties:
use.proxy – > possible values true/false
http.proxy_host
http.proxy_port
potentially also:
http.proxy_user
pwd.proxy (http.proxy_password is the equivalent of this property in the Application Properties)
2.5. Set up the certificates in at least one of the modes below;
CONFIGURING THE CERTIFICATES IN THE ELSTER MODULES FOR
PI/PO

HOW the certificates are delivered ?
Usually the certificates are provided by the authorities in one PFX file. This file contains two keys,
accompanied by certificate chain. The keys are two, because they have different usage. One is with
key usage “key encipherment” and the other is with key usage “digital signature”.
In order to have working scenarios the PFX file must be split to two parts. One containing the private
key for encipherment and one for signature. This is required due to the way the NetWeaver Key Store
is importingcertificates.
1. Splitting the certificates With keystore explorer
Using KeyStore Explorer is very easy. Download KeyStore Explorer from source of your choice and
install it.
Then open your PFX file. You will see two entries: “signaturekey” and “encryptionkey”.
Page 6 of 17
2021.11.02
Configuration Document
Then right click -> Export -> Export Key Pair. Enter password and save the file.
Export both key pairs and import them in the NetWeaver Key Store.
2. Splitting the certificates With internet explorer




Start the certificate management in Internet Explorer via Tools –> Options. In the “Content”
tab, choose “Certificates”.
In the “Certificates” window, choose “Import#” to start the “Certificate Import Wizard”
Enter the file name of the “.pfx” file
Enter the password for the file and select “Mark this key as exportable”. Leave the other
settings unchanged
You will then find 2 certificates issued by ELSTER in the “Personal” tab of the certificate management
Page 7 of 17
2021.11.02
Configuration Document
with friendly name “encryptionkey” and “signaturekey”.






In the certificate list, select the signature certificate, and choose “Export#”
In the “Certificate Export Wizard”, select “Yes, export the private key”
Also select “Include all certificates in the certification path if possible”
Enter a password to protect the new file
Save the file with a new name
Repeat the steps for the encryption key
3. Importing the certificates in the key store
Start SAP NetWeaver Administrator at http://<host>:<httpport>/nwa.
Choose Configuration > Security > Certificates and Keys End
Using the “Add View” button create new Key Store View. In the default configuration the view is
named “elster_ag”. Then, using the “Import Entry” button import the two certificates, that you
exported previously. Rename the certificates if it is necessary. The default values are
“elster_ag_key_enc”, for the encryption key, and “elster_ag_key_sig”, for the signature key.
Your view should look something like that:
Page 8 of 17
2021.11.02
Configuration Document
Verify your certificates. They should look like that:
Page 9 of 17
2021.11.02
Configuration Document
4. Priority of certificates configuration
Certificates can be configured in 3 ways: with incoming payload, as module parameters or as Elster
application properties. The priority in descending order is: payload -> module -> application.
4.1.) The configuration for the certificates is sent with the payload from the HR or FI system. This is
checked with highest priority. In this case the XML has the following structure:
<?xml version=”1.0″ encoding=”ISO-8859-15″ ?>
Page 10 of 17
2021.11.02
Configuration Document
<SAP>
<DATTYPE>LSTA_2018</DATTYPE>
<URL/>
<CERTSTORE>
<CERT_VIEW>elster_ag</CERT_VIEW>
<CERT_AG>elster_ag_key</CERT_AG>
</CERTSTORE>
<TRACE/>
<ELSTER>Base64 ELSTER Payload</ELSTER>
</SAP>
The “CERT_VIEW” tag stands for the key store view in the NetWeaver key store.
The “CERT_AG” tag contains the name from which the aliases for the encryption key and the
signature key will be composed. For example:
<CERT_AG>elster_ag_key</CERT_AG> Encryption key alias – elster_ag_key_enc
Signature key alias – elster_ag_key_sig
<CERT_AG>my_other_certificate</CERT_AG> Encryption key alias – my_other_certificate_enc
Signature key alias – my_other_certificate_sig
In that case, you must have the keystore vie with name elster_ag (or whatever set up in the sender
HR or FI system) in NetWeaver java keystore and two entries with the necessary keypairs, ending
with _enc and _sig, as shown above.
4.2.) If the certificate parameters are not provided with the payload, they will be taken from the
module configuration. Set up the properties as shown below:
Page 11 of 17
2021.11.02
Configuration Document
4.3.) In the certificates are provided neither in the payload, nor as module parameters, you can set up
them as application properties. The same is valid for proxy settings.

TROUBLESHOOTING
1. Collecting XPI Inspector traces
The best way to troubleshoot these kind of scenarios is to trace the error with the XPI Inspector tool
(SAP Note 1514898).
1.1. Install XPI Inspector tool by deploying the EAR file which you were given in an OSS incident. It’s
crucial to install the latest version of the XPI Inspector tool as from version 6.6 a new Elster related
example is available.
Page 12 of 17
2021.11.02
Configuration Document
1.2. Open the URL http://<host>:<port>/xpi_inspector.
1.3. Check the version of the XPI Inspector in the system. Open the URL
http://<host>:<port>/xpi_inspector.
The RFC Sender Communication Channel, which connects the FI/HCM system to the PI system.
The SOAP Receiver Communication channel, where the ERiC application is triggered which transfers
data from the PI system to the Clearingstelle.
1.4. Start the XPI Inspector tool by clicking on Start button.
As soon as the error message appears, click on Stop to stop inspection of the tool.
1.5. Repeat the procedure from Step 2 but select Example 71 – Elster instead of Example 50 – XI
Channel. Both Example 50 and Example 71 can be relevant for the troubleshooting.
With older XPI Inspector versions – use it with example 100 (Custom), selecting the following
locations:
com.sap.fin.elster com.sap.fin.eric
com.sap.fin.xi.elster
Press “Start” and reproduce the issue.
In the traces you will see the loaded libraries paths, the payload, the properties, the keystore aliases
that are searched in the key store etc. – all the necessary information for troubleshooting.
1.6. Looking into the XPI Inspector trace file
Download the ZIP file to your local computer.
Unzip the archive and open result.html or index.html (later XPI Inspector releases).
2. In case of an error during the message processing like: “Unable to create EricContext due to
KeyStoreException: Certificates with aliases: my_invalid_alias_enc and my_invalid_alias_sig are either
invalid or does not exists”, the best way to check what is wrong is to use “XPI Inspector”.
Page 13 of 17
2021.11.02
Configuration Document
Properties:
Properties extracted
DATTYPE: LSTA_2018
Certificate View: elster_ag
Certificate Alias:
my_invalid_alias
Certificate aliases trace:
“Building certificate configuration with the following properties: Encryption
elster_ag:my_invalid_alias_enc Si gnature: elster_ag:my_invalid_alias_sig”
The actual errors:
11:56:26:337
~StoreManageme KeyStoreManager:
nt:
com.sap.aii.security.impl.keystore.KeyStoreManagerImpl
getKeyStoreMan SystemLevel.
ager
11:56:26:339 undefined System[10] ~sfProfileKeySto KeyStoreException. The requested keystore type is not
reImpl.getPrivate
available in the default provider package or any of the other
Key
provider packages that were searched.
[EXCEPTION]
java.security.KeyStoreException: getPrivateKey
( KeyStore, String, String )
Alias not in KeyStore Viewmy_invalid_alias_enc at
com.sap.aii.security.lib.keystore.ISsfProfileKeyStoreImpl.
getPrivateKey(ISsfProfileKeyStoreImpl.java:136) at
com.sap.aii.security.lib.keystore.ISsfProfileKey
StoreImpl.<init>(ISsfProfileKeyStoreImpl.java:69) at
com.sap.aii.security.impl.keystore.KeyStoreManagerImpl.
getISsfProfile(KeyStoreManagerImpl.java:658) at
com.sap.aii.security.impl.keystore.KeyStoreManagerThread
Page 14 of 17
2021.11.02
Configuration Document
run(KeyStoreManagerThread.java:404) at
com.sap.engine.frame.core.thread.Task.run
(Task.java:73) at com.sap.engine.core.thread.impl5.
SingleThread.
execute(SingleThread.java:178) at
com.sap.engine.core.thread.impl5.SingleThread.
11:56:26:340 undefined
run(SingleThread.java:316)
~d.KeyStoreMan A KeyStoreagerThread
Method: run
Exception is encountered. Message: KeyStoreException in
Method: getPrivateKey( KeyStore, String, String ).
The requested
keystore type is not available in the default provider
package
or any of the other provider packages that were searched..
To-
String: java.security.KeyStoreException: KeyStoreException
in Method: getPrivateKey( KeyStore, String, String ).
The requested keystore type is not available in the default
provider package or any of the other provider packages that
were searched.
[EXCEPTION]
java.security.KeyStoreException: KeyStoreException in
Method:
getPrivateKey( KeyStore, String, String ).
The requested keystore type is not available in the
default provider package or any of the other provider
packages that were searched.
at com.sap.aii.security.lib.keystore.ISsfProfileKeyStoreImpl.
Page 15 of 17
2021.11.02
Configuration Document
getPrivateKey
(ISsfProfileKeyStoreImpl.java:158) at
com.sap.aii.security.lib.keystore.ISsfProfileKeyStoreImpl.
<init> (ISsfProfileKeyStoreImpl.java:69) at
com.sap.aii.security.impl.keystore.KeyStoreManagerImpl.
getISsfProfile(KeyStoreManagerImpl.java:658) at
com.sap.aii.security.impl.keystore.KeyStoreManagerThread
run(KeyStoreManagerThread.java:404) at
com.sap.engine.frame.core.thread.Task.run(Task.java:73)
at com.sap.engine.core.thread.impl5.SingleThread.
execute(SingleThread.java:178) at
com.sap.engine.core.thread.impl5.SingleThread.run
(SingleThread.java:316)
To remove the error, verify that all aliases and the key store view name are correct.
3. Check the ERiC application logs
The ERiC application is collecting logs in the
folder /usr/sap/<systemID>/<instanceID>/j2ee/os_libs/eric in the file called eric.log. This log file
can reveal any validation, connection errors. The default log level is INFO but this can be increased so
that the whole processing by the ERiC application is logged. There are two ways to increase it the log
level.
3.1. Increase the ERiC application’s log level in a channel
Open the Integration Builder of your PI/PO system and navigate to the SOAP receiver channel. In the
receiver SOAP channel configuration go to the Module tab and set the module parameter with
parameter name “log.detailed” and parameter value “true” for the
module sap.com/com.sap.fin.xi.elster/ElsterHCMSendModule
(HCM) or sap.com/com.sap.fin.xi.elster/ElsterSendModul (FI)
3.2. Increase the ERiC application’s log level at application level
Open NWA → Configuration → Infrastructure → Java System Properties →
Applications → fi~elster_appl → Change the log.detailed property from false to true. The property is
online changeable.
PROPERTIES
Most of the properties are described in note 2745249 – Implementation of ELSTER modules using
the ERiC libraries.
There is one additional property related to Elster modules error response enhancing – you can
configure how you would want the error message using the property module parameter
Page 16 of 17
2021.11.02
Configuration Document
“validation.error.type” for the module sap.com/com.sap.fin.xi.elster/ElsterHCMSendModule
(HCM) or sap.com/com.sap.fin.xi.elster/ElsterSendModul (FI)
Possible supported values are:
Values:
“default” – Fail the message in PI. This is the deafult value in order to keep backward compatibility.
“xml” – Return XML response to the ABAP system
“text” – Return the exception text to the ABAP system
For more details please refer to SAP Note 2905852 – ELSTER modules error response enhancing.

DATENART VERSION MATRIX
Example for daten art version matrix:

Summary
In this blog post we had a general information, configuration and troubleshooting guide for the ERiC
scenarios which is relevant for the new Elster implementation introduced with SAP Note 2745249 –
Implementation of ELSTER modules using the ERiC libraries.
Page 17 of 17
2021.11.02