- SAP Managed Tags:
The new ELSTER solution is designed and developed to wrap native OS libraries that are provided by the German tax authorities (ERiC). From technical point of view, the payloads sent out from HCM or FI system goes through PI/PO with a simple RFC to SOAP scenario. The technical implementation of signing, encryption and HTTP data transmission to Elster authorities is completely in the delivered by the authorities ERiC libraries at Elster online portal (https://www.elster.de/)
The procedure of setting up ELSTER 2.1 with ERiC on your PI/PO system is as follows below.
Install the XI/PI-specific ABAP sections in the ERP or HCM system
Note 2745035 describes the must-have libraries ERP side for FI scenarios and note 2558316 deals with HCM systems and required components.
Deploy of the NW PI/PO Java modules and the XI content
Maintain the certificates and maintain the Java Keystore
Certificates are obtained by Elster authorities at https://www.elsteronline.de/eportal/
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 importing certificates.
1. Splitting the certificate
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.
- 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”.
2. 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:
Verify your certificates. They should look like that:
Set up IFlows/Scenarios in Integration Directory
Create a configuration scenario in relation to the integration scenario "Elster_VAT", namespace "http://sap.com/xi/ELSTER/VAT/2005" from ESR - for FI scenario and "Elster_HCM", namespace http://sap.com/xi/ELSTER/HCM/2009 - for HCM scenarios.
If done properly, you will have a scenario with RFC sender channel and SOAP receiver channel in Integration Directory.
In case there are issues with using the templates from ESR, create the following scenario manually in Integration Directory or create an IFlow in NWDS:
You can find additional information about the RFC adapter in the SAP NetWeaver documentation under XI/PI section.
The channel is quite trivial and has nothing additionally to be set up. The Program ID must be corresponding to the Registered Server program ID in the sender ABAP system (HCM or ERP).
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
By default, no module parameters are necessary. The modules must be with exactly these names and in exactly this order.
HCM
FI
Name Elster_In
Namespace: http://sap.com/xi/ELSTER/VAT/2005 for FI(VAT) scenarios or http://sap.com/xi/ELSTER/HCM/2009 for HCM scenarios.
HCM
FI
HCM
FI
Activate the change list in the Integration Directory.
Create an RFC connection in the ERP system
Create an RFC connection in the HCM system
****************************************************************************************************************
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:
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:
Encryption key alias – elster_ag_key_enc
Signature key alias – elster_ag_key_sig
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.
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:
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.
Download the ZIP file to your local computer. Unzip the archive and open result.html or index.html (later XPI Inspector releases).
In case you cannot deal yourself with the error, attach the traces to the reported incident to SAP Support.
Note 2745249 contains most of the properties of Elster/ERiC modules, as well as some known issues.
This blog describes how to set up from scratch Elster with ERiC scenarios on your PI/PO system.
If you already have the scenario setup with previous Elster versions, visit the following blog for the changes that should be done: https://blogs.sap.com/2021/01/12/elster-modules-for-pi-po-with-eric-libraries/
The procedure of setting up ELSTER 2.1 with ERiC on your PI/PO system is as follows below.
Install the XI/PI-specific ABAP sections in the ERP or HCM system
Note 2745035 describes the must-have libraries ERP side for FI scenarios and note 2558316 deals with HCM systems and required components.
Deploy of the NW PI/PO Java modules and the XI content
- Obtain the latest version of the SAP XI Content Elster 2.1 or 2.2 and import it in ESR of the configured PI/PO system. (Tools -> Import Design Objects -> select the extracted .tpz file on the file system). There is no actual difference between ELSTER 2.1 and ELSTR 2.2 content but we strongly recommend updating the content as well, if you have upgraded to ELSTER 2.2
- Download and deploy the latest ELSTER 2.1 SCA from SAP Service Marketplace and deploy it on the PI/PO system. For ELSTER 2.2 you need to download the latest ELSTER 2.2 SCA file AND the latest ELSTERLIBS .SAR file as per your OS. Follow SAP Note 3106691 for details.
Maintain the certificates and maintain the Java Keystore
Certificates are obtained by Elster authorities at https://www.elsteronline.de/eportal/
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 importing certificates.
1. Splitting the certificate
- 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.
- 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
2. 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:
Verify your certificates. They should look like that:
Set up IFlows/Scenarios in Integration Directory
Create a configuration scenario in relation to the integration scenario "Elster_VAT", namespace "http://sap.com/xi/ELSTER/VAT/2005" from ESR - for FI scenario and "Elster_HCM", namespace http://sap.com/xi/ELSTER/HCM/2009 - for HCM scenarios.
If done properly, you will have a scenario with RFC sender channel and SOAP receiver channel in Integration Directory.
In case there are issues with using the templates from ESR, create the following scenario manually in Integration Directory or create an IFlow in NWDS:
- Configuration of the Sender channel (RFC adapter):
- Create a business system (service without partners) for the ERP system in the System Landscape Directory of the PI system.
- Create a communication channel with Adapter type "RFC", type "Sender".
- Enter the Gateway Application Server and Service of the ERP system (see transaction SMGW in the ERP system), as well as a user-defined program ID.
- Enter the logon data for the RFC metadata repository, use the message server (for load balancing) or an application server of the ERP system.
You can find additional information about the RFC adapter in the SAP NetWeaver documentation under XI/PI section.
The channel is quite trivial and has nothing additionally to be set up. The Program ID must be corresponding to the Registered Server program ID in the sender ABAP system (HCM or ERP).
- Configuring the receiver channel (SOAP adapter):
- On the "Parameter" tab, select the required Adapter Engine (the Adapter Engine on which the Java module is running).
- Enter the Target URL: 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. The host and port must point to the load-balancer in case of more than one instance.- Select "Do Not Use SOAP Envelope" under Conversion Parameters section
- On the "Module" tab under "Processing sequence" define the following module sequence:
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
By default, no module parameters are necessary. The modules must be with exactly these names and in exactly this order.
- Save the configuration scenario and create Integrated Configuration. Alternatively, the same setup can be done via IFlow in NWDS
- Create Integrated Configuration and fill the fields with the Sender RFC channel details with Interface FI_DE_B2A_ELSTER_XI (for FI scenarios) or HR_DE_B2A_ELSTER_EXPORT (for HCM scenarios), and namespace in both cases urn:sap-com:document:sap:rfc:functions.
HCM
FI
- In tab "Inbound Processing" specify the RFC Sender channel
- In tab "Receiver" add the Service (Communication Components) that contain the receiver SOAP channel for the scenario. In the example below, the same receiver component is used with different SOAP receiver channels per scenario.
- In tab "Receiver Interfaces" under Receiver Interfaces section specify the following :
Name Elster_In
Namespace: http://sap.com/xi/ELSTER/VAT/2005 for FI(VAT) scenarios or http://sap.com/xi/ELSTER/HCM/2009 for HCM scenarios.
HCM
FI
- In tab "Outbound Processing" select the Receiver SOAP Channel
HCM
FI
Activate the change list in the Integration Directory.
Create an RFC connection in the ERP system
- Use transaction SM59 to create a new RFC connection.
- Name FI_DE_ELSTER_XI
- Type T
- Activation type "Registered server program"
- Program ID, gateway host and gateway service as defined in the RFC sender channel in the Integration Directory.
Create an RFC connection in the HCM system
- Use transaction SM59 to create a new RFC connection.
- Name can be freely chosen, but it should be set up to be used in the system (constant RFCDE in table t50bk)
- Type T
- Activation type "Registered server program"
- Program ID, gateway host and gateway service as defined in the RFC sender channel in the Integration Directory.
****************************************************************************************************************
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.
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.elsterPress “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.
Download the ZIP file to your local computer. Unzip the archive and open result.html or index.html (later XPI Inspector releases).
In case you cannot deal yourself with the error, attach the traces to the reported incident to SAP Support.
Note 2745249 contains most of the properties of Elster/ERiC modules, as well as some known issues.
This blog describes how to set up from scratch Elster with ERiC scenarios on your PI/PO system.
If you already have the scenario setup with previous Elster versions, visit the following blog for the changes that should be done: https://blogs.sap.com/2021/01/12/elster-modules-for-pi-po-with-eric-libraries/
3 Comments
