Page Comparison

SAP software solutions are widely used among product and process oriented enterprises for finance, operations, HR and many other aspects of the 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.

Installing WSO2 SAP Adapter

The WSO2 SAP adapter is written as a transport for WSO2 ESB. The relevant jar is org.wso2.carbon.transports.sap-VERSION.jar (e.g. org.wso2.carbon.transports.sap-1.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.

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:

...

*.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:

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:

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

transportReceiver:

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

IDoc Adapter

transportSender:

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

transportReceiver:

<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 name="sapbapiendpoint">
  <address
 uri="bapi:/JCOCLIENT01"/>
</endpoint>

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

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

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

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

    JCOSERVER01

  </parameter>

// other parameters
</proxy>

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)

Client properties (*.dest property file)

Troubleshooting

Given below are general troubleshooting guides.

How to handle the Server unknown error

An example of this error message is as follows:

...

Systems, Applications, and Products (SAP) 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 a business. SAP ERP solutions provide reliable and efficient platforms to build and integrate enterprise or business-wide data and information systems with ease. 

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 asorg.wso2.carbon.transports.sap-VERSION.jar (e.g. org.wso2.carbon.transports.sap_1.0.0.jar).

The WSO2 SAP adapter has full IDoc and experimental BAPI support. It uses 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.

...

...

Installing WSO2 SAP Adapter

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

1. Download and install WSO2 ESB by following the instruction in Installation Guide.

2. Download the sapidoc3.jar and sapjco3.jar middleware libraries from the SAP support portal 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.

3. 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 jcolibrary libsapjco3.so to <JDK_HOME>/jre/lib/i386/server.
   Linux 64-bit	Copy the Linux native SAP jcolibrary libsapjco3.so to <JDK_HOME>/jre/lib/amd64.
   Windows	Copy the Windows native SAP jcolibrary sapjco3.dll to <WINDOWS_HOME>/system32.

4. Create a directory named sap in the <ESB_HOME>/repository/conf/ directory and provide access rights to read the properties files you will save in it later.

5. Copy the following SAP endpoint properties files to the <ESB_HOME>/repository/conf/sap directory. You need to have two properties files, one at the server-end and the other at the client-end to communicate with an external SAP endpoint using IDoc or BAPI.

   • *.dest : This is where we store SAP endpoint parameters when WSO2 ESB is configured as a client to an external SAP endpoint.  
   • *.server : This is where we store SAP endpoint parameters when WSO2 ESB is configured as a server to an external SAP endpoint.
   For details on creating the properties files and defining the relevant properties, see Setting up the Client Configuration File and Setting up the Server Configuration File.
6. 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/ 


...

Setting up the Client Configuration File

To setup WSO2 ESB as a client to a SAP system you need to create the *.dest properties 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 properties file.

The *.dest properties 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 properties file:

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

Anchor
SetupServerPropertyFiles SetupServerPropertyFiles

Setting up the Server Configuration File

To setup WSO2 ESB as an IDoc server you need to create the *.server properties 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 properties file.

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 properties file:

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

Configuring WSO2 SAP Adapter

Go to the required tab for detailed steps based on how you need to configure WSO2 SAP Adapter.

Additional Configuration Parameter

This section describes additional parameters that can be used when configuring WSO2 SAP adapter.

SAP Transport Sender Parameters

Following are descriptions of the SAP client properties that can be defined in the message context with axis2-client scope when using WSO2 ESB as a SAP client to send messages. These properties can be added in <ESB_HOME>/repository/conf/axis2/axis-client.xml file:

Following is an Axis2 transport sender property that can be defined in <ESB_HOME>/repository/conf/axis2.xml file: 

transport.sap.customXMLMappers : The key/value list of custom mappers, where the values are fully qualified class names for custom mappers implementing org.wso2.carbon.transports.sap.idoc.IDocXMLMapper.

Anchor
ListenerParameters ListenerParameters

 

Proxy Service Listener Parameters

Following are descriptions of the proxy level listener parameters that can be defined in a proxy configuration when using WSO2 ESB as a SAP 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.

...

The solution is to add your SAP server names to /etc/services file with their relevant ports. For example, the following lines can be added as relevant to the example error given above.

...

• 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

• How to handle connection to message server host failed error  
  
  An example of this error message is as follows:

  Code Block
  language xml
  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 indicates that that the username (i.e. wso2-user) used in the above configuration is not assigned to the 'public' user group. 
  The solution to overcome this is to add wso2-user to the user group named public in your SAP system. If such a group does not exist, a user group named 'public' needs be created and the above user needs to be added to that group.