Cloud Integration – Usage of the Elster Adapter
This blog describes the Elster ERiC libraries used in the new Elster adapter provided in SAP Cloud Integration. The adapter is planned for the March-24-2019 update. In the blog the End-to-end configuration and the monitoring options are described, links to further information sources are given. Furthermore the current restrictions are listed.
ERiC@SAP: What is ERiC?
In the areas of HR (employment tax notification (LStA), employment tax statement (LStB), electronic employment tax deduction features (ELStAM)) and FI (advanced return for tax on sales/purchases (UStA)), electronic reporting data is transferred to the clearing house of the fiscal authority block for communication with the tax authorities.
Technical background: For the transfer, the data is summarized in an XML file, signed, and encrypted. The data is then transferred to the clearing house of the fiscal authority block.
The XML file is generated in the HR or FI system. From this system, the data is then transferred to the middleware used (Business Connector, PO/PI, or Cloud Integration). The signature, encryption, and transfer of the data from the employer’s network to the clearing house is done using the middleware.
Previous Solution – Open Interface
The standards used for the signature and encryption were published by the tax authority, as is the case for social insurance, and it was made possible for the software manufacturer to implement and deliver all components for the transfer using its own program components in its software solution. The solution is referenced to as an “open interface” in the ELSTER environment.
This model allows for a clear distinction between the software solutions involved and the parties responsible.
New Solution – ERiC
To support manufacturers when creating software products for communication with the tax authorities, the tax authorities have also been providing software components since the introduction of electronic communication. The software manufacturers can integrate these components into their products to minimize the implementation effort.
Initially Java-based program components were provided by the tax authority, now only fully compiled program components (C libraries) are provided. These are known as EriC (Elster Rich Client) libraries.
To make technical or subject-specific changes to the ERiC libraries, the tax authority updates the ERiC libraries twice a year (usually in May and November). The ERiC release in May delivers only technical changes but the subject-specific changes are provided with the main release in November. Therefore, you can find the bases necessary for the advance return for tax on sales/purchases (UStA) and the employment tax notification (LStA) for the subsequent year in the November release. This means that it is mandatory to include this ERiC main release in the manufacturer’s software. It must be delivered as soon as possible so that the ERiC libraries required for the new year can be used at the start of the year.
The new Elster Adapter provided in Cloud Integration uses those libraries to support the communication with the German tax authority. The ERiC libraries are updated automatically in Cloud Integration, there is no need for any manual action be the user of the integration scenario.
What changes does ERiC result in for the employer in the HR/FI system?
For the changeover to ERiC, some changes have to be made to the programs for transferring the tax notifications and to the HR/FI system.
The changeover from the previous solution to ERiC is done using Customizing in the HR/FI system. A prerequisite for this is that the ERiC-based solution has been imported or set up on the middleware used (Business Connector, PO/PI, Cloud Integration).
How does the ELSTER ERiC solution for Cloud Integration work?
The Cloud Integration solution for the Elster integration is based on two components. First of all, it is based on a newly created Elster adapter. It provides the latest ERiC libraries on the Cloud Integration tenant and offers an interface for using the functions contained in the libraries. The second component is the HR or FI-specific content that contains the integration flows for the communicating.
- The HR or FI application system sends tax data to the Cloud Integration tenant. The transfer is done using a HTTPS connection that was maintained using transaction SM59 in the application system.
- The HR or FI integration flow on the Cloud Integration tenant receives the tax data from the application system, sets the parameters required for calling the ERiC libraries (tax type, certificates, etc.), and passes on the data for transfer to the Elster adapter.
- The Elster adapter validates the XML data. This data is then signed, encrypted, and sent to the tax authority. The response provided by the tax authority is then received by the HR or FI integration flow, decrypted, and returned to the calling HR or FI application system.
In the Elster integration scenario in the Cloud Integration system, the following security relevant aspects are relevant:
- For the communication between the HR-/FI-system and the SAP Cloud Integration system, HTTPS is used. HTTPS is also used by ERiC for sending the data to the authority system.
- The message payload is received by and processed in the cloud integration system as configured in the integration flow. The message payload data is only processed in memory in the cloud integration system. The message payloads are not stored in the cloud system, neither in the database nor in the system log files.
- During processing of the message a message processing log is written and stored in the cloud integration system database for monitoring purpose. The message processing log only contains administrative data, like timestamps and the message ID, and the status of the message processing, but no message payload data. The message processing log is stored for 30 days and then automatically deleted. The access to the message processing log data is restricted to users with the Tenant Administrator or the Integration Developer role assigned in this integration tenant.
- In case of an error during message processing, the error message is stored in the SAP Cloud Integration system in the message processing log and in the system log file. The system log file is stored for 7 days and automatically deleted afterwards. The access to the system log is restricted to the Tenant Administrator and the Integration Developer of the respective integration tenant.
- If the log level for the integration artifact is set to TRACE (see blog Enabling Trace for Message Processing) for error analysis, also the payload is stored in the systems database. The access to this payload data is restricted to users with the Business Expert role assigned in this integration tenant. The trace data is stored for 1 hour only and automatically deleted afterwards.
If you want to know more about security aspects of SAP Cloud Integration and how customer specific data is secured, check out the help chapter Security. Various aspects of privacy and data storage security are discussed there.
Overview for Setting up the ELSTER ERiC Scenario in Cloud Integration
Initial Configuration of the Cloud Integration Tenant
Setup and configure the Cloud Integration tenant as described in the Get Started documentation for SAP Cloud Integration.
Configure Integration Flow
- Select the required Integration Package ‘SAP HR ELSTER ERIC for Germany’ or ‘SAP Finance Applications Integration with ELSTER’ in the content store.
- Deploy the required integration flow as described in the configuration guide contained in the integration package.
- Retrieve the inbound end point of the integration flow from the Monitoring -> Monitor Integration Content -> End Points.
Set up the HTTPS connection
To setup a secure HTTPS connection between the application system (HR/FI) and the Cloud Integration tenant add the load balancer root certificate to the HR/FI trust store. Find further details in the blog How to setup secure http inbound connection with client certificates.
Set up Authentication (two options)
For the setup of the authentication two options exist, Basic Authentication or Client Certificate-based Authentication. The more secure option is to use Client Certificates.
Create an user in Cloud Integration and assign ESBMessaging.send role. More information can be found in the documentation chapter Defining Permissions for senders to Process Messages on the Runtime Node.
Client certificate-based authentication
Neo Environment: Set up client certificate in HR/FI system and upload it in certificate-to-user mapping in Cloud Integration as described in the blog How to setup secure http inbound connection with client certificates.
Cloud Foundry Environment: Set up client certificate in HR/FI system and upload it in the service key as described in the blog CF -How to setup secure http inbound connection with client certificates.
Setup SM59 Destination
- Create a SM59 Destination in the HR/FI application system.
- Enter the end point retrieved for the integration flow from the Cloud Integration monitoring (see above)
- Maintain logon details for the HTTPS connection (basis authentication or client certificate-based)
Upload Elster Certificates
Upload the ELSTER certificates (PFX file) to the key store monitor of the Cloud Integration tenant.
Execute HR/FI Customizing
You can find detailed instructions for setting up the scenario in the Implementation Guide in the content provided.
Operation of the Elster Scenario
Update of ERiC Libraries
The Elster adapter is automatically updated with the latest libraries in Cloud Integration. No manual steps are necessary.
Message Processing Log (MPL)
The processing of data in the cloud integration tenant can be monitored in the Message Processing Monitor. Each message processing generates an MPL (Message Processing Log), which can be found in the monitoring under Monitor Message Processing.
In the case of an error, the message has the status Failed and you can find further error information in the status area of the message on the right-hand side. All ERiC related error messages are issued here, for example if the message validation or the encryption was not successful.
In the case of an error, further information can be found in the default trace of the Cloud Integration tenant. The default trace can be found in the monitoring of the cloud integration tenant in the area Access Logs -> System Log Files. The logs are in the most up-to-date files with the name ljs_trace_<ID>_<Timestamp>.log.
- Note that the information above only applies to tax types UStA, LStA, LStB, and ELStAM, and not to the use of ERiC in connection with the E-Bilanz.
- The ELSTER ERiC Cloud Integration scenario only supports tax types employment tax notification (LStA), employment tax statement (LStB), electronic employment tax deduction features (ELStAM)), and FI (advance return for tax on sales/purchases (UStA)). The HR tax types are covered by the Integration Content SAP HR ELSTER ERIC for Germany. The Integration Content for FI is under development, it is expected to be available mid of July 2019 under the name ‘SAP Finance Applications Integration with ELSTER’.