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.
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.
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.
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:
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.
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-9d93-000001c6051a
Detailed log: false
Test ID: false
Connection Timeout: 120
Response Timeout: 120
Print Directory: C:\usr\sap\ASD\J02\j2ee\eric ======================================================
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.
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
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
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.
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;
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”.
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
You will then find 2 certificates issued by ELSTER in the "Personal" tab of the certificate management with friendly name “encryptionkey” and “signaturekey”.
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:
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" ?>
<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:
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.
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.
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”.
Properties:
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:
To remove the error, verify that all aliases and the key store view name are correct.
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.
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)
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 "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.
Example for daten art version matrix:
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.
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
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:
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-9d93-000001c6051a
Detailed log: false
Test ID: false
Connection Timeout: 120
Response Timeout: 120
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.
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
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
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.
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”.
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 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:
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" ?>
<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:
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.
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”.
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 nt: getKeyStoreMan ager | KeyStoreManager: com.sap.aii.security.impl.keystore.KeyStoreManagerImpl SystemLevel. | ||
| 11:56:26:339 | undefined | System[10] | ~sfProfileKeySto reImpl.getPrivate Key | KeyStoreException. 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: 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. 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) |
| 11:56:26:340 | undefined | ~d.KeyStoreMan agerThread Method: run | A KeyStore- 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. 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.
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.
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)
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 "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.
- SAP Managed Tags:
1 Comment
