IDocs have been around for multiple decades in the SAP world, and customers very commonly want to integrate them as they are the backbone of transferring master and transactional data between SAP systems and other applications in any ABAP-based system, be it SAP ECC, BW, SRM, SCM, CRM or SAPs flagship product S/4HANA.
Overview
Inside SAP systems IDocs are processed by the Application Link Enabling (ALE) framework. People familiar with the system often use the terms ALE and IDoc together or mention them in the same sentence. For people unfamiliar with SAP, it is essential to understand that ALE works just like a messaging system. As the sender of the message (IDoc), you specify what type of message is sent, who should receive it, and what ALE Port you want to use. On the SAP side, the ALE framework decides when the message is processed and what functionality is used to do that by configuration.
With this basic understanding of ALE, let us briefly go over the individual Snaps we have and how they are used before we dive into the details of each one. Let's start with the SAP IDoc Write Snap. While it is pretty self-explanatory what it does, it is used to create an IDoc in the SAP system; our documentation is a bit misleading as it suggests that IDocs are always processed asynchronously and, therefore, a SnapLogic pipeline will never wait for the processing in SAP to finish before proceeding. Later in this series, we will see that both scenarios are possible: asynchronous and synchronous processing.
At first, IDoc Listener and IDoc Document Listener sounded confusing to me. Why would one want two separate Snaps to listen to IDocs sent to a pipeline by an SAP system? The answer is simple: once the IDoc is received, the IDoc Listener outputs the IDoc as XML in a binary format while the IDoc Document Listener can directly transform the IDoc into a SnapLogic Document with the added feature of specifying an IDoc Basic Type, a specific version of a given IDoc Message, that is read during validation and then used to pass the structure of the message to downstream Snaps.
Lastly, the IDoc Read Snap allows you to read an already-created IDoc. While this Snap returns the complete IDoc with all its data, the most common use case for this Snap is to determine the processing status of the IDoc in the SAP system. We will have a brief look at IDoc statuses later in the series. The ALE framework and the application processing the IDoc in SAP set statuses that can be used to gain insights into what happened on the SAP side.
In the next part of the series we are going to look at the prerequisites for the IDoc Snaps (link to next part)
What you must do before using the Snaps successfully
Let's now examine the prerequisites for using the SAP IDoc Snaps. While the prerequisites are not complicated to implement they are essential if you want to use the Snaps.
Prerequisites for IDoc Write, IDoc Read Snaps
Because an SAP system does not have standard functionality to read an existing IDoc from the outside, the IDoc Read and IDoc Write Snaps require you to create a custom RFC-enabled Function Module in the SAP system before they can be used. You can do this using SAP transaction SE37.
The interface of the RFC must be identical to the `IDOC_READ_COMPLETELY` function module available inside the SAP system. We suggest wrapping the original function module instead of copying it, and we have attached an example to this blog. If you are not familiar with creating an RFC-enabled Function Module yourself, we suggest you contact the team that operates SAP in your organization and ask them to do it for you. Creating the function module is simple and merely takes a few minutes, especially if you are able to hand them the attached example.
Prerequisites for IDoc Listener and IDoc Document Listener Snaps
Service Names
The Listening Snaps require you to add entries to the /etc/services file on Linux or the %windir%\System32\drivers\etc\services file on Windows on each node of the Groundplexes you intend to use with the IDoc Snaps. The file maps TCP/IP ports to service names for many standard services and will, by default, contain entries for many of the standard ports for many standard services like Email, SSH, and others. You will need to add service names for the SAP system depending on the System Number(s) of your SAP system(s). The SAP System number consists of two digits and is generally used to map to the various ports SAP listens on. If the System Number is 00, the SAP Gateway port is 3300. If it is 01, the port will be 3301, and so forth. If you intend to use Secure Network Communication (SNC) you must also make an entry for the SNC port which is 48xx. The naming rule is sapgwXX for the standard port and sapgwXXs for the SNC port.
sapgw00 3300/tcp # Standard port of SAP Gateway for System No 00
sapgw00s 4800/tcp # SNC port of SAP Gateway for System No 00
Alternatively you can also reach out to the team operating the SAP systems in your company and ask for the entries. They are able to provide them to you as they are configured in every system running SAP as well as every Windows based desktop that has an SAP Gui installed.
SAP RFC Gateway Access Control Lists
For your IDoc Listen Snaps to register successfully at the SAP RFC Gateway the gateway has to allow access for the nodes of the Groundplex you intend to use. In order to do this, you need to make sure that the SAP RFC Gateway has entries in the reginfo and secinfo files of the Gateway. The files can be configured via SAP Gui Transaction SMGW and the various options are explained in a great multi series blog on SAP SCN that discusses SAP RFC Gateway Security. We suggest you check with the team that operates your SAP systems what ACL settings are in place or ask them to include the IP addresses of the nodes of the Groundplex(s) you intend to use.
Creating IDocs in SAP using the IDoc Write Snap
In a typical SAP system, many standard IDOCs are available by default. Some companies use the default ones like ORDERS05 for Sales Orders or MATMAS05 for the Material Master, but others either extend the ones supplied by SAP or create their own ones. These IDocs are typically large and contain a lot of fields grouped into segments, and it is easy to get overwhelmed by them. To focus on the integration aspects of the blog series, we created a straightforward custom IDoc with only ten fields grouped into one segment to discuss the functionality. The IDoc we created looks as follows:
<?xml version='1.0' encoding='UTF-8'?>
<ZPERSON01>
<IDOC BEGIN="1">
<EDI_DC40 SEGMENT="1">
<TABNAM>EDI_DC40</TABNAM>
<MANDT>100</MANDT>
<DOCNUM>0000000000058011</DOCNUM>
<DOCREL>758</DOCREL>
<STATUS>30</STATUS>
<DIRECT>1</DIRECT>
<OUTMOD>2</OUTMOD>
<IDOCTYP>ZPERSON01</IDOCTYP>
<MESTYP>ZPERSONDATA</MESTYP>
<SNDPOR>SAPS4H</SNDPOR>
<SNDPRT>LS</SNDPRT>
<SNDPRN>S4HCLNT100</SNDPRN>
<RCVPOR>A000000003</RCVPOR>
<RCVPRT>LS</RCVPRT>
<RCVPRN>SNPCLNT000</RCVPRN>
<CREDAT>20240508</CREDAT>
<CRETIM>225707</CRETIM>
<SERIAL>20240508225707</SERIAL>
</EDI_DC40>
<ZPERSONDATA01 SEGMENT="1">
<FIRSTNAME>Herbert</FIRSTNAME>
<LASTNAME>Walker</LASTNAME>
<TITLE>Mr.</TITLE>
<GENDER>male</GENDER>
<STREET>1234 Somestreet</STREET>
<CITY>Boston</CITY>
<ZIP>72662</ZIP>
<COUNTRY>United States</COUNTRY>
<EMAIL>herbert.walker@myemail.com</EMAIL>
<PHONE>555555525</PHONE>
</ZPERSONDATA01>
</IDOC>
</ZPERSON01>
In the IDoc, the EDI_CD40 segment represents the control structure that contains the various information needed by the SAP system to understand what data the IDoc contains and what application it is intended for, while ZPERSONDATA01 is the segment with the fields that contain the data of the IDoc.
When creating an IDoc in SAP, you do not need to send the entire EDI_CD40 segment with all the fields; you only need the fields required for the ALE layer to understand where the IDoc is supposed to go. In the example below, we have limited the structure only to contain the fields required by the configuration we made in SAP. The SAP team in your organization is responsible for configuring ALE and can give you the details of what needs to be filled into the fields for the IDoc you intend to send.
The pipeline we have built consists of 3 Snaps, a JSON generator Snap that contains the sample data below:
{
"EDI_DC40": {
"MESTYP" : "ZPERSONDATA",
"SNDPRT" : "LS",
"SNDPRN" : "SNPCLNT000",
"SNDPOR" : "A000000003",
"RCVPRT" : "LS",
"RCVPRN" : "A4HCLNT001"
},
"ZPERSONDATA01": [
{
"FIRSTNAME": "Ingo",
"LASTNAME": "Sauerzapf",
"TITLE": "Mr.",
"GENDER": "female",
"STREET": "33rd Str.",
"CITY": "New York",
"ZIP": "98632",
"COUNTRY": "United States",
"EMAIL": "ingo.s@somecompany.com",
"PHONE": "5405883833",
"SLEEPTIME": 40
}
]
}
A Mapper Snap that maps the Control Segment as well as the data Segment. While the names of the fields in the data segment are identical between the output of the JSON Generator and the IDOC field names, we deliberately used the SAP internal names for the Control-Record of the JSON Generator; the IDoc Write Snap will show these fields with the names the setter methods have in the underlying SAP IDoc java class library. We have attached a mapping table to this blog that will help you map the setter names of the Java methods to the SAP internal names, but you can find the mapping in the JavaDocs of the SAP IDoc library.
The completed pipeline looks as follows:
The output of the SAP IDoc Write Snap will give you a large set of information back to understand what happened in the SAP system. Most importantly the DOCUMENT_NUMBER but also the STATUS the IDoc has in SAP after the Snap executed successfully.
Once successfully executed you can see the processing of the IDoc in transaction WE02 or WE09 in the SAP.
We've attached the sample pipeline. In the next part of the blog we will have a look at the various settings you can make in the IDoc Write Snap to manipulate the behavior of the Snap and we take a look at synchronous and asynchronous execution.
