SAP PI 7.11 Java Mapping Step By Step Monday, February 04, 2013 7:14 PM
It is short description which let you figure out the bunch of the necessary steps that can be done to create your fist Java Mapping scenario from scratch. Even you can easily to repeat it if you have necessary environment and know how to create your ftp server. The aim of that manual to show you how it could be easily to start use JAVA Mapping instead of Message mapping and why it could be profit. The example includes all steps which we have to be done from task mome nt to ready to use product. Prerequisites:
- You are familiar with JAVA API. - You are skilled in creation of SAP PI scenario by Message Type. - Your SAP PI has version 7.0 or 7.1. (even you have 7.3 it could be useful as well if you didn't try to use Java Mapping before this moment). Our scenario will provide the next order of the xml file transformation:
XML File -> Business system (BS_XML_SND) -> Sender (CC_XML_SND) -> Sender Service Interface (SI_XML_SND) -> Operation mapping based on JAVA Mapping Mapping (OM_XML_JM_X (OM_XML_JM_XML) ML) -> Receiver Service Interface (SI_XML_RCV) -> Receiver (CC_XML_RCV) -> Business System (BS_XML_RCV) -> XML File The main steps which you have to do to achieve the our goal:
1) 2) 3) 4) 5) 6) 7) 8)
Create mapping project and export in JAR file. Prepare the Enterprise Service Part of your scenario. Import JAR file into Imported Archives (IA) of mapping objects. Test our imported JAR file in the IA obje ct. End creating of the Enterprise Service Part of o ur scenario based on Java mapping. Test our operation mapping based on Java mapping. Create the Integration Part of our scenario. Test our scenario by real XML file.
Step by step activity to execute main steps:
1) Creating mapping project and export in JAR file. a. Get jar file of mapping library from your PI server. To be able to use the library which consists the necessary components I did searc h in the folder "D:\usr\sap\PI3\DVEBMGS00\j2ee\cluster\apps\sap.com D:\usr\sap\PI3\DVEBMGS00\j2ee\cluster\apps\sap.com"" (yours folder will be close to this one but of course with different name of system) which is placed on server. Pattern which I entered into search box was like this one: '*mapping*.jar'. I found library that could be useful and it was: library com.sap.xpi.ib.mapping.lib com.sap.xpi.ib.mapping.lib.jar .jar
I opened the containing folder. The path of that folder was the next (yours will be another): D:\usr\sap\PI3\DVEBMGS00\j2ee\cluster\apps\sap.com\com.sap.xi.repository\servlet_jsp \rep\root\start\lib I copied library from that server's folder to folder on my wo rkstation to be able to use it in my work space locally. b. Create your java project, open properties and add two libraries there: external jar (com.sap.xpi.mapping.lib.jar) from the jar file which we saved from PI server on previous step. the java runtime library for compilation process of your project. It must be with the same version that your SAP PI 7.1 has used. In my case the server had 1.5.0_22 version ( [jre1.5.0 _22] ).
c. Check that your project has t he properly configured Java compiler . You need to check this one, because wrong configuration of the compiler compliance level can be root of problem during attempt to test the operation mapping which uses your jar module. The message "LinkageError
at Java Mapping.load()" Mapping.load() " can be encountered if the compliance level of your project will be higher than server's. Open Properties of your project and check settings on "Java Compiler" page as follows:
d. Create the class domMapping (of course you can use another name but for study process I recommend this one) under vendor epam.com for example. The structure of your project with that class could be the next:
e. Create your first code of the mapping java class . We named it as "domMapping". That class will do StreamTransformation of your Input Stream to Output Stream into method execute. That is deprecated code but it is still actual to let yo u understand the methodology of java mapping. (if you have to be more familiar with it you can visit url: http://help.sap.com/saphelp_nwpi711/helpdata/en/e2/e13fcd80fe47768df001a558ed10b6/fram eset.htm):
package epam.com; import java.io.IOException; import java.io.InputStream; import java.io.OutputStream; import java.util.Map; import javax.xml.parsers.DocumentBuilder; import javax.xml.parsers.DocumentBuilderFactory; import javax.xml.parsers.ParserConfigurationException; import javax.xml.transform.Result;
import javax.xml.transform.Source; import javax.xml.transform.Transformer; import javax.xml.transform.TransformerConfigurationException; import javax.xml.transform.TransformerException; import javax.xml.transform.TransformerFactory; import javax.xml.transform.dom.DOMSource; import javax.xml.transform.stream.StreamResult; import org.w3c.dom.Document; import org.xml.sax.SAXException; import com.sap.aii.mapping.api.MappingTrace; import com.sap.aii.mapping.api.StreamTransformation; import com.sap.aii.mapping.api.StreamTransformationConstants; import com.sap.aii.mapping.api.StreamTransformationException; /** * Copy XML with a DOM. */ public class domMapping implements StreamTransformation { private MappingTrace trace; /** * Constructor for DomCopy. */ public domMapping() { super(); } /** * @see com.sap.aii.mapping.api.StreamTransformation#setParameter(Map) */ public void setParameter(Map param) { trace = (MappingTrace) param.get(StreamTransformationConstants.MAPPING_TRACE); } /** * @see com.sap.aii.mapping.api.StreamTransformation#execute(InputStream, *
OutputStream)
*/ public void execute(InputStream in, OutputStream out) throws StreamTransformationException { try { // read XML DocumentBuilderFactory documentBuilderFactory = DocumentBuilderFactory.newInstance(); DocumentBuilder documentBuilder = documentBuilderFactory.newDocumentBuilder(); Document xml = documentBuilder.parse(in); // write XML TransformerFactory transformerFactory = TransformerFactory.newInstance(); Transformer transformer = transformerFactory.newTransformer(); Result result = new StreamResult(out); Source domSource = new DOMSource(xml); transformer.transform(domSource, result); } catch (ParserConfigurationException e) { trace.addWarning(e.getMessage()); throw new StreamTransformationException("Can not create Docume ntBuilder.", e); } catch (SAXException e) { trace.addWarning(e.getMessage()); throw new StreamTransformationException("Can not read XML.", e); } catch (IOException e) { trace.addWarning(e.getMessage()); throw new StreamTransformationException("Can not read XML.", e); } catch (TransformerConfigurationException e) { trace.addWarning(e.getMessage()); throw new StreamTransformationException("Can not create Transformer.", e); } catch (TransformerException e) { trace.addWarning(e.getMessage()); throw new StreamTransformationException("Can not write XML.", e); } } }
Note: this code just only transforms the input message to output without any modification to simplify example and make it repeatable in short time. This is good template and you can expand it by your own code according to methods from this mapping library which is described here: https://help.sap.com/javadocs/pi/SP3/xpi/com/sap/aii/mapping/api/package-summary.html e. Export this project into JAR file to be able use it for importing in future steps. Do the next:
Select context menu of your project and choose the "Export". On the "Export" form open Java node and select "JAR file" and press "Next" as follows:
On this step you have to define the placement where you wish to save your JAR file and as soon as you done it, you can press "Finish" as follows:
2) Prepare the Enterprise Service Part of your scenario. Implement your software component and create there namespace of scenario which you would like to make. In my case I gave the name of the namespace like "http://lukcad.com/xml_JM-xml". Such name has been done to describe the aim of that scenario (XML -> via Java Mapping -> XML).
3) Import JAR file into Imported Archives (IA) of mapping objects. a. Select your namespace and open context menu where you can do t he new adding of Imported Archives as follows:
b. Once you added the object "IA_EcllipsMap", you can upload your JAR file (which has been prepared on the first step this manual) as follows:
4) Test our imported JAR file in the IA object. a. Select the main class of our java mapping which you can find after importing into the list of our "IA_EclipsMap" object as follows:
b. Press pictogram "Display Program"
c. If your JAR file is suitable you will get some list of met hods from your class, but if it is not suitable then you will get message that code with er ror. In my case I got the list of properties, so I found that my class is suitable for server. The programs which I got has been shown by pop-up form as follows:
5) End creating of the Enterprise Service Part of our scenario based on Java mapping. Add all necessary elements of your message mapping, I mean you have to add:
Order of creation that objects as follows:
data type "DT_XML_TYPE". We add only one, because to simplify our example we use the same data type for input and output messages. Our type will provide access to xml file and you can load that XSD to save time for type creation:
Message type for sender "MT_XML_SND" based on the data type "DT_XML_TYPE". Message type for receiver "MT_XML_RCV" based on the data type "DT_XML_TYPE" as well. Service interface "SI_XML_SND" to describe interface of sender as follows:
Service interface "SI_XML_RCV" to describe interface of receiver as follows:
Finally you have to create the operational mapping "OM_XML_JM_XML" based on your service interfaces and Imported Archive with your jar file as follows:
6) Test our operation mapping based on Java mapping . a. Switch the tab "Definition" to "Test" on your operation mapping editing page and fill in the test values:
b. Press test button (in the left bottom corner), and you have to get message with results of executing. Explore that message and if the transmitting was successful, so you can check the result panel as well, there must be the same data which have been entered on left panel in test.
7) Create the Integration Part of our scenario. Once the previous steps have been done, you have to create the integration part of your scenario. Put your scenario in separate folder, as I usually do it. The next objects of your integration scenario has to be done:
To create that objects you have to make each object in the order as follows: Create the business system "BS_XML_SND" which is describe your sender system and based on your business component which must be assigned to your software component which you have just used to create in previous step service mapping.
Create the business system "BS_XML_RECV" for your receiver. This system must be also relevant to your business component which is assigned to your software component that has been used for service mapping.
Create the sender channel "CC_XML_SND" which has the "File" type of adapter with transport protocol "Ftp". Use your own ftp site to provide ftp folder for sender, in my case it was "BS_XML_SND" on my server "EPBYMINW2009". To be possible to use the any file name (but inner format will be important, but this one will be explained later) you can adjust any file name by expression "*.*" but in this case you have to adjust the tab "Advanced " as well (see the second screen below).
Create the receiver channel "CC_XML_RCV" which has "File" type with transport protocol "Ftp". Adjust the receiver with parameters of your ftp server for receiving files, in my case it was "BS_XML_RCV" ftp folder on my server "epbyminsw2009". Put all marked settings in proper status to be ensured that it create the xml files with different names that is provided by name from sender side. Look at the next three screens to understand it more clear:
Create the sender agreement "BC_XML_SND | SI_XML_SND" which defines which service interface connected to our business component of sender.
Create the receiver determination "BC_XML_SND | SI_XML_SND" which will determine our receiver communication channel "BC_XML_RECV".
Create the interface determination "BC_XML_SND | BI_XML_SND | BC_XML_RECV" which will determine the service interface "SI_XML_RCV" for receiver side.
Create the receiver agreement "BC_XML_SND | SI_XML_RECV | SI_XML_RCV" which defines which service interface must be used for our receiver communication channel "CC_XML_RCV"
8) Test our scenario by real XML file. a. Once all previous steps have been done, you can test the whole your scenario by real file. To do that you have to create the test file with data that will suitable for our data type which we have used when created the communication scenario, so let me propose the next content of file which you can use in your test:
1 Test
b. Name that file for example "test.xml" and put your file on the "BS_XML_SND" folder of your ftp server which we have connected to our integration scenario, as follows:
c. When that folder will be empty, you understand that the sender part is started working:
d. Go to the receiver folder "BS_XML_RCV" to check the received or not our file there. And we got it there, as follows:
e. Go to the our PI server by SAP GUI to check the payload log of our scenario by transaction "SXMB_MONI" as follows: Select the "Monitor for processed XML Messages"
Select the period (by default it is right range and you can not change anything) and press execute:
You will find the XML messages which has been transformed. As you can see we are able to find our scenario:
Press twice on our scenario to be able look at the inbound and response messages to be able to make analysis of the all parts of messages (how it was detected sender, receiver, which reliable messages has been sent, how many hopes were used and so on)
This is the end that manual. Finally we did message transfer via Java Mapping module which we created by ourselves and implemented correctly in our scenario. Since you have done that, you are able to make such scenarios and repeat it for future another type of scenarios. Thank you for your attention, and I hope that it was help . Sincerely, LukCAD.
