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 moment 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 (OM_XML_JM_XML) -> 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:

Create mapping project and export in JAR file.1)Prepare the Enterprise Service Part of your scenario.2)Import JAR file into Imported Archives (IA) of mapping objects.3)Test our imported JAR file in the IA object.4)End creating of the Enterprise Service Part of our scenario based on Java mapping.5)Test our operation mapping based on Java mapping.6)Create the Integration Part of our scenario.7)Test our scenario by real XML file.8)

Step by step activity to execute main steps:

Creating mapping project and export in JAR file.1)

Get jar file of mapping library from your PI server. a.

To be able to use the library which consists the necessary components I did search in the folder "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.jar

I opened the containing folder. The path of that folder was the next (yours will be another):

SAP PI 7.11 Java Mapping Step By StepMonday, February 04, 20137:14 PM

PI Page 1

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 workstation to be able to use it in my work space locally.

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] ).

Create your java project, open properties and add two libraries there:b.

Check that your project has the 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()" 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:

c.

PI Page 2

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:

d.

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 you 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/frameset.htm):

e.

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;

PI Page 3

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 DocumentBuilder.", 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);

}

}

}

PI Page 4

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

Export this project into JAR file to be able use it for importing in future steps. Do the next:e.

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:

PI Page 5

Prepare the Enterprise Service Part of your scenario.2)

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).

Select your namespace and open context menu where you can do the new adding of Imported Archives as follows:

a.

Import JAR file into Imported Archives (IA) of mapping objects.3)

PI Page 6

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:

b.

Select the main class of our java mapping which you can find after importing into the list of our "IA_EclipsMap" object as follows:

a.

Test our imported JAR file in the IA object.4)

PI Page 7

Press pictogram "Display Program" b.

If your JAR file is suitable you will get some list of methods from your class, but if it is not suitable then you will get message that code with error. 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:

c.

Add all necessary elements of your message mapping, I mean you have to add:

End creating of the Enterprise Service Part of our scenario based on Java mapping.5)

PI Page 8

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:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://lukcad.com/xml_JM_xml" targetNamespace="http://lukcad.com/xml_JM_xml"> <xsd:complexType name="DT_XML_TYPE"> <xsd:sequence> <xsd:element name="REC" maxOccurs="unbounded"> <xsd:complexType> <xsd:sequence> <xsd:element name="ID" type="xsd:integer" /> <xsd:element name="Name" type="xsd:string" /> </xsd:sequence> </xsd:complexType> </xsd:element> </xsd:sequence> </xsd:complexType></xsd:schema>

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:

Order of creation that objects as follows:

PI Page 9

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:

PI Page 10

Test our operation mapping based on Java mapping.6)

Switch the tab "Definition" to "Test" on your operation mapping editing page and fill in the test values:

a.

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.

b.

PI Page 11

panel in test.

Create the Integration Part of our scenario.7)

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:

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.

To create that objects you have to make each object in the order as follows:

PI Page 12

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).

PI Page 13

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:

PI Page 14

screens to understand it more clear:

PI Page 15

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".

PI Page 16

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"

Test our scenario by real XML file.8)

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:

a.

<?xml version="1.0" encoding="utf-8"?><DT_XML_TYPE><REC><ID>1</ID><Name>Test</Name></REC></DT_XML_TYPE>

PI Page 17

</DT_XML_TYPE>

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:

b.

When that folder will be empty, you understand that the sender part is started working:c.

Go to the receiver folder "BS_XML_RCV" to check the received or not our file there. And we got it there, as follows:

d.

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:

Go to the our PI server by SAP GUI to check the payload log of our scenario by transaction "SXMB_MONI" as follows:

e.

PI Page 18

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

PI Page 19

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.

PI Page 20