Skip to Content
Author's profile photo Vikas Singh

Using SAP Java Idoc Class Library in SAP PI Adapter Modules and allow segment type to be used for Idoc Flatfile to XML conversion


We were investigating replacing one of our custom adapter modules which converts flat files to idoc messages by calling an ABAP function module on PI ABAP stack to do the conversion.

SAP has created an adapter module which performs the conversion of idoc flat file to xml format message.

William Li’s excellent blog describes the steps in detail about “How to Use User-Module for Conversion of IDoc Messages Between Flat and XML Formats”.

However we ran into an issue as out input data doesn’t have segment definitions .

The message keeps failing with the errorIDoc segment metadata could not be found for segment name E1EDK01”.

I couldn’t find any solution documented on SCN which gives the solution for this issue though some people have raised this as comments in the above mentioned blog post.

Problem :

IDOCFlatToXmlConvertor expects segment definition instead of segment types. As we don’t want to use PI ABAP stack to read the idoc metadata, we were not sure how can we do the segment definition to segment type replacement.


Before we were using JCo calls from within the bean to call an ABAP function module. However, we wanted to avoid reading segment metadata from PI ABAP stack primarily because PI ABAP stack will go away in future, though we’re still on dual stack system. After some analysis, we tried using SAP Java Idoc class library.

Where to get the libraries from:

– SAP Java Idoc class library and SAP JCO libraries can be downloaded from  .

Refer this page:

Our plan was to create an adapter module which can do some pre-conversion before standard module IDOCFlatToXmlConvertor  is called .

Before we use SAP Java Idoc class library within the module, let’s try to write a small example which can read idoc metadata. It’s much easier to understand that way and makes the whole process much faster as well  . The program will read idoc metadata and parse through the whole segment tree. .This can be then later used to build a list of segment type and segment definitions so that we can replace the segment types by segment definitions.

Java SE Set Up:

  • Create a Java project and addthe SAP JCO and SAP Java Idoc class library files to the Java project
  • Create a helper Java file with segment type and segment definition.

We need recursion to traverse the whole segment tree as any segment has information only about its immediate children.

public void getMetaData(IDocSegmentMetaData currSeg, List<IDocSegmentMetaData> metaDataList){


  IDocSegmentMetaData[] children = currSeg.getChildren();

  for(IDocSegmentMetaData currChild : children){


In Java SE environment iDocRepositorycan be initiated as follows for testing.

JCoDestination destination=JCoDestinationManager.getDestination(“NSP”);

      IDocRepository iDocRepository = JCoIDoc.getIDocRepository(destination);

      IDocSegmentMetaData rootMetaData = iDocRepository

        .getRootSegmentMetaData(“Z_TEST”, “Z_TEST_EXT”,

            “7.02”, “7.02”);          } }

where Z_TEST : idoc type

Z_TEST_EXT : Extension Type

Our system is at release level 702 . So we can give the release level as 7.02 for SAP release and segment release level.

IDoc Segment Representation

Our idoc in SAP is represented as follows:

2015-11-26 03_48_47-Display extension_ Z_TEST_EXT.png

Idoc library returns the root Segment : it has the definition “ROOT” with the description “General root segment”.

2015-11-26 03_58_48-Untitled drawing - Google Drawings.png

and our program displays the information :






Using the class library, we’re able to retrieve segment type and segment definitions.

Using SAP  Java Idoc class library on PI server.

As the library is present in the runtime environment already, no extra deployment descriptors are needed in the custom adapter module.

Obviously the call to get iDoc Repository instance gets modified on the PI server.

ConnectionFactory connectionFactory = (ConnectionFactory) initialcontext.lookup((new StringBuilder()).append(


              JRAIDocFactory idocFactory = JRAIDoc.getIDocFactory();

              IDocRepository idocRepository = idocFactory.getIDocRepository(connectionFactory);

We need to do a JNDI lookup using the connection factory ( refer to William Li’s blog mentioned above about requirements ). This is then used to get reference to JRAIDocFactory and ultilmately iDocRepository.

Once we get reference to iDocRepository, similar process can be used to retrieve segment metadata and build a list of segment type and segment definition pairs.

So the custom module parameters required are :




Once we have the list, segment type to segment definition translation can be easily carried out.

Internally system calls IDOCTYPE_READ_COMPLETE to read the metadata information and the metadata is cached on the PI server optimising the performance of the custom adapter module . Release appears without decimals . So release 7.02 we gave in Java code when reading root segment metadata on Java stack will be represented as 702 on ABAP stack .

Further, our idoc files don’t have segment hierarchy within them but it’s taken care of by setting RenumberSegments. This information is present in segment metadata in case it’s required.

Hopefully this blog will help people more familiarity with Java Idoc Class library and also help with the specific case of allowing idoc segment types to be used for Flat file to idoc conversion using the SAP provided IDOCFlatToXmlConvertor  bean.

You can refer some sample programs at this github link : viksingh/JavaIdocLibrary · GitHub


SAP has updated bean IDOCFlatToXmlConvertor  and added parameter SegmentTypeProcessing ( Note 2267985  ) . Hence, this blog is not really required as the functionality is present in standard now .

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Eng Swee Yeoh
      Eng Swee Yeoh

      Hi Vikas

      Thanks for sharing this interesting technique!

      Would appreciate it if you can entertain a few of my queries/requests:

      1) Does this call the IDOCTYPE_READ_COMPLETE on the backend ABAP system (not the ABAP stack of the dual stack system)? If yes, does it mean that the relevant NWA configuration as detailed for the usage of the standard IDoc converter modules need to be configured first?

      2) Can you update the blog with which JAR files are required and their location in the PI system? I could figure out a few of them but the file is incomplete and does not have all the import statements.

      3) Can you provide a sample input and output of how the payload would look like before and after the custom module? This would help anyone who is considering this solution to compare their data against the samples to see if this solution would work for their case.

      Thanks. Looking forward to your response.


      Eng Swee

      Author's profile photo Vikas Singh
      Vikas Singh
      Blog Post Author

      Hi Eng Swee,

      1. You're correct in understanding - It calls the function module on the backend ABAP system and not the PI ABAP system .

      2. The jar files ( for SAP JCO and for the Idoc library ) will need to be downloaded from SAP connectors download SAP Service Marketplace - Connectors .

      Thanks for the feedback on this . I've updated the blog with the location.

      3. Yes, I had put only the snippets relevant for PI as my module was more complicated handling some other cases as well . I'll update a working version with a sample file soon.



      Author's profile photo Vikas Singh
      Vikas Singh
      Blog Post Author

      Hi Eng,

      SAP has added a parameter to standard bean now - added SegmentTypeProcessing .

      See note 2267985 .