Technical Articles
eDocument Electronic Invoicing for Italy: building custom router for using TEST and PROD in parallel having one tenant only
Introduction
You’re implementing the “eDocument: Electronic Invoicing for Italy” solution having only one SCPI (HCI) tenant. You have read how to create a TEST copy of the eDocument package but it doesn’t suit your scenario since you registered at SdI indicating the same endpoint for test end production.
In this case, you can’t use the same iFlows for sending and receiving messages from and to SdI: once you’ve switched the parameter Mode to PROD in your iFlows, you stop sending messages to SdI test. When you receive notifications and invoices from SdI, they’re all stored into datastore distinguished by Fiscal Code, regardless of what SdI is calling.
This blog aims at showing how to easily build a custom middleware to put between the standard SCPI eDocument solution and the respective caller (either SAP backend or SdI).
Prerequisites
- eDocument for Italy solution implemented in accordance with SAP note 2583309.
- Latest version of eDocument for Italy deployed (we use the 1.0.3).
- Active Experimental SdI system.
Solution – Overview
If you registered the same endpoint at SdI for test and production, how do you know whether it is SdI TEST or SdI PROD calling your SCPI application? If you run your scenarios both using test and production environment, you might come across a case like this.
The main problem to overcome is allowing SCPI to understand who is calling. For that we need something doing the trick.
The idea laying behind this solution is having:
- The original eDcoument Italy package with endpoints distinguished by ‘PROD’ suffix (i.e. /PROD/ItalyReceiveInvoice)
- A copied eDocument Italy package with endpoints distinguished by ‘TEST’ suffix (i.e. /TEST/ItalyReceiveInvoice)
- A custom built artifact gathering all the endpoints registered at SdI and called by SAP, no matter who’s the caller, it’ll be able to understand the caller and redirect the messages accordingly
Solution – Details
Step 1 – add suffix “/PROD”
Add suffix “/PROD” to all the eDocument: Electronic Invoicing for Italy addresses (even to the process direct connections).
Example of Italy Receive Invoice reconfigured.
Deploy it.
Step 2 – create a TEST copy package and add suffix “TEST”
Copy the eDocument: Electronic Invoicing for Italy solution from Discovery in your SCPI, add the “TEST” suffix, then add suffix “/TEST” to all the addresses in there.
Example of Italy Receive Invoice (TEST) reconfigured.
Deploy it.
Step 3 – create your eDocument: ROUTER package
This package will hold:
- A Value Mapping containing all the previously configured endpoints
- The Integration Flow solution
- Italy Endpoints – Value Mapping
Each eDocument iFlow (TEST and PROD) is reachable at an address: the addresses are collected in the below Value Mapping list. The list is accessed based on the respective iFlow name distinguished by the string “TEST” or “PROD”. Altogether we have 14 endpoints (7 for TEST and 7 for PROD).
The Value Mapping gets accessed via a groovy script shown in the next step.
Please notice I’m using the default endpoints, not those custom domain based. You can choose what to use.
- Italy Router – Integration Flow
The router performs the following steps:
- Setting the Message Type based on what address is called (i.e. ReceiveInvoice)
- Understanding the calling environment (TEST or PROD)
- For SdI it’s based on the username created in accordance with chapter 12 of SAP note 2583309 (i.e. sdi_user_test -> TEST)
- For SAP it’s based on the calling sy-name/system ID taken from the payload (alternatively you can use the username created in the certificate-to-user mapping if you applied this solution)
- Retrieving the correct endpoint (i.e. SendInvoiceTEST -> https://mytenant/cxf/TEST/ItalySendInvoice)
- Calling the SCPI SOAP WS which will call the receiver system (i.e. https://mytenant/cxf/TEST/ItalySendInvoice will send the invoice to SdI TEST)
The Router iFlow gathers all the addresses called both by SdI and by SAP.
The addresses are configurable.
The 4 additional parameters are:
- SAPCaller_TEST and SAPCaller_PROD: the calling SAP backend system names (3 characters)
- SdIUserPROD and SdIUserTEST: the user created in accordance with chapter 12 of SAP note 2583309
Add SapAuthenticatedUserName among the allowed headers.
Example of Receive Invoice (ROUTER). SdI calls SCPI.
Handle SdI Message works as follows.
Groovy script to access Value Mapping.
import com.sap.gateway.ip.core.customdev.util.Message;
import java.util.HashMap;
import com.sap.it.api.ITApiFactory
import com.sap.it.api.mapping.ValueMappingApi
def Message processData(Message message) {
def properties = message.getProperties();
def CallerAgency = properties.get("CallerAgency");
def valueMapApi = ITApiFactory.getApi(ValueMappingApi.class, null);
def endpoint = valueMapApi.getMappedValue('EdocItalyCallerAgency', 'EdocItalyCallerSchema', CallerAgency, 'EdocItalyEndpointAgency', 'EdocItalyEndpointSchema');
message.setProperty("Endpoint", endpoint);
return message;
}
To connect to SCPI itself, you could use either the user credentials (create one under Security Material) or a client certificate.
When is SAP that calls SCPI, the only difference is how SCPI recognizes the caller. Build a groovy script accordingly (for example you can get it from the payload, otherwise from the SOAP Header, you choose the option that suits your scenario).
The rest works exactly the same.
Testing the solution
Let’s send and invoice from SAP TEST and another one from SAP PROD to SCPI. We expect to receive the two notifications into different datastores and retrieve them in the correct system.
Sending from SAP TST
Send Invoice log details and Receive Notification log details
Datastore
Sending from SAP PRD
Send Invoice log details and Receive Notification log details
Datastore
Retrieve Notification from SAP TST
Datastore after retrieving: TEST removed
Retrieve Notification from SAP PRD
Datastore after retrieving: PROD removed
Pros and cons
Here some considerations on this solution.
PROs |
CONs |
Single tenant for keeping using TEST and PROD environments in parallel | Difficulty in monitoring: each message gets doubled in the message monitor |
Standard eDocument solution left unchanged | Increased latency due to SCPI calling itself via SOAP calls instead of using Process Direct calls |
Highly paramiterizable | |
Potentially scalable |
Statistics
Here some figures in respect to almost a thousand messages (no matter if it was a SendInvoice or a ReceiveNotification) passed through the custom router artifact (only the router, NOT router+<eDocIFlow>).
Time | Time for completing a message (ms) |
Average | 394 |
Median | 116 |
Max | 15.460 |
Min | 40 |
Thanks for reading.