Page Comparison

Systems, Applications, and Products (SAP software solutions are ) for data processing is an industry leading enterprise software solution that is widely used among product and process oriented enterprises for finance, operations, HR and many other aspects of the a business. SAP ERP solutions provide reliable and efficient platforms to build and integrate enterprise or business-wide data and information systems with ease.

One of the drawbacks however is vendor lock-in and the relative inflexibility of SAP solutions to align itself with the business model or customization required. Having understood these challenges, SAP software vendors are moving towards exposing their solutions to SOA.

WSO2 ESB on the other hand leverages the best of both worlds by supporting technologies along with native SOA integration technologies. It has the capability to connect existing SAP based solutions of an enterprise with other data/business oriented systems and to mix-and-match user requirements with minimal effort. As a result, enterprises can keep parts of their systems independent of SAP and extensible for many other systems, solutions and middleware.

This section describes how to set up WSO2 ESB in a SAP environment, how to install the SAP JCo middleware library, SAP Intermediate Document (Idoc) and Business Application Programming Interface (BAPI) adapters.

Table of Contents

maxLevel	3
minLevel	3

Installing WSO2 SAP Adapter

The WSO2 SAP adapter is written as a transport for WSO2 ESB. The relevant jar is WSO2 ESB leverages the best of both worlds by providing the integration layer so that an existing SAP R/3 based solutions of an enterprise can be integrated with other data/business oriented systems so that you can mix-and-match requirements with minimal effort. As a result, enterprises can keep parts of their systems independent of SAP and extensible for many other systems, solutions and middleware.

The WSO2 SAP adapter is shipped with WSO2 ESB and is implemented as a transport for WSO2 ESB. This is provided in the <ESB_HOME>/repository/components/plugins directory as org.wso2.carbon.transports.sap-VERSION.jar (e.g. org.wso2.carbon.transports.sap-_1.0.0.jar). Follow the steps below to install and set up.

...

Copy the native SAP jco library to the system path. Pick the system path relevant to your operating system from the list below.

Linux 32-bit	Copy the Linux native SAP jco library (libsapjco3.so) to <JDK_HOME>/jre/lib/i386/server.
Linux 64-bit	Copy the Linux native SAP jco library (libsapjco3.so) to <JDK_HOME>/jre/lib/amd64.
Windows	Copy the Windows native SAP jco library (sapjco3.dll) to <WINDOWS_HOME>/system32.

Copy the SAP endpoint property files to the <ESB_HOME>/repository/conf/sap directory. When communicating with an external SAP endpoint using IDoc or BAPI, there are two property files for server-side and client-side as follows:

Info
This directory does not exist by default. Make sure that you create it and provide access rights to the WSO2 user to read the files saved in it.

...

*.dest - SAP endpoint properties when the ESB acts as the client to an external SAP endpoint. This file should be named <SAP-GWHOST>.dest. For example, if the name of your SAP gateway is SAPSYS01, the name of the file should be SAPSYS01.dest and its configuration can be as follows:

Code Block

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

...

Configuring WSO2 SAP Adapter

As noted earlier, the SAP adapter was written as a new transport for the WSO2 ESB. This transport consists of two parts as follows.

BAPI/RFC transport
IDoc transport

Just as a normal transport, define each of these transports' receiver/sender configurations in <ESB_HOME>/repository/conf/Axis2/axis2.xml file. Examples are given below for your reference.

BAPI/RFC Adapter

transportSender:

...

language	html/xml

...

The WSO2 SAP adapter has full IDoc and experimental BAPI support. It used the SAP JCO library as the underlying framework to communicate with SAP. This section describes how to set up WSO2 ESB in a SAP environment, how to install the SAP JCo middleware library, SAP Intermediate Document (IDoc) and Business Application Programming Interface (BAPI) adapters.

...

Table of Contents

maxLevel	3
minLevel	3
location	top
type	flat
separator	pipe

...

Installing WSO2 SAP Adapter

Follow the instructions below to install and set up the ESB SAP adapter.

Download and install WSO2 ESB by following the instruction in Getting Started.
Download the sapidoc3.jar and sapjco3.jar middleware libraries from the SAP support portal https://websmp109.sap-ag.de/connectors and copy those libraries to the <ESB_HOME>/repository/components/lib directory.
Info
title Note
You need to have SAP login credentials to access the SAP support portal.

Download the native SAP JCo library and copy it to the system path. You need to select the system path applicable to your operating system as described below.

Linux 32-bit	Copy the Linux native SAP jco library `libsapjco3.so` to `<JDK_HOME>/jre/lib/i386/server`.
Linux 64-bit	Copy the Linux native SAP jco library `libsapjco3.so` to `<JDK_HOME>/jre/lib/amd64`.
Windows	Copy the Windows native SAP jco library `sapjco3.dll` to `<WINDOWS_HOME>/system32`.

Copy the following SAP endpoint property files to the <ESB_HOME>/repository/conf/sap directory. You need to have two property files, one at the server-end and the other at the client-end to communicate with an external SAP endpoint using IDoc or BAPI.
Info
This directory does not exist by default. A SAP system administrator has to create the directory and provide access rights so that you can read the property files saved in the directory.
- *.dest : This is where we keep SAP endpoint parameters when WSO2 ESB should act as a client to an external SAP endpoint.
- *.server : This is where we keep SAP endpoint parameters when WSO2 ESB should act as a server to an external SAP endpoint.
For details on creating the property files and defining the relevant properties, see Setting up the *.dest and *.server property files.
Start the ESB using the -Djava.library.path switch to specify the location of your SAP jco library.
For example ./wso2server.sh -Djava.library.path=/usr/lib/jvm/jre1.7.0/lib/i386/server/

...

Configuring WSO2 SAP Adapter

As mentioned above, the SAP adapter is implemented as a transport for WSO2 ESB. This transport consists of two parts as follows:

BAPI/RFC adapter
IDoc adapter

Just like any other transport, you need to enable the BAPI/RFC adapter as well as the IDoc adapter in order to use the SAP adapter.

To enable the BAPI/RFC adapter

Edit the <ESB_HOME>/repository/conf/axis2/axis2.xml file and uncomment the BAPI sender and listener as follows:

Code Block

language	xml

<transportSender name="bapi" class="org.wso2.carbon.transports.sap.SAPTransportSender"/>
...
<transportReceiver name="bapi" class="org.wso2.carbon.transports.sap.SAPTransportListener"/>

To enable the IDoc adapter

Edit the <ESB_HOME>/repository/conf/axis2/axis2.xml file and uncomment the IDoc sender and listener as follows:
Code Block
language xml
<transportSender name=”idoc” class="org.wso2.carbon.transports.sap.SAPTransportSender"/>

...

transportReceiver:

...

language	html/xml

... <transportReceiver name=

...

”idoc” class="org.wso2.carbon.transports.sap.SAPTransportListener"/>

...

Anchor

transportSender:Given below are general troubleshooting guides

	SetupPropertyFiles

Code Block

language	html/xml

<transportSender name=”idoc” class="org.wso2.carbon.transports.sap.SAPTransportSender"/>

transportReceiver:

Code Block

language	html/xml

<transportReceiver name=”idoc” class="org.wso2.carbon.transports.sap.SAPTransportListener"/>

The table below summarizes how to define a SAP endpoint and a proxy service.

Endpoint Configuration

ProxyService Configuration

BAPI/RFC adapter

Code Block

language	html/xml

<endpoint name="sapbapiendpoint">
  <address
 uri="bapi:/JCOCLIENT01"/>
</endpoint>

The SAP endpoint client property file should be in <ESB_HOME>//repository/conf/sap/JCOCLIENT01.dest.

Code Block

language	html/xml

<proxy name=”sapbapiproxy” transports=”bapi”/>
//in,out,fault Sequence
  <parameter name="transport.sap.serverName">  
    JCOSERVER01
  </parameter>
// other parameters
</proxy>

SAP endpoint server property file should be in <ESB_HOME>/repository/conf/sap/JCOS ERVER01.server

IDoc adapter

Code Block

language	html/xml

<endpoint name="sapidocendpoint">
   <address
 uri="idoc:/JCOCLIENT01"/>
</endpoint>

The SAP endpoint client property file should be in <ESB_HOME>/repository/conf/sap/JCOCLIENT01.dest

Code Block

language	html/xml

<proxy name=”sapidocproxy”
 transports=”idoc”/>

//in,out,fault Sequence
  <parameter
 name="transport.sap.serverName">

    JCOSERVER01

  </parameter>

// other parameters
</proxy>

SAP endpoint server property file should be in <ESB_HOME>/repository/conf/sap/JCOSERVER01.server

JCo parameters

You have to specify some properties when communicating with a SAP system using the JCo middleware library. They are specified using the *.dest and *.server properties files in <ESB_HOME>/repository/conf/sap directory. The two tables below define the properties and their possible values.

Server properties (*.server property file)

Property	Description
jco.server.gwhost	Gateway host
jco.server.gwserv	Gateway service
jco.server.progid	Program ID of the server
jco.server.trace	You can enable or disable the RFC trace
jco.server.params	Arbitrary parameters for RFC library
jco.server.snc_myname	SNC name
jco.server.snc_qop	SNC level of security (1-9)
jco.server.snc_lib	Path to the SNC library
jco.server.profile_name	Name of the profile file used during start-up
jco.server.unicode	Determines whether or not you connect in unicode mode (1=true, 0=false)
max_startup_delay	Maximum server start-up delay time in seconds

Client properties (*.dest property file)

Property	Description
jco.client.client	Client logon
jco.client.user	User logon
jco.client.alias_user	Alias user name
jco.client.passwd	Logon password
jco.client.lang	Logon language
jco.client.sysnr	R/3 system number
jco.client.ashost	R/3 application server
jco.client.mshost	R/3 message server
jco.client.gwhost	Gateway host
jco.client.gwserv	Gateway service
jco.client.r3name	R/3 name
jco.client.group	Group of application servers
jco.client.tpname	Program ID of external server program
jco.client.tphost	Host of external server program
jco.client.type	Type of remote host (3=R/3, E=External)
jco.client.codepage	Initial code page for logon
jco.client.use_sapgui	Use remote SAP graphical user interface
jco.client.mysapsso2	Use the specified SAP cookie version 2 as the logon ticket
jco.client.grt_data	Additional data for GUI
jco.client.use_guihost	Host to which the remote GUI is redirected
jco.client.use_guiserv	Service to which the remote GUI is redirected
jco.client.use_guiprogid	Progid of the server that starts the remote GUI
jco.client.snc_partnername	SNC partner name (for example, CN=B20, O=SAP-AG, C=DE\) snc_mode
jco.client.snc_mode	SNC mode (0 or 1)
jco.client.snc_qop	SNC level of security (1-9)
jco.client.snc_myname	SNC name; overrides default SNC partner
jco.client.snc_lib	Path to the library
jco.client.Dest	R/2 destination
jco.client.saplogon_id	SAPLOGON string on 32-bit Windows
jco.client.extiddata	Data for external application (PAS)
jco.client.extidtype	Type of external authentication (PAS)
jco.client.x509cert	Use the specified X509-certificate as the logon ticket
jco.client.msserv	R/3 port number of message server
jco.client.profile_name	Profile name used for shared memory communication
jco.client.idle_timeout	Idle timeout for the connection
jco.client.ice Ignore	RFC library character conversion errors (1 or 0)
jco.client.logon	Enable or disable logon check at open time (1 or 0)
jco.client.trace	Enable or disable RFC trace (1 or 0)
jco.client.abap_debug	Enable ABAP debugging (1 or 0)
jco.client.getsso2	Get or do not get a SSO ticket after logon (1 or 0)
jco.client.toupper	Enable or disable uppercase character conversions for logon

Troubleshooting

SetupPropertyFiles

...

Setting up the *.dest property file

To setup WSO2 ESB as a client to a SAP system you need to create the *.dest property file and define the relevant properties. The following table lists the properties and the description of each property that should be specified in the *.dest property file.

Property	Description
`jco.client.client`	Client logon
`jco.client.user`	User logon
`jco.client.alias_user`	Alias user name
`jco.client.passwd`	Logon password
`jco.client.lang`	Logon language
`jco.client.sysnr`	R/3 system number
`jco.client.ashost`	R/3 application server
`jco.client.mshost`	R/3 message server
`jco.client.gwhost`	Gateway host
`jco.client.gwserv`	Gateway service
`jco.client.r3name`	R/3 name
`jco.client.group`	Group of application servers
`jco.client.tpname`	Program ID of external server program
`jco.client.tphost`	Host of external server program
`jco.client.type`	Type of remote host (3=R/3, E=External)
`jco.client.codepage`	Initial code page for logon
`jco.client.use_sapgui`	Use remote SAP graphical user interface
`jco.client.mysapsso2`	Use the specified SAP cookie version 2 as the logon ticket
`jco.client.grt_data`	Additional data for GUI
`jco.client.use_guihost`	Host to which the remote GUI is redirected
`jco.client.use_guiserv`	Service to which the remote GUI is redirected
`jco.client.use_guiprogid`	Progid of the server that starts the remote GUI
`jco.client.snc_partnername`	SNC partner name (for example, CN=B20, O=SAP-AG, C=DE\) snc_mode
`jco.client.snc_mode`	SNC mode (0 or 1)
`jco.client.snc_qop`	SNC level of security (1-9)
`jco.client.snc_myname`	SNC name; overrides default SNC partner
`jco.client.snc_lib`	Path to the library
`jco.client.Dest`	R/2 destination
`jco.client.saplogon_id`	SAPLOGON string on 32-bit Windows
`jco.client.extiddata`	Data for external application (PAS)
`jco.client.extidtype`	Type of external authentication (PAS)
`jco.client.x509cert`	Use the specified X509-certificate as the logon ticket
`jco.client.msserv`	R/3 port number of message server
`jco.client.profile_name`	Profile name used for shared memory communication
`jco.client.idle_timeout`	Idle timeout for the connection
`jco.client.ice Ignore`	RFC library character conversion errors (1 or 0)
`jco.client.logon`	Enable or disable logon check at open time (1 or 0)
`jco.client.trace`	Enable or disable RFC trace (1 or 0)
`jco.client.abap_debug`	Enable ABAP debugging (1 or 0)
`jco.client.getsso2`	Get or do not get a SSO ticket after logon (1 or 0)
`jco.client.toupper`	Enable or disable uppercase character conversions for logon

Info

title	Note

You can obtain the values for these properties from your SAP system administrator.

The *.dest property file should be named <SAP-GWHOST>.dest. For example, if the name of your SAP gateway is SAPSYS, the name of the file should be SAPSYS.dest.

Following is a sample configuration for the *.dest property file:

Code Block

jco.client.client=800
jco.client.user=wso2_user
jco.client.passwd=wso2pass14
jco.client.lang=en
jco.client.ashost=/H/217.116.29.154/S/3299/H/10.100.5.120/S/3200
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=CPT

Setting up the *.server property file

To setup WSO2 ESB as an IDoc server you need to create the *.server property file and define the relevant properties. The following table lists the properties and the description of each property that should be specified in the *.server property file.

Property	Description
`jco.server.gwhost`	Gateway host
`jco.server.gwserv`	Gateway service
`jco.server.progid`	Program ID of the server
`jco.server.trace`	You can enable or disable the RFC trace
`jco.server.repository_destination`	Name of the `.dest` file. For example, if the `.dest` file is `SAPSYS01.dest` , set this to `SAPSYS01` .
`jco.server.params`	Arbitrary parameters for RFC library
`jco.server.snc_myname`	SNC name
`jco.server.snc_qop`	SNC level of security (1-9)
`jco.server.snc_lib`	Path to the SNC library
`jco.server.profile_name`	Name of the profile file used during start-up
`jco.server.unicode`	Determines whether or not you connect in unicode mode (1=true, 0=false)
`jco.server.max_startup_delay`	Maximum server start-up delay time in seconds

Info

title	Note

You can obtain the values for these properties from your SAP system administrator.

This file should be named <SAP-GWHOST>.server. For example, if the name of your SAP gateway is SAPSYS, the name of the file should be SAPSYS.server.

Following is a sample configuration for the *.server property file:

Code Block
jco.server.gwhost=/H/217.116.29.154/S/3299/H/10.100.5.120/S/3200 jco.server.gwserv=3300 jco.server.progid=IGS.CPT jco.server.repository_destination=IGS.CPT jco.server.name=IGS.CPT jco.server.unicode=1

The table below summarises how you can define a SAP endpoint and a proxy service.

Endpoint Configuration ProxyService Configuration

BAPI/RFC adapter

Code Block

language	html/xml

<endpoint name="sapbapiendpoint">
  <address uri="bapi:/JCOCLIENT01"/>
</endpoint>

The SAP endpoint client property file should be in <ESB_HOME>/repository/conf/sap/JCOCLIENT01.dest

Code Block

language	html/xml

<proxy name=”sapbapiproxy” transports=”bapi”/>
//in,out,fault Sequence
  <parameter name="transport.sap.serverName">JCOSERVER01</parameter>
// other parameters
</proxy>

SAP endpoint server property file should be in <ESB_HOME>/repository/conf/sap/JCOS ERVER01.server

IDoc adapter

Code Block

language	html/xml

<endpoint name="sapidocendpoint">
   <address uri="idoc:/JCOCLIENT01"/>
</endpoint>

The SAP endpoint client property file should be in <ESB_HOME>/repository/conf/sap/JCOCLIENT01.dest

Code Block

language	html/xml

<proxy name=”sapidocproxy”transports=”idoc”/>
//in,out,fault Sequence
  <parameter name="transport.sap.serverName">JCOSERVER01</parameter>
// other parameters
</proxy>

SAP endpoint server property file should be in <ESB_HOME>/repository/conf/sap/JCOSERVER01.server

...

Troubleshooting

Given below are general troubleshooting guidelines.

How to handle the Server unknown error

An example of this error message is as follows:

Code Block

[2010-10-25 19:53:00,405] ERROR - DefaultErrorListener Exception occured on :
JCOSERVER01 and connection : null
com.sap.conn.jco.JCoException: (129) JCO_ERROR_SERVER_STARTUP: Server startup
failed at Mon Oct 25 19:53:00 IST 2010.
This is caused by either a) erroneous server settings, b) the backend system has been shutdown,
c) network problems. Will try next startup in 1 seconds.
Could not start server: Connect to SAP gateway failed
Connect parameters: TPNAME=JCOSERVER01 GWHOST=cynthia GWSERV=sapgw00
ERROR service 'sapgw00' unknown
TIME Mon Oct 25 19:53:00 2010
RELEASE 720
COMPONENT NI (network interface)
VERSION 40
RC -3
MODULE nixxsl.cpp
LINE 184
DETAIL NiSrvLGetServNo: service name cached as unknown
COUNTER 2
at com.sap.conn.jco.rt.DefaultServer.openConnection(DefaultServer.java:1168)
at com.sap.conn.jco.rt.DefaultServer.openConnections(DefaultServer.java:1057)
at com.sap.conn.jco.rt.DefaultServer.adjustConnectionCount(DefaultServer.java:1004)
at
com.sap.conn.jco.rt.DefaultServerManager$DispatcherWorker.run(DefaultServerManager.java:
299)
at java.lang.Thread.run(Thread.java:619)
Caused by: com.sap.conn.jco.JCoException: (129) JCO_ERROR_SERVER_STARTUP: Could
not start server: Connect to SAP gateway failed
Connect parameters: TPNAME=JCOSERVER01 GWHOST=cynthia GWSERV=sapgw00
ERROR service 'sapgw00' unknown
TIME Mon Oct 25 19:53:00 2010
RELEASE 720
COMPONENT NI (network interface)
VERSION 40
RC -3
MODULE nixxsl.cpp
LINE 184
DETAIL NiSrvLGetServNo: service name cached as unknown
COUNTER 2
at
com.sap.conn.jco.rt.MiddlewareJavaRfc$JavaRfcServer.accept(MiddlewareJavaRfc.java:2135)
at com.sap.conn.jco.rt.ServerConnection.accept(ServerConnection.java:380)
at com.sap.conn.jco.rt.DefaultServer.openConnection(DefaultServer.java:1149)
© 2012 WSO2
.. 4 more
Caused by: RfcException: [null]
message: Connect to SAP gateway failed
Connect parameters: TPNAME=JCOSERVER01 GWHOST=cynthia GWSERV=sapgw00
ERROR service 'sapgw00' unknown
TIME Mon Oct 25 19:53:00 2010
RELEASE 720
COMPONENT NI (network interface)
VERSION 40
RC -3
MODULE nixxsl.cpp
LINE 184
DETAIL NiSrvLGetServNo: service name cached as unknown
COUNTER 2
Return code: RFC_FAILURE(1)
error group: 102
key: RFC_ERROR_COMMUNICATION
at com.sap.conn.rfc.engine.RfcIoControl.error_end(RfcIoControl.java:255)
at com.sap.conn.rfc.engine.RfcIoControl.ab_rfcaccept(RfcIoControl.java:43)
at com.sap.conn.rfc.api.RfcApi.RfcAccept(RfcApi.java:41)
at
com.sap.conn.jco.rt.MiddlewareJavaRfc$JavaRfcServer.accept(MiddlewareJavaRfc.java:2121)
... 6 more

The solution to overcome this is to add your SAP server names to the /etc/services file with

...

the relevant ports. For example, the following lines can be added

...

if we consider the example error given above.
Code Block
sapgw00 3300/tcp sapgw01 3301/tcp

Excerpt

hidden	true

Information about enterprise integration with SAP and WSO2 ESB.

Versions Compared

Old Version 5

New Version 6

Key

Installing WSO2 SAP Adapter

Configuring WSO2 SAP Adapter

BAPI/RFC Adapter

Installing WSO2 SAP Adapter

Configuring WSO2 SAP Adapter

To enable the BAPI/RFC adapter

To enable the IDoc adapter

JCo parameters

Troubleshooting

Setting up the *.dest property file

Setting up the *.server property file

Troubleshooting

How to handle the Server unknown error