WSO2 ESB comes with a variety of adapters to connect to all sorts of different systems. One of these adapters is the SAP adapter.
The WSO2 SAP adapter has full iDOC and experimental BAPI support. It used the SAP JCO library as underlying framework to communicate with SAP.
Installing the adapter couldn’t be easier. Its shipped with WSO2 ESB and the WSO2 ESB documentation website describes the installation procedure from the WSO2 perspective.
The installation procedure however does not guide you on how to find the settings you need in SAP.
So, let’s start off with some SAP adapter knowledge. I’ll refer to the WSO2 ESB SAP adapter as ‘SA’ in the following guide.
The SA is capable to be used as a Client as well as a Server. To setup the SA as client to a SAP system you’ll need to setup a client-side configuration fle. This file should be named [SAP-GWHOST].dest and must be placed in the [WSO2_HOME]/repository/conf/sap folder. This folder does not exist per default so make sure you create it and provide enough access rights for the WSO2 user to read the files within it.
To setup the WSO2 as an idoc server you must create a configuration file named [SAP-GWHOST].server.
Let’s first handle the client configuration file. There might be some differences based on your SAP system but the following settings should cover a lot of installations. The screenshots are based on SAP ECC version 6.0
In the examples below the SAP gateway is known as SAPSYS01.
The configuration of the SAPSYS01.dest (remember this is the “using WSO2 ESB as a SAP client” configuration) has the following content:
jco.client.client=900
jco.client.user=spremote
jco.client.passwd=FILL_IN_YOUR_PASSWORD_HERE
jco.client.lang=en
jco.client.ashost=SAPSYS01
jco.client.mshost=SAPSYS01
jco.client.gwhost=SAPSYS01
jco.client.gwserv=3300
jco.client.sysnr=00
jco.client.idle_timeout=300
jco.client.logon=0
jco.client.msserv=3600
jco.client.trace=0
jco.client.getsso2=0
jco.client.r3name=QCR
Ok, lets open up some screens in the SAP system. Assuming an experienced SAP engineer will be doing this you could either go through the SAP Easy Access menu or directly open up the appropriate transaction screen.
Open the System Gateway Monitor (SMGW) and use the top-menu named Goto – Parameters and Display as shown below.
The following screen will show:
Use the highlighted values from the Gateway Monitor Values for the jco.client.gwhost andjco.client.gwserv respectively.
Please be aware that you can substituted the service name (sapgw00 in the screenshot) to its corresponding port number (“sapgw00“ corresponds to portnumber 3300). Please see the last paragraph at Communication Connections of the R/3 System for more information.
Now, open transaction /NSMMS which will show the following screen:
The highlighted values are to be used for respectively jco.client.msserv and jco.client.mshost
To find the SAP Server you’ll need to open transaction /NSSM51 which shows the following screen:
Use this highlighted value as jco.client.ashost
Then you’ll need to open transaction RZ11 and select the parameter name “SAP SYSTEM” and press Display which will show you the following screen:
Use the “Current value” as value for jco.client.sysnr
OK So far so good, we have already a bunch of values of our client configuration, but we’re not there yet.
Open the System status to get some additional values. Do that through the top menu, select System and then Status which will show the following screen:
Use the values shown Client value for jco.client.client, user for jco.client.user, and Language for jco.client.lang
Based on the username shown here make sure to fill in the password for this useraccount injco.client.passwd
To find the R/3 name parameter value you’ll need to open transaction /NSMMS and then use the topmenu Goto -> Parameters -> Display which will show the following screen:
Here you need to use the server service name and strip off the “sapms” part which in the screenshot case will leave you with ERD as jco.client.r3name
There are still some settings left. These are jco.client.getsso2, jco.client.logon andjco.client.idle_timeout and jco.client.trace
The jco.client.getsso2 value can be left as value 0. It indicates whether a Single-Sign On ticket should be requested from SAP. That will not be used in this setup.
The jco.client.logon can also be left 0. It enables or disabled the logon check when a connection is opened to SAP.
The jco.client.idle_timeout can be left default to value 300. This setting allows connections to stay open for a specified amount of time. It is beneficial to leave this rather lengthy as that saves the connection setup overhead upon sending data to SAP.
The last setting is jco.client.trace can be used to switch on SAP JCO tracing. Trace files will be stored in WSO2_HOME and will be called jco_XXXXX.trc where XXXXX is a unique number to indicate the request.
Once all connection settings from the above paragraphs have been found and configured in the server and dest files then you might still run into issues.
One of which is a common issue where the following error appears:
Connect to message server host failed
Connection parameters: TYPE=B DEST=SAPSYS01 MSHOST=SAPSYS01 MSSERV=3600 R3NAME=ERD GROUP=PUBLIC PCS=1
ERROR Group PUBLIC not found
TIME Fri Jan 24 15:48:53 2014
This issue indicates that the user (Called “SPREMOTE” in the above configuration steps) is not assigned to the public user-role.
To fix this open up transaction /NSMLG where you must select the “PUBLIC” logon group. Then go to the top menu, choose Goto and User list as show here.
If there is no public logon group then you should create one.
This can be done using the Create new assignment button in the CCMS:Maintain Logon Groups screen above.
As can be seen in the screenshot below; fill in PUBLIC as logon group name and click Copy to create the group.
Receiving IDOCs
Ok, so lets start off with setting up WSO2 as an IDOC server so that you can receive IDOC within WSO2. Assuming you read and executed the previous post you should now have the SAPSYS01.dest and SAPSYS01.server files. To setup WSO2 as an IDOC server you need only the SAPSYS01.server configuration file in [WSO2_HOME]/repository/conf/sap.
Make sure that your axis2.xml (which is located in [WSO2_HOME]/repository/conf/axis2) has the SAPTransportListener named idoc and the SAPTransportSender named idoc uncommented/enabled.
Please create a proxy service. Use the Custom proxy type and give it contents similar to the following:
<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns=http://ws.apache.org/ns/synapse name="SAPAdapterProxy"
transports="idoc" statistics="enable" trace="enable" startOnLoad="true">
<target>
<inSequence>
<log level="full"/>
<drop />
</inSequence>
<outSequence>
<log level="full"/>
<send/>
</outSequence>
</target>
<parameter name="transport.sap.enableTIDHandler">enabled</parameter>
<parameter name="transport.sap.serverName">SAPSYS01</parameter>
<description/>
</proxy>
The magical parts are in bold.
First tell WSO2 to start listening with an idoc transport listener by setting the transports attribute value to “idoc”.
Then to configure the TransportListener you must set the two parameters which are highlighted at the bottom of the proxy. The first being the transactionHandler which needs to be enabled and the second needs tob e the servername of the SAP server you have a configuration setup for. In our case that is the SAPSYS01.server configuration file or SAPSYS01 SAP system name.
When you deploy this proxy then you should see a message in the log indicating that WSO2 is listening for incoming IDOCs.
TID: [0] [ESB] [2014-02-04 11:28:44,474] [localhost-startStop-1] DEBUG {org.wso2.carbon.transports.sap.idoc.IDocEndpoint} - Engaging the default TID handler for : SAPSYS01 {org.wso2.carbon.transports.sap.idoc.IDocEndpoint}
TID: [0] [ESB] [2014-02-04 11:28:44,481] [localhost-startStop-1] INFO {org.wso2.carbon.transports.sap.idoc.IDocEndpoint} - IDoc server started with server name : SAPSYS01 and program ID : JCOSERVER01 {org.wso2.carbon.transports.sap.idoc.IDocEndpoint}
Within your SAP system you should be able to see that an RFC connection to WSO2 is alive.
When you now send an iDOC over the new RFC connection to the registered programID (which is JCOSERVER01 as can be seen from the logstatements above) it will end up in the WSO2 proxy and the log-mediator will show you the IDOC received from SAP.
When you dont get the IDOC in the proxy then fiddle around a bit with the unicode setting in SAP. Experience showed me that enabling or disabling that at the SAP side fixes the connection and the IDOC is received properly.
Sending IDOCs
Sending IDOCs is actually rather easier than receiving them. To send IDOCs to SAP you need to have the SAPSYS01.dest configuration file setup. Please see my previous post for more details.
Lets create a custom proxy again with the following content:
<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns=http://ws.apache.org/ns/synapse name="SAPSenderProxy"
transports="http" startOnLoad="true" trace="enable" statistics="enable">
<description/>
<target>
<inSequence>
<log level="full"/>
<send>
<endpoint name="sapidocendpoint">
<address uri="idoc:/SAPSYS01"/>
</endpoint>
</send>
</inSequence>
<outSequence/>
</target>
<parameter name="serviceType">proxy</parameter>
</proxy>
This proxy has been configured as an ordinary one where you send your data to it over the HTTP transport. The special part is in the address of the send-mediator’s endpoint. You must configure it to use the idoc transport and set the hostname-part of the URI to your SAP systems name.
You should now be up and running with your IDOC connections.
