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.
- Download and install WSO2 ESB using instruction given in section Getting Started.
- Download the sapidoc3.jar and sapjco3.jar middleware libraries from SAP support at http://service.sap.com/connectors, and copy them to <ESB_HOME>/repository/components/lib directory.
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/sapdirectory. When communicating with an external SAP endpoint using IDoc or BAPI, there are two property files for server-side and client-side as follows: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 isSAPSYS01, the name of the file should beSAPSYS01.destand 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
- *.server - SAP endpoint properties when the ESB acts as the server to an external SAP endpoint. This file should be named
<SAP-GWHOST>.server.For example, if the name of your SAP gateway isSAPSYS01, the name of the file should beSAPSYS01.server.The SAP client and server properties file should be available with its name according to the property transport.sap.serverName for server, and the endpoint name for the destination. The next section explains this in detail.
- Start the ESB using the
-Djava.library.pathswitch 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 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 Configuration | ProxyService Configuration | |
|---|---|---|
BAPI/RFC adapter | <endpoint name="sapbapiendpoint"> <address uri="bapi:/JCOCLIENT01"/> </endpoint> The SAP endpoint client property file should be in <ESB_HOME>//repository/conf/sap/JCOCLIENT01.dest. | <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 | <endpoint name="sapidocendpoint"> <address uri="idoc:/JCOCLIENT01"/> </endpoint> The SAP endpoint client property file should be in <ESB_HOME>/repository/conf/sap/JCOCLIENT01.dest | <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) |
jco.server.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.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
Given below are general troubleshooting guides.
How to handle the Server unknown error
An example of this error message is as follows:
[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 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.
sapgw00 3300/tcp sapgw01 3301/tcp