When working with SAP from an integration perspective, it can sometimes come in handy to use IDOCs. These type of documents are relatively easy to generate, contain a lot of information, and even better: it’s standard SAP functionality!
Do you also know it’s very easy to send them from SAP directly into Azure Logic Apps? No? Well, now you do!
Even though it’s all standard functionality in SAP as well as Azure, it does require some steps to be executed for it to work. For your convenience, I’ve written this blog post as guidance, to help you configure your environment.
Prerequisites
Before you start I’m considering the following in place:
- An SAP system to connect with
- Authorization in SAP to register SM59 destinations and configure IDOCs
- The On-Premises Data Gateway is installed, with
- The correct SAP Connector for Microsoft .Net
- An open network connection to the SAP system from the server running the On-Premises Data Gateway
- You’ve got administrator access to the server running the On-Premises Data Gateway
- There is an active Subscription in Azure where the On-Premises Data Gateway is registered
- You’re at least Contributor of the Subscription
- You know your way around Azure and SAP (specifically how to configure IDOCs)
- Preferably there are already Azure Logic Apps in place communicating with SAP
Configure On-Premises Data Gateway
As stated in the prerequisites we presume there is already a registered On-Premises Data Gateway. However, it does need some additional configuration before it can be used to forward IDOCs from SAP to Azure. SAP uses named services to communicate with the outside world, and therefor your On-Premises Data Gateway needs some changes!
Get your copy
In the steps below we are going to update the services file on the server running the On-Premises Data Gateway. For this I’ve already prepared the entries, which can be downloaded here (don’t worry, it’s just a text file).
- Log on to the server running the On-Premises Data Gateway
- On that server, click the Start button and start typing “notepad”
- You will now see Notepad appear, right click it
- Select ‘Run as administrator’ to open Notepad with elevated privileges (accept with ‘Yes’ if confirmation is required)
- In the appearing Notepad screen, click ‘File’
- Next, choose ‘Open’
- The Browse screen is shown, type “C:\windows\system32\drivers\etc\services”
- Click ‘Open’ to open the Services file
- With the Services file open, scroll down to the last record
- Set the cursor behind the last record and press Enter
- Copy the contents of the text file in your Services file to make it look like below:
- Click ‘File’ again and select ‘Save’ this time
- You may now close Notepad
- Reboot the server running the On-Premises Data Gateway
Changes in the services file don’t become active immediately on the On-Premises Data Gateway. Therefor it is necessary to reboot the entire server. Even though the documentation states restarting the On-Premises Data Gateway itself should be enough, I’m rather safe than sorry.
Create SM59 destination in SAP
SAP uses destinations registered in transaction ‘SM59’ to deliver messages to, one of which will be the IDOCs that we’re setting up right now. The following steps take you to the process on configuring the destination for our purpose:
- Start up your SAP GUI and log on
- Enter “SM59” in the transaction input and hit Enter
- You’re now in the RFC Connections screen where you can click the New button
- In the ‘RFC Destination’ screen you can set a name in the ‘RFC Destination’ field, for example “AZURE”
- Enter “T” in the small field next to ‘Connection Type’ to set a TCP connection type
- Now press the Save button to create the new connection
Don’t leave the screen just yet, as you’re now able to store additional information in the Technical Settings tab:
- Under ‘Activation Type’, select ‘Registered Server Program’
- Enter the name you want to use for Azure to register itself on SAP in the ‘Program ID’ field (easiest would be to keep the same name as the RFC Destination itself)
- Note the name of your server program as we’ll need it later on (it’s case sensitive)
- Scroll down when you’re ready
- Enter the hostname of your SAP server in the ‘Gateway Host’ field and temporarily store it for later reference
- Enter the gateway service for your SAP server ‘Gateway Service’ field and store it as well
Info on the Gateway Service
By default SAP is communicating over port 3300 for system number 00, port 3301 for system number 01, and so on. The Gateway Service resembling these ports as named service is respectively ‘sapgw00’, ‘sapgw01’, etc. So if your SAP system number is 00 the system most probably communicates RFCs over port 3300 and you can should use ‘sapgw00’ as Gateway Service.
- Now go to the ‘Unicode’ tab
- Check the box next to ‘Unicode’ under ‘Communication Type with Target System’
- Now press Save once again to store your configuration
For now, this is it in SAP. But don’t close the screen just yet as we’re gonna need it in a moment! After we’ve configured Azure it is a good idea to perform a connection test here.
Add SAP trigger to Logic App
Now we’ve got our connections configured it is time to set up Azure to start receiving IDOCs:
- Go to the Azure Portal
- Create a new Logic App and open it after deployment
- Select ‘Blank Logic App’ when opening the Designer for the first time
- You’ll now see the search field, enter “sap” here
- Select ‘SAP’ when you see it appear
- As of this writing there is only one SAP trigger available, being ‘When a message is received’, click it to add the trigger to your Logic App
- If you haven’t done so already, enter the login information upon ask to connect to the SAP server, or select the correct connection file when necessary (if the one that’s auto-selected isn’t the right one)
- Enter the information we’ve temporarily stored in the previous steps, being:
- Gateway Host in the ‘GatewayHost’ field
- Gateway Service in the ‘GatewayService’ field
- Program ID in the ‘ProgramId’ field
- Click Save to activate your changes
That’s it! As soon as your settings are saved the Logic App is registering itself directly on the SAP server through the On-Premises Data Gateway. When all steps are performed correctly, we should now have a working connection!
Test Connection
Everything is set up. Now let’s check if everything’s correct by performing a connection test. You should still have SAP open on the ‘SM59’ transaction. If not, please open it again with your newly created SM59 destination.
Simply click the ‘Connection Test’ button on the top of the screen.
When the connection test succeeds you should see a screen like the one below:
Since our test is successful, we can now continue sending actual IDOCs. As soon as SAP is configured to send out IDOCs to our newly created SM59 destination it will be automatically forwarded to Azure on creation, straight to your Logic App.
IDOC configuration
Because IDOC delivery configuration isn’t a “one-off” in SAP I haven’t included any specific configuration details on this topic. I assume you or one of your colleagues now how to deliver IDOCs to the SM59 destination, fit for your scenario.
When the IDOC arrives in Azure you can view its contents directly from within the trigger of the Logic App in the runs history:
Considerations
While writing this guide and providing examples, I noted some considerations you might want to take into account:
- Depending on your processing logic and the (micro)services used, you may want to – temporarily – store the IDOC contents somewhere else (like for example Azure Storage), while passing through the IDOC number only, as IDOCs can be large at times
- An IDOC contains an XML structure, which can be easily converted into JSON, but keep in mind that parts of the XML that are actually arrays can be seen as object if there’s only one record available at conversion time
Next Steps
IDOC delivery to your Logic App is only the first step in the process. From that point forward it’s off course important you go on actually processing it. It really depends on your scenario what that processing looks like. Drop me a note if you want to discuss your options. I’m happy to help!
Please feel free to discuss with me on this topics through the comments below. Off course, you can also get in touch and leave me a message. Looking forward to IT!
Known Errors
As soon as any errors occur that have a known solution, I will add them in the following paragraphs for your reference.
Connection Error
When you click the ‘Connection Test’ button in SAP, it could happen that the connection does not work and the error below is thrown:
Possible reasons for this error could be:
- Your registered program is not allowed to register itself through the On-Premises Data Gateway as an Access Control List (ACL) is active on the ‘SMGW’ transaction in SAP, where you should explicitly allow it
- The port your SAP server is listens to RFC connections, for example 3300, isn’t reachable from the On-Premises Data Gateway server, so your firewall needs additional configuration
- You’ve entered ‘sapgw00’ as Gateway Service, but your SAP is configured to listen on another port and therefor needs another Gateway Service (for example SAP listens on port 3301 which needs Gateway Service ‘sapgw01’)
- The hostname you’ve entered in your configuration isn’t exactly the same as your SAP server (for example: it includes the domain name where the SAP configuration doesn’t, or vice versa)
- Your SAP server is configured with a custom port and Gateway Service configuration so the Services file needs to be adjusted accordingly to make the named services match your SAP server configuration
Troubleshoot Connection
It is possible to troubleshoot your connection using the On-Premises Data Gateway logs. Here you’ll find the exact message SAP is throwing, pointing you in the right direction. If there’s no SAP error messages in the logs, than you’re probably hitting a connection issue to the SAP server.
