Skip to Content

In some cases, SAP PI standard mapping functions that are provided as a part of graphical mapping functions library doesn’t fulfill requirements for complex message transformations and need to be complemented with custom development and employment of user-defined functions / function libraries or custom mapping programs written in Java, ABAP or (ABAP-/Java-)XSLT transformations. In latter cases, 3rd party tools are sometimes used to simplify and speed up such development tasks as well as to utilize graphical user interface for construction of transformation rules. One (but surely not the only one) of such tools that is commonly used for these tasks is the product MapForce which is developed by Altova ( ). Questions and discussions about its usage show up from time to time in SCN – in overwhelming majority of cases, attention is drawn to development of XSLT transformations and further employment of generated XSLT transformation programs in PI scenarios (as an example, please see the guide “Step-By-Step Guide on File to File Using Xslt Mapping” written by  Dipankar Sinha Sarkar).


In this blog, I would like to discuss briefly another functionality that can be used practically – namely, usage of graphically prepared and automatically generated Java transformations exported from MapForce and used in PI as Java mapping programs.

Please note that description of standard steps which are required for Java mapping program creation are out of scope of this blog – there are quite many various materials on SCN that cover Java mapping program development steps in details. This blog will only focus on specific steps that have to be undertaken on the example of the case MapForce is used for PI Java mappings development.


Let’s firstly get a brief outlook on sequence of steps that are required in order to complete this development task using MapForce:

  1. Export source and target message types in a form of XSD files from ESR [PI ESR];
  2. Create a MapForce mapping project [MapForce];
  3. Import the generated XSD files containing message types’ definitions to the project [MapForce];
  4. Create transformation rules using functions from standard libraries and/or user-defined functions / function libraries [MapForce];
  5. Generate transformation source code in Java language [MapForce];
  6. Import the generated project into Java IDE that is used for PI Java development (e.g. SAP NetWeaver Developer Studio that will be used in this example) [NWDS];
  7. Supplement the obtained Java project with necessary PI Java mapping specific objects (add referenced PI Java mapping libraries and adjust build path, create a Java class extending abstract class AbstractTransformation, etc.) [NWDS];
  8. Implement the method transform() of the created PI Java mapping program class that will hold mapping logic – precisely, implement a wrapper logic followed by a call of the method run() of the transformation class generated by MapForce [NWDS];
  9. Export the developed mapping program in a form of JAR file [NWDS];
  10. Import the generated JAR file containing the developed mapping program into ESR as an Imported Archive [PI ESR];
  11. Use imported mapping program in operation mapping as mapping of type Java Class [PI ESR].


Now, let’s concentrate on some specific non-generic steps and get more precise look on them in more details.


For this example, very simple transformation logic was implemented in the mapping in order not to distract attention from the discussed topic (for detailed description of MapForce transformation libraries and available functions, please refer to Altova MapForce help documentation). The source message has two elements – ShortText1 and ShortText2 – that should be transformed into a single element of the taget message – LongText – applying following transformation logic: the substring of the original value of each of source elements that is located to the right of the colon is retrieved, obtained substrings are separated by semi-colon and space (; ) from each other, brought to upper case and finally surrounded by curly braces ({ }).


For example, for the sample source message:

<?xml version=”1.0″ encoding=”UTF-8″?>

<ns0:mt_ShortText xmlns:ns0=”http://sap/ags/pi/vadim/misc“>

   <ShortText1>value:sample text 1</ShortText1>

   <ShortText2>value:sample text 2</ShortText2>


… the following target message should be constructed:


<?xml version=”1.0″ encoding=”UTF-8″?>

<ns0:mt_LongText xmlns:ns0=”http://sap/ags/pi/vadim/misc“>

   <LongText>{SAMPLE TEXT 1; SAMPLE TEXT 2}</LongText>




The created MapForce mapping project and mapping graphical layout are depicted on following screenshots:


  • Mapping overview:


  • Components overview (input – for source message type, output – for target message type):



  • Mapping project settings:

mapping project.png

Meaningful advantage of MapForce is a built-in execution engine that can be used to immediately check output of constructed transformation execution right in MapForce:


After transformation is prepared (and optionally tested) in MapForce, we generate the Java source code for it:


As a result, MapForce generates the separate project folder with Java source code of the developed transformation containing MapForce types and operations libraries as well as transformation specific classes that are actually implementing designed transformation logic. MapForce types and operations libraries are located in the package com.altova.* and transformation classes are located in user-defined package (specified in mapping project settings, by default com.mapforce). Transformation classes names are beginning with the application name (specified in mapping project settings, in this example – SampleMapping).


The next step is to import the generated project in NWDS that is done using usual Eclipse Import wizard (Import Projects). After this is done, we proceed with implementating the Java mapping program in a usual manner – namely, adding referenced PI Java mapping libraries to the Java project, adjusting its build path, creating a Java class that inherits abstract class, implementing method transform() of the created class, but instead of writing source code for parsing the source message, transformation rules and constructing the target message, we now utilize the transformation class generated by MapForce:


As it can be seen from the sample implementation of the Java mapping program, the method run() of the generated transformation class (SampleMappingMapTomt_LongText) is called in order to trigger transformation logic execution. In this example, we used input and output streams (corresponding to source and target messages) that were passed to the method run(). Thus, we also instantiated respective (used for reading InputStream obtained from and (used for writing to OutputStream derived from objects before calling transformation. Generally speaking there are other various wrapper objects (e.g. strings, input readers / output writers, DOM documents and files) that can be passed to this method. Variety of wrapper objects supported by MapForce can be evidenced when exploring contents of the package (expanded on the screenshot above).


Remaining part of development activities is exactly the same as they would be in case of usual Java mapping programs development: build and export the mapping program as a JAR file from NWDS, import the archive in ESR and use it in the operation mapping accordingly:

imported archive.png

operation mapping - design.png

Test results of the developed operation mapping in PI against the same source XML document that was used during MapForce execution engine test are reflected on the screenshot below:

operation mapping - test.png


As a conclusion for this blog, I would like to mention that in addition to MapForce standalone installation that was used when developing demonstrated sample transformation, Altova provides a MapForce plugin for Eclipse (a part of Altova MapForce Integration Kit) that can be used to establish seamless coupling of MapForce and Eclipse based Java development environment for PI and ensure transparent integration of MapForce mapping project in the PI Java mapping project. However the core logic of the mapping program development remains the same as described in this blog.

To report this post you need to login first.


You must be Logged on to comment or reply to a post.

    1. Vadim Klimov Post author

      Hi Trevor. Thank you for your positive feedback. And I’m very glad that the described approach was useful to you and can help avoiding unnecessary complexity.

  1. Sunil Chandra

    Cool stuff! As a PI developer never thought of using Altova MapForce for doing anything else than developing xsl mapping.

    Keep exploring, keep sharing!


    Sunil Chandra


Leave a Reply