MuleSoft Enterprise Java Connector for SAP

Enterprise

This connector requires a separate license. Please contact MuleSoft if you want to evaluate or use this connector.

Introduction

The Mule SAP Transport uses SAP Java Connector (JCo) libraries, thus enabling your Mule application to:

Execute BAPI functions over sRFC (synchronous RFC), tRFC (transactional RFC) and qRFC (queued RFC)
Act as a JCo Server to be called as a BAPI over sRFC, tRFC and qRFC
Send IDocs over tRFC and qRFC
Receive IDocs over tRFC and qRFC
Transform all SAP objects (JCoFunction & IDocs) to/from XML

Mule Compatibility

There are two versions of the MuleSoft Enterprise Java Connector for SAP:

1.x: Compatible with Mule 3.0 / 3.1 / 3.2
2.x: Compatible with Mule 3.3 / 3.4

Stateful transactions, involving multiple outbound endpoints, only work starting in Mule 3.3 with the transactional scope.

Installation

The SAP transport needs JCo libraries to operate. The following section explains how to setup Mule ESB so that you can use the SAP transport in your Mule applications:

This procedure assumes that you already have a Mule instance installed on your host machine. If not, then follow the instructions for downloading and installing Mule.

Throughout this document, we use $MULE_HOME to refer to the directory where Mule is installed.

Download the SAP JCo and IDoc libraries from the SAP site: http://service.sap.com/connectors (To do this, you need a SAP User ID).
Make sure that the SAP jars available to your Mule application and/or Mule ESB instance. JCo relies on a native library, which requires additional installation steps.
If you plan to use SAP as an Inbound Endpoint (i.e., Mule will be called as a BAPI or will receive IDocs), you must perform additional configuration within the services file at the OS level.

About the SAP JCo and IDoc Library Versions

The SAP Transport requires:

SAP JCo Library 3.0.x (Tested with sapjco-3.0.7.jar and sapjco-3.0.9.jar)
SAP IDoc Libraries 3.0.x (Tested with sapidoc-3.0.6.jar)

The SAP JCo libraries are OS dependent, so make sure to download the SAP libraries that correspond to the OS and hardware architecture of the host server on which Mule will be running.

Making Jars Available to Your Mule ESB Application

Follow the instructions provided by SAP to install the JCo libraries, but remember that certain jar files must be located in your application CLASSPATH, and the dynamic link library (dll/so) must reside in your LD_LIBRARY_PATH.

Next, include the transport jar file (mule-transport-sap-{version}.jar) in your application CLASSPATH.

About the Application CLASSPATH

The Mule SAP Transport depends on three libraries:

mule-transport-sap-{version}.jar
sapjco-3.0.x.jar
sapidoc-3.0.x.jar

You need to place these in your application CLASSPATH.

For the SAP Transport, MuleSoft recommends the following directories:

$MULE_HOME/apps/YOUR_APP/lib: To make libraries available for just your application.
$MULE_HOME/lib/user: To share libraries among all applications running within the same Mule ESB instance. As SAP JCo configuration is a singleton, if you go this way, then all your applications will share the same configuration, including the JCo destination repository.

Your application lib directory is automatically enabled to support dynamic libraries. If you are not including them there, then you also need to tell Mule ESB where the SAP JCo dynamic linked library resides. To accomplish this, you can do either of the following:

Configure the LD_LIBRARY_PATH environment variable
Configure the Mule ESB wrapper configuration file $MULE_HOME/conf/wrapper.conf by adding the line wrapper.java.library.path.{N}=PATH/TO/SAP-JCO/LIB-DIR

IMPORTANT: Do not combine both strategies (For example putting JCo libraries in the mule instance shared lib directory (For example $MULE_HOME/lib/user) and the SAP connector library inside your application $MULE_HOME/apps/YOUR_APP/lib. This will cause classloader issues as JCo libraries hold configuration in static fields (singletons).

Example: Shipping all dependencies inside your application

Lets assume you have an application called sap-test deployed in $MULE_HOME/apps in a Windows x86 box. Then the directory tree in order to have all the connector dependencies is:

$MULE_HOME/apps/sap-test/lib
- mule-transport-sap-{version}.jar
- sapjco-3.0.x.jar
- sapidoc-3.0.x.jar
- sapjco3.dll

It is recommended to configure the SAP libraries at Mule instance level, as having two applications with different versions of the SAP transport and/or JCo libraries may cause classloader issues.

SAP Inbound Endpoint Requirements

If you are configuring a SAP Inbound Endpoint (JCo Server), then you will need to modify your OS services file, which is:

/etc/services file (for Unix-based OSes)
C:\WINDOWS\system32\drivers\etc\services file (for Windows)

In the above file, you must add your gateway (which is configured through the jcoGwService attribute or the jco.server.gwserv / jco.client.gwserv property). There’s no need to add the whole mapping list.

For example, to set the following, jcoGwService=sapgw00, you simply add the following line:

sapgw00 3300/tcp

Port 3300 is predefined by SAP, so if you need to validate other port numbers based on your SAP instance number, you can check the complete list of service-to-port mappings, which can be found here.

Namespace and Syntax

XML namespace:

xmlns:sap= http://www.mulesoft.org/schema/mule/sap

Connector Syntax:

<sap:connector name="SapConnector" jcoClient="100" jcoUser="User"
     jcoPasswd="Password" jcoLang="en" jcoAsHost="host" jcoSysnr="00"
     jcoTrace="true" jcoPoolCapacity="3" jcoPeakLimit="10"/>

Endpoint Syntax

Inbound Endpoint

<sap:inbound-endpoint name="idocServer" type="idoc" rfcType="trfc"
     jcoConnectionCount="5" jcoGwHost="yoursapgw.company.com" jcoProgramId="send_idoc"
     jcoGwService="sapgw00" exchange-pattern="one-way"/>

Outbound endpoint

<sap:outbound-endpoint name="idocSender" type="idoc" connector-ref="SapConnector"
                       exchange-pattern="request-response"/>

The Connector

The sap:connector element allows the configuration of JCo connection parameters that can then be shared among sap:inbound-endpoints and sap:outbound-endpoints in the same application.

Configurable Attributes

Attribute Description Default Value Since Version

Attribute	Description	Default Value	Since Version
name	The reference name of the connector used internally by Mule configuration.		1.0
jcoClient	The SAP client. This is usually a number (For example: 100).		1.0
jcoUser	The logon user name for password-based authentication		1.0
jcoPasswd	The logon password used for password- based authentication		1.0
jcoLang	The language to use for logon dialogs. If not defined, the default user language is used.	en	1.0
jcoAsHost	The SAP application server host (either the IP address or server name can be specified).		1.0
jcoSysnr	The SAP system number		1.0
jcoTrace	Enable/disable RFC trace	false	1.0
jcoTraceToLog	If jcoTraceToLog is true then JCo trace will be redirected to Mule ESB log files. If this attribute is set, it will override the java startup environment property (-Djco.trace_path=<PATH>). Because of JCo libraries limitations, this attribute has to be configured at class loader level, so if configured it will be applied to all SAP connections at class loader level. jcoTrace should be enabled for this parameter to work.	false	1.0
jcoPoolCapacity	The maximum number of idle connections kept open by the destination. No connection pooling takes place when the value is 0.	5	1.0
jcoPeakLimit	The maximum number of active connections that can be created for a destination simultaneously	10	1.0
jcoClientExtendedProperties-ref	A reference to `java.util.Map` containing additional JCo connection parameters. Additional information and a complete list of parameters can be found here		1.0
disableFunctionTemplateCache	A boolean representing whether function templates should be cached or not. Disabling the cache is only recommended for really special cases (for example during development) as disabling will affect performance. Each function (BAPI) call will require two hits to SAP server.	false	2.1.0

name

The reference name of the connector used internally by Mule configuration.

1.0

jcoClient

The SAP client. This is usually a number (For example: 100).

1.0

jcoUser

The logon user name for password-based authentication

1.0

jcoPasswd

The logon password used for password- based authentication

1.0

jcoLang

The language to use for logon dialogs. If not defined, the default user language is used.

1.0

jcoAsHost

The SAP application server host (either the IP address or server name can be specified).

1.0

jcoSysnr

The SAP system number

1.0

jcoTrace

Enable/disable RFC trace

false

1.0

jcoTraceToLog

If jcoTraceToLog is true then JCo trace will be redirected to Mule ESB log files. If this attribute is set, it will override the java startup environment property (-Djco.trace_path=<PATH>). Because of JCo libraries limitations, this attribute has to be configured at class loader level, so if configured it will be applied to all SAP connections at class loader level. jcoTrace should be enabled for this parameter to work.

false

1.0

jcoPoolCapacity

The maximum number of idle connections kept open by the destination. No connection pooling takes place when the value is 0.

1.0

jcoPeakLimit

The maximum number of active connections that can be created for a destination simultaneously

1.0

jcoClientExtendedProperties-ref

A reference to java.util.Map containing additional JCo connection parameters. Additional information and a complete list of parameters can be found here

1.0

disableFunctionTemplateCache

A boolean representing whether function templates should be cached or not. Disabling the cache is only recommended for really special cases (for example during development) as disabling will affect performance. Each function (BAPI) call will require two hits to SAP server.

false

2.1.0

Configuration Example

<sap:connector name="SapConnector" jcoClient="100" jcoUser="User" jcoPasswd="Password"
    jcoLang="en" jcoAsHost="host" jcoSysnr="00" jcoTrace="true" jcoPoolCapacity="3"
    jcoPeakLimit="10"/>

Disabling JCo Pool

If you want to disable JCo Pool, then just do not provide values for the attributes jcoPoolCapacity and jcoPeakLimit. Also providing a value of zero for the attribute jcoPoolCapacity will disable pooling.

SAP Solution Manager

The MuleSoft Enterprise Java Connector for SAP is SAP Solution Manager ready.

To configure it, you create a child element sap:sld-config inside sap:connector so that Mule registers with the System Landscape Directory (SLD) every time the application starts. This child element supports the following attributes:

Attribute	Description	Default Value	Since Version
url	The URL (including host and port) where your SLD is listening. Usually the URL will conform to a pattern like this: http://sld-host.company.com:80/sdl/ds		1.0
user	A user who has privileges to update information in the SLD		1.0
password	The password for the user who has privileges to update the SLD settings		1.0
computerName	The name of the machine on which your application.	The host name (without the domain), as obtained from the OS.	1.0
localSystemName	The descriptive name for your application.		1.0

Attribute

Description

Default Value

Since Version

url

The URL (including host and port) where your SLD is listening. Usually the URL will conform to a pattern like this:

http://sld-host.company.com:80/sdl/ds

1.0

user

A user who has privileges to update information in the SLD

1.0

password

The password for the user who has privileges to update the SLD settings

1.0

computerName

The name of the machine on which your application.

The host name (without the domain), as obtained from the OS.

1.0

localSystemName

The descriptive name for your application.

1.0

Example

<sap:connector name="SapConnector" jcoClient="100" jcoUser="User" jcoPasswd="Password"
               jcoLang="en" jcoAsHost="host" jcoSysnr="00" jcoTrace="true"
               jcoPoolCapacity="3" jcoPeakLimit="10">
    <sap:sld-config url="http://sapsld.mulesoft.com:80/sld/ds" user="slduser" password="secret" computerName="mule01" localSystemName="Mule ESB Enterprise Connector"/>
</sap:connector>

If you have multiple SAP connectors in the same Mule application or even on the same Mule server, then there is no reason to configure a different SLD for every one of them.

Unless you need to register with different SLD servers, you can configure a single sap:sld-config for only one sap:connector, and that SLD will serve for all SAP connectors running on the same host.

Endpoints

The MuleSoft Enterprise Java Connector for SAP supports both Inbound Endpoint and Outbound Endpoint endpoints.

Inbound Endpoint: Receives IDocs and BAPI calls over RFC.
- Receiving IDocs
- Receiving BAPI calls
Outbound Endpoint: Sends IDocs and executes BAPIs over RFC.

Endpoint Address

To support for dynamic endpoints, the SAP Transport supports a URI-style address, for which the general format is:

address="sap://jcoUser:jcoPasswd@jcoAsHost?attr1=value1&attr2=value2& … &attrN=valueN"

These attributes can be:

The same attributes supported in the connector or endpoint element (for example jcoClient, jcoSysnr, etc.)
Specific SAP Connection Properties (for example jco.client.r3name, jco.client.type, etc.)

Whenever attributes that are not specified, default values are used.

You can use Mule expressions inside the address attribute, just as you do for other Mule ESB transports.

Example of an Inbound Endpoint Address

<sap:inbound-endpoint
   address="sap://TEST_USER:secret@localhost?type=function&amp;rfcType=trfc&amp;jcoClient=100&amp;jcoSysnr=00&amp;jcoPoolCapacity=10&amp;jcoPeakLimit=10&amp;jcoGwHost=localhost&amp;jcoGwService=gw-service&amp;jcoProgramId=program_id&amp;jcoConnectionCount=2"/>

Example of an Outbound Endpoint Address

<sap:outbound-endpoint
   address="sap://TEST_USER:secret@localhost?type=function&amp;rfcType=trfc&amp;jcoClient=100&amp;jcoSysnr=00&amp;jcoPoolCapacity=10&amp;jcoPeakLimit=10"/>

Important

You must “escape” the ampersand sign ('&') in the address attribute, replacing it with '& amp; '.

Prioritizing Connection Properties

Properties for SAP JCo connections (inbound and outbound) can be configured in numerous places. The following list details the priorities accorded to values specified in different places, with the highest priority level listed first.

Attributes at <sap:inbound-endpoint/> and <sap:outbound-endpoint/> level (For example jcoClient, jcoUser, jcoPasswd, jcoSysnr, jcoGwHost, jcoProgramId, …)
Properties in the address attribute at <sap:inbound-endpoint/> and <sap:outbound-endpoint/> level
Properties inside the Map configured in the jcoClientExtendedProperties-ref and/or jcoServerExtendedProperties-ref attributes at at <sap:inbound-endpoint/> and <sap:outbound-endpoint/> level
Attributes configured at <sap:connector/> level (For example jcoClient, jcoUser, jcoPasswd, jcoSysnr, …)
Properties inside the Map configured in the jcoClientExtendedProperties-ref at <sap:connector/> level
Default values

XML Definition

This definition is the XML representation of a function (JCOFunction) or IDoc (IDocDocument / IDocDocumentList).

In short, these are the XML documents you will be receiving from and sending to SAP.

The SAP transport includes Transformers that will convert the XML documents exchanged between the endpoints and SAP into corresponding SAP objects that the endpoints can handle.

The complete documentation for the different XML documents can be found here:

JCo Function
- Version 1
- Version 2
IDoc

Inbound Endpoint

The SAP inbound endpoint will act as RFC server or IDoc server. The JCo server needs to register against the SAP instance, and for this reason it requires both client and server configuration attributes.

Attribute Description Default Value Since Version

Attribute	Description	Default Value	Since Version
name	The reference name of the endpoint used internally by Mule configuration.		1.0
exchange-pattern	The available options are request-response and one-way.		1.0
address	The standard way to provide endpoint properties. For more information check: Endpoint Address.		1.0
type	The type of SAP object this endpoint will process (i.e., function, idoc)	function	1.0
rfcType	The type of RFC the endpoint used to receive a function or IDoc. The available options are srfc (which is sync with no TID handler), trfc and qrfc (both of which are async, with a TID handler).	srfc	1.0
functionName	If the type is function then this is the name of the BAPI function that will be handled. If no value is provided, then a generic handler is configured to receive all calls.		1.0
jcoClient	The SAP client. This is usually a number (For example: 100)		1.0
jcoUser	The logon user for password-based authentication.		1.0
jcoPasswd	The logon password associated with the logon user for password based authentication.		1.0
jcoLang	The logon language., If not defined, the default user language is used.	en	1.0
jcoAsHost	The SAP application server host. (Use either the IP address or server name).		1.0
jcoSysnr	The SAP system number.		1.0
jcoPoolCapacity	The maximum number of idle connections kept open by the destination. No connection pooling takes place when the value is 0.	5	1.0
jcoPeakLimit	The maximum number of simultaneously active connections that can be created for a destination.	10	1.0
jcoClientExtendedProperties-ref	A reference to `java.util.Map`, which contains additional JCo connection parameters for the client connection.		1.0
jcoGwHost	The gateway host on which the server should be registered.		1.0
jcoGwService	The gateway service, i.e. the port on which registration is performed.		1.0
jcoProgramId	The program ID with which the registration is performed.		1.0
jcoConnectionCount	The number of connections that should be registered at the gateway.	2	1.0
jcoClientExtendedProperties-ref	A Reference to `java.util.Map`, which contains additional JCo connection parameters. Additional information and a complete list of parameters can be found here.		1.0

name

The reference name of the endpoint used internally by Mule configuration.

1.0

exchange-pattern

The available options are request-response and one-way.

1.0

address

The standard way to provide endpoint properties. For more information check: Endpoint Address.

1.0

type

The type of SAP object this endpoint will process (i.e., function, idoc)

function

1.0

rfcType

The type of RFC the endpoint used to receive a function or IDoc. The available options are srfc (which is sync with no TID handler), trfc and qrfc (both of which are async, with a TID handler).

srfc

1.0

functionName

If the type is function then this is the name of the BAPI function that will be handled. If no value is provided, then a generic handler is configured to receive all calls.

1.0

jcoClient

The SAP client. This is usually a number (For example: 100)

1.0

jcoUser

The logon user for password-based authentication.

1.0

jcoPasswd

The logon password associated with the logon user for password based authentication.

1.0

jcoLang

The logon language., If not defined, the default user language is used.

1.0

jcoAsHost

The SAP application server host. (Use either the IP address or server name).

1.0

jcoSysnr

The SAP system number.

1.0

jcoPoolCapacity

The maximum number of idle connections kept open by the destination. No connection pooling takes place when the value is 0.

1.0

jcoPeakLimit

The maximum number of simultaneously active connections that can be created for a destination.

1.0

jcoClientExtendedProperties-ref

A reference to java.util.Map, which contains additional JCo connection parameters for the client connection.

1.0

jcoGwHost

The gateway host on which the server should be registered.

1.0

jcoGwService

The gateway service, i.e. the port on which registration is performed.

1.0

jcoProgramId

The program ID with which the registration is performed.

1.0

jcoConnectionCount

The number of connections that should be registered at the gateway.

1.0

jcoClientExtendedProperties-ref

A Reference to java.util.Map, which contains additional JCo connection parameters. Additional information and a complete list of parameters can be found here.

1.0

Example

<sap:inbound-endpoint exchange-pattern="request-response" type="function" rfcType="srfc"
    jcoGwHost="gateway-host" jcoGwService="gateway-service" jcoProgramId="program_id"
    jcoConnectionCount="2" functionName="BAPI_FUNCTION_NAME" jcoServerExtendedProperties-ref="mapWithServerProperties"/>

Output Mule Message

The inbound-endpoint will generate a Mule Message with the following contents:

Payload: A org.mule.transport.sap.SapObject instance. This is a Java POJO whose two main properties are:
- type: SapType.FUNCTION or SapType.IDOC, depending on whether a BAPI call or an IDoc is being received.
- value: The type depends on the specific JCo Object: com.sap.conn.idoc.IDocDocument or com.sap.conn.idoc.IDocDocumentList for IDocs and com.sap.conn.jco.JCoFunction for BAPI calls.

The payload can be transformed into an XML Definition with the following transformer: <sap:object-to-xml/>

Receiving IDocs

To configure a IDoc Server, you need to complete the following steps:

Set the type parameter to idoc.
Define the rfcType parameter as trfc or qrfc (IDocs are asychronous by definition, so they cannot be received over srfc).
Configuring the TID Handler. (The default is an in-memory TID handler).
Specify the following required attributes: jcoGwHost, jcoGwService, jcoProgramId.
Specify required connection attributes, as necessary, for the endpoint or the connector. This might include, for example, jcoClient, jcoUser, jcoPasswd, jcoAsHost, jcoSysnr.

A Sample IDoc Server Configuration

<mule>
    ...
    <sap:connector name="SapConnector" jcoClient="100" jcoUser="mule_user" jcoPasswd="secret" jcoLang="en"
        jcoAsHost="sap-as.mulesoft.com" jcoSysnr="00" jcoTrace="true" jcoPoolCapacity = "3" jcoPeakLimit="10"
        jcoClientExtendedProperties-ref="sapProperties"/>
    ...
    <flow name="sapExample">
        <sap:inbound-endpoint name="sapInbound" exchange-pattern="request-response" type="idoc"
            rfcType="trfc" jcoGwHost="sapgw.mulesoft.com" jcoProgramId="idoc_send" jcoGwService="sapgw00"
            jcoConnectionCount="2" jcoClientExtendedProperties-ref="sapProperties">

                <sap:default-in-memory-tid-store/>
        </sap:inbound-endpoint>
        ...
    </flow>
</mule>

Receiving BAPI calls

To configure a BAPI RFC Server you must complete the following steps:

Set the type parameter to function.
Define the rfcType parameter to trfc, qrfc or srfc. If rfcType is not specified, srfc is used by default).
If rfcType is trfc or qrfc, then you may also need to Configuring the TID Handler
Specify the following required attributes: jcoGwHost, jcoGwService, jcoProgramId
Specify the required connection attributes, as necessary, for the endpoint or the connector. This might include, for example, jcoClient, jcoUser, jcoPasswd, jcoAsHost, jcoSysnr.

Returning to SAP

After the flow executes and if the SAP inbound endpoint is request-response, then Mule will return values to the calling SAP instance. Return values can be represented with the XML representation of the JCo Function.
There are three possible scenarios:

Normal Execution: Just populate values in the export, changing or tables sections.
Exception: Populate an exception in the exceptions section. This will throw an AbapException that will be treated by SAP as an application error.
Flow Exception: Any exception thrown by the flow will be treated in SAP as a system failure (SYSTEM_FAILURE)

A Sample BAPI RFC Server Configuration

<mule>
    ...
    <sap:connector name="SapConnector" jcoClient="100" jcoUser="mule_test" jcoPasswd="secret" jcoLang="en" jcoAsHost="sapas.mulesoft.com"
        jcoSysnr="00" jcoTrace="true" jcoPoolCapacity = "3" jcoPeakLimit="10" jcoClientExtendedProperties-ref="sapProperties"/>
    ...
    <flow name="sapExample">
        <sap:inbound-endpoint name="sapInbound" exchange-pattern="request-response" type="function" rfcType="trfc" jcoGwHost="sapas.mulesoft.com"
            jcoProgramId="rfc_send" jcoGwService="sapgw00" jcoConnectionCount="2"/>
        ...
    </flow>
</mule>

Configuring the TID Handler

The TID (Transaction ID) handler , an important component for tRFC and qRFC, ensures that Mule ESB does not process the same transaction twice.

The SAP Transport allows you to configure different TID stores:

In Memory TID Store: This default TID store facilitates the sharing of TIDs within the same Mule ESB instance. If the rfcType is tRFC or qRFC, and no TID store is configured, then this default store is used.
Mule Object Store TID Store: This wrapper uses existing Mule ESB object stores to store and share TIDs. If you need multiple Mule ESB server instances, you should configure a JDBC Object Store or a Cluster enabled Object Store so that you can share TIDs among the instances.

Important

If the rfcType is configured to srfc, or it is not provided (thus defaulting to srfc), then no TID handler is configured. Furthermore, if a TID handler has been configured in the XML file, it will be ignored.

Example of a Default In-memory TID Store

To configure an In-memory TID Store successfully, you must understand the following:

The In-memory TID Store won’t work as expected if you have multiple Mule ESB instances that share the same program id. (This is because the SAP gateway load-balances across all registered SAP servers that share the same program id).
The rfcType in the <sap:inbound-endpoint …/> should be trfc or qrfc
Configuring the child element <sap:default-in-memory-tid-store/> is optional, since the in-memory handler is the option by default.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xmlns:sap="http://www.mulesoft.org/schema/mule/sap"
    xsi:schemaLocation="
        http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
        http://www.mulesoft.org/schema/mule/sap http://www.mulesoft.org/schema/mule/sap/current/mule-sap.xsd
        http://www.mulesoft.org/schema/mule/xml http://www.mulesoft.org/schema/mule/xml/current/mule-xml.xsd
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd">

    <!-- Configuration for both SAP & the TID Store -->
    <spring:bean id="sapProperties" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"
        <spring:property name="ignoreUnresolvablePlaceholders" value="true" />
        <spring:property name="location" value="classpath:sap.properties"/>
    </spring:bean>

    <!-- SAP Connector -->
    <sap:connector name="SapConnector" jcoClient="${sap.jcoClient}"
        jcoUser="${sap.jcoUser}" jcoPasswd="${sap.jcoPasswd}" jcoLang="${sap.jcoLang}" jcoAsHost="${sap.jcoAsHost}"
        jcoSysnr="${sap.jcoSysnr}" jcoTrace="${sap.jcoTrace}" jcoPoolCapacity="${sap.jcoPoolCapacity}" jcoPeakLimit="${sap.jcoPeakLimit}"/>


    <flow name="idocServerFlow">
        <sap:inbound-endpoint name="idocServer" exchange-pattern="request-response" type="idoc" rfcType="trfc" jcoGwHost="${sap.jcoGwHost}"
                              jcoProgramId="${sap.jcoProgramId}" jcoGwService="${sap.jcoGwService}" jcoConnectionCount="${sap.jcoConnectionCount}">
            <sap:default-in-memory-tid-store/>
        </sap:inbound-endpoint>

            ...
    </flow>
</mule>

A Sample JDBC-based Mule Object Store TID Store

To configure the Mule Object Store TID Store, complete the following steps:

Configure the rfcType in the <sap:inbound-endpoint …/> component as trfc or qrfc
Configure the child element <sap:mule-object-store-tid-store>
Configure a DataSource bean with Database Connection details.
Configure a JDBC connector.

The child element of <sap:mule-object-store-tid-store> can be any of the supported Mule Object Stores.

This example illustrates how to configure a MySQL-based JDBC object store.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xmlns:sap="http://www.mulesoft.org/schema/mule/sap"
      xmlns:jdbc="http://www.mulesoft.org/schema/mule/jdbc"
    xsi:schemaLocation="
        http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
        http://www.mulesoft.org/schema/mule/sap http://www.mulesoft.org/schema/mule/sap/current/mule-sap.xsd
        http://www.mulesoft.org/schema/mule/jdbc http://www.mulesoft.org/schema/mule/jdbc/current/mule-jdbc.xsd
        http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd">

    <!-- Configuration for both SAP & TID Store -->
    <spring:bean id="sapProperties" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"
        <spring:property name="ignoreUnresolvablePlaceholders" value="true" />
        <spring:property name="location" value="classpath:sap.properties"/>
    </spring:bean>

    <spring:bean id="jdbcProperties" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
        <spring:property name="location" value="classpath:jdbc.properties"/>
    </spring:bean>

    <!-- TID Store configuration -->
    <spring:bean id="jdbcDataSource"
        class="org.enhydra.jdbc.standard.StandardDataSource"
        destroy-method="shutdown">
        <spring:property name="driverName" value="${database.driver}"/>
        <spring:property name="url" value="${database.connection}"/>
    </spring:bean>

    <jdbc:connector name="jdbcConnector" dataSource-ref="jdbcDataSource" queryTimeout="${database.query_timeout}">
        <jdbc:query key="insertTID" value="insert into saptids (tid, context) values (?, ?)"/>
        <jdbc:query key="selectTID" value="select tid, context from saptids where tid=?"/>
        <jdbc:query key="deleteTID" value="delete from saptids where tid=?"/>
    </jdbc:connector>

    <!-- SAP Connector -->
    <sap:connector name="SapConnector" jcoClient="${sap.jcoClient}"
        jcoUser="${sap.jcoUser}" jcoPasswd="${sap.jcoPasswd}" jcoLang="${sap.jcoLang}" jcoAsHost="${sap.jcoAsHost}"
        jcoSysnr="${sap.jcoSysnr}" jcoTrace="${sap.jcoTrace}" jcoPoolCapacity="${sap.jcoPoolCapacity}" jcoPeakLimit="${sap.jcoPeakLimit}"/>

    <flow name="idocServerFlow">
        <sap:inbound-endpoint name="idocServer" exchange-pattern="request-response" type="idoc" rfcType="trfc" jcoGwHost="${sap.jcoGwHost}"
                              jcoProgramId="${sap.jcoProgramId}" jcoGwService="${sap.jcoGwService}" jcoConnectionCount="${sap.jcoConnectionCount}">
            <sap:mule-object-store-tid-store>
                <jdbc:object-store name="jdbcObjectStore" jdbcConnector-ref="jdbcConnector"
                    insertQueryKey="insertTID"
                    selectQueryKey="selectTID"
                    deleteQueryKey="deleteTID"/>
            </sap:mule-object-store-tid-store>
        </sap:inbound-endpoint>
        ...
    </flow>
</mule>

Make sure to note the following points:

Specific confguration attributes are store in two properties files: sap.properties and jdbc.properties.
To configure more than one PropertyPlaceholder, the first one must have the property ignoreUnresolvablePlaceholders set to true. (i.e., <spring:property name="ignoreUnresolvablePlaceholders" value="true" />)

A Sample Database Creation Script for the JDBC Object Store

-- MySQL Script
CREATE DATABASE saptid_db;

GRANT ALL ON saptid_db.* TO 'sap'@'localhost' IDENTIFIED BY 'secret';
GRANT ALL ON saptid_db.* TO 'sap'@'%' IDENTIFIED BY 'secret';

USE saptid_db;

CREATE TABLE saptids
(
    tid VARCHAR(512) PRIMARY KEY,
    context TEXT
);

Outbound Endpoint

The SAP outbound endpoint will execute functions (BAPIs) or send IDocs.

Attribute Description Default Value Since Version

Attribute	Description	Default Value	Since Version
name	The reference name of the endpoint used internally by mule configuration.		1.0
exchange-pattern	The available options are `request-response` and `one-way`.		1.0
address	The standard way to specify endpoint properties. For more information check: Endpoint Address.		1.0
type	The type of SAP object this endpoint will be processing (function or idoc and since 2.1.0 function-metadata)	function	1.0
rfcType	Type of RFC the endpoint will use to execute a function or send and IDoc. Allowed values are srfc, trfc and qrfc	srfc	1.0
queueName	If the RFC type is qrfc, then this is the name of the queue.		1.0
functionName	When the type is function, this BAPI function is executed. If the type is function-metadata then you need to provide the name of the BAPI that you want to retrieve its metadata. This attribute accepts Mule Expressions.		1.0
evaluateFunctionResponse	When the type is function, a true flag indicates that the SAP transport should evaluate the function response and throw and exception when an error occurs in SAP. When this flag is set to false, the SAP transport does not throw an exception when an error occurs, and the user is responsible of parsing the function response.	false	1.0
definitionFile	The path to the template definition file of either the function to be executed or the IDoc to be sent.		1.0
idocVersion	When the type is idoc, this version is used when sending the IDoc. Values for the IDoc version correspond to IDOC_VERSION_xxxx constants in com.sap.conn.idoc.IDocFactory	0 (IDOC_VERSION_DEFAULT).	1.0
jcoClient	The SAP client. This is usually a number (For example: 100).		1.0
jcoUser	The logon user for password-based authentication. Since version 2.1.0 this attribute accepts Mule Expressions.		1.0
jcoPasswd	The password associated with the logon user for password-based authentication. Since version 2.1.0 this attribute accepts Mule Expressions.		1.0
jcoLang	The language used by the logon dialogs. When not defined, the default user language is used.	en	1.0
jcoAsHost	The SAP application server host (IP or server name).		1.0
jcoSysnr	The SAP system number.		1.0
jcoPoolCapacity	The maximum number of idle connections kept open by the destination. No connection pooling takes place when the value is 0.	5	1.0
jcoPeakLimit	The maximum number of active connections that can be created for a destination simultaneously	10	1.0
jcoClientExtendedProperties-ref	A reference to `java.util.Map` containing additional JCo connection parameters. Additional information and a complete list of parameters can be found here.		1.0
bapiTransaction	When set to true , either BAPI_TRANSACTION_COMMIT or BAPI_TRANSACTION_ROLLBACK is called depending if there were exceptions or not. This attribute can be used depending the existence of a transaction. If there is no transaction configured, then BAPI_TRANSACTION_COMMIT is called after executing the function. If there is a transaction, then BAPI_TRANSACTION_COMMIT is called at the end of it.	false	2.1.0
xmlVersion	This attribute supports the value 1 or 2 and defines the version of the XML output generated when type is function-metadata	1	2.1.0

name

The reference name of the endpoint used internally by mule configuration.

1.0

exchange-pattern

The available options are request-response and one-way.

1.0

address

The standard way to specify endpoint properties. For more information check: Endpoint Address.

1.0

type

The type of SAP object this endpoint will be processing (function or idoc and since 2.1.0 function-metadata)

function

1.0

rfcType

Type of RFC the endpoint will use to execute a function or send and IDoc. Allowed values are srfc, trfc and qrfc

srfc

1.0

queueName

If the RFC type is qrfc, then this is the name of the queue.

1.0

functionName

When the type is function, this BAPI function is executed. If the type is function-metadata then you need to provide the name of the BAPI that you want to retrieve its metadata. This attribute accepts Mule Expressions.

1.0

evaluateFunctionResponse

When the type is function, a true flag indicates that the SAP transport should evaluate the function response and throw and exception when an error occurs in SAP. When this flag is set to false, the SAP transport does not throw an exception when an error occurs, and the user is responsible of parsing the function response.

false

1.0

definitionFile

The path to the template definition file of either the function to be executed or the IDoc to be sent.

1.0

idocVersion

When the type is idoc, this version is used when sending the IDoc. Values for the IDoc version correspond to IDOC_VERSION_xxxx constants in com.sap.conn.idoc.IDocFactory

0 (IDOC_VERSION_DEFAULT).

1.0

jcoClient

The SAP client. This is usually a number (For example: 100).

1.0

jcoUser

The logon user for password-based authentication. Since version 2.1.0 this attribute accepts Mule Expressions.

1.0

jcoPasswd

The password associated with the logon user for password-based authentication. Since version 2.1.0 this attribute accepts Mule Expressions.

1.0

jcoLang

The language used by the logon dialogs. When not defined, the default user language is used.

1.0

jcoAsHost

The SAP application server host (IP or server name).

1.0

jcoSysnr

The SAP system number.

1.0

jcoPoolCapacity

The maximum number of idle connections kept open by the destination. No connection pooling takes place when the value is 0.

1.0

jcoPeakLimit

The maximum number of active connections that can be created for a destination simultaneously

1.0

jcoClientExtendedProperties-ref

A reference to java.util.Map containing additional JCo connection parameters. Additional information and a complete list of parameters can be found here.

1.0

bapiTransaction

When set to true , either BAPI_TRANSACTION_COMMIT or BAPI_TRANSACTION_ROLLBACK is called depending if there were exceptions or not. This attribute can be used depending the existence of a transaction. If there is no transaction configured, then BAPI_TRANSACTION_COMMIT is called after executing the function. If there is a transaction, then BAPI_TRANSACTION_COMMIT is called at the end of it.

false

2.1.0

xmlVersion

This attribute supports the value 1 or 2 and defines the version of the XML output generated when type is function-metadata

2.1.0

Multi-user Support

Since SAP Connector version 2.1.0 users can dynamically set connection user and password (This means that both jcoUser and jcoPasswd can be set using a Mule Expression that will be evaluated in runtime). Though this is really useful for use cases where it is important to execute a BAPI under a specific user, it is worth mentioning that there will be a pool of connections to SAP created for each user.
Please size correctly the JCo connection pool and configured java memory based on the amount of users that may be used.

IDoc Versions

Value	Description
0	IDOC_VERSION_DEFAULT
2	IDOC_VERSION_2
3	IDOC_VERSION_3
8	IDOC_VERSION_QUEUED

A Sample SAP Outbound Endpoint Configuration

<sap:outbound-endpoint exchange-pattern="request-response" type="function" rfcType="qrfc"
    queueName="QRFC_QUEUE_NAME" functionName="BAPI_FUNCTION_NAME"
    definitionFile="path/to/definition/file.xml"/>

A Sample SAP Outbound Endpoint Configuration to retrieve the Metadata for a BAPI (since version 2.1.0)

<sap:outbound-endpoint exchange-pattern="request-response" type="function-metadata"  functionName="BAPI_FUNCTION_NAME"/>

Input Mule Messages

The outbound-endpoint expects a Mule Message carrying any of the following payloads:

org.mule.transport.sap.SapObject instance. This is a Java POJO, whose two main properties are:
- type: SapType.FUNCTION (for a BAPI call) or SapType.IDOC (for an IDoc).
- value: The specific JCo Object depends on the payload type: com.sap.conn.idoc.IDocDocument or com.sap.conn.idoc.IDocDocumentList for IDocs and com.sap.conn.jco.JCoFunction for BAPI calls.
Any other Object. You need to provide the XML definition with the attribute definitionFile or embedding it in the XML.

The payload can be transformed from a XML Definition into a SapObject with the following transformers:

<!-- IDocs -->
<sap:xml-to-idoc/>

<!-- BAPI calls -->
<sap:xml-to-function/>

Embedding the XML Definition

As an alternative to providing the SAP object definition in a file (through the definitionFile attribute), the XML definition can be embedded inside the sap:outbound-endpoint element by using the
sap:definition element. As the definition will be an XML fragment, it has to be provided inside a CDATA section.

<sap:outbound-endpoint ...>
    <sap:definition>
        <![CDATA[
        <jco>
          <import>
            <structure name="POHEADER">
              <field name="COMP_CODE">#[payload.value1]</field>
              <field name="DOC_TYPE">#[header:value2]</field>
              <field name="VENDOR">#[bean:value3]</field>
              <field name="PURCH_ORG">#[xpath://path/to/value4]</field>
            </structure>
          </import>
        </jco>
        ]]>
    </sap:definition>
</sap:outbound-endpoint>

Executing Functions

There are different ways to execute a function:

Create an instance of com.sap.conn.jco.JCoFunction and send it as the payload to the SAP outbound-endpoint. In this case, the following attributes will be ignored:type, functionName, definition, definitionFile. You can create the JCoFunction object in a Java component or Script for example.
Generate the XML definition for the JCoFunction and send it as the payload (i.e., in one of these formats: InputStream, byte[], or String) to the SAP outbound-endpoint through the <xml-to-function/> transformer. In this case, if the function name is provided in the XML definition, it overrides the value in the attribute functionName. The following attributes are also ignored: type, definition, definitionFile.
Configure definitionFile or embed the XML definition in the SAP outbound-endpoint (If both are configured, then the contents of the definitionFile override the embedded XML definition). The type attribute should be set to function. In this case, if the function name is provided in the XML definition, it overrides the value in the attribute functionName. The XML definition file may contain Mule Expressions that can be substituted at runtime with values present in the Mule Event (payload, headers, global properties, beans, etc.)

Invocation of a function results in a JCoFunction object. The Mule SAP outbound-endpoint wraps this object inside org.mule.transport.sap.SapObject. You can access the response JCoFunction object by invoking the getValue method.

You can also use the <object-to-xml/> transformer to get the XML representation of the JCoFunction.

Examples

XML input and XML output

Example notes:

Input is received as an XML document that uses the tag <jco name="BAPI_NAME"> to specify the BAPI to be called.
The function output is transformed into a XML document.
If the execution of the BAPI by SAP produces an error, an exception is raised from the outbound endpoint (because evaluateFunctionResponse is true).

<mule>
    ...
    <sap:connector name="SapConnector" jcoClient="100" jcoUser="mule_test" jcoPasswd="secret" jcoLang="en" jcoAsHost="sapas.mulesoft.com"
        jcoSysnr="00" jcoTrace="true" jcoPoolCapacity = "3" jcoPeakLimit="10" jcoClientExtendedProperties-ref="sapProperties"/>
    ...
    <flow name="sapExample">
        ...
        <xml-to-function/>
        <sap:outbound-endpoint name="sapOutbound" exchange-pattern="request-response" type="function" rfcType="srfc" evaluateFunctionResponse="true"/>
        <object-to-xml/>
        ...
    </flow>
</mule>

A Sample of an Embedded XML Definition using Mule Expressions

Example notes:

The payload is a Java object. (For this example, let’s assume it has a property name is_value1_).
The function output is transformed into a XML document
The name of the BAPI function to be executed is BAPI_PO_CREATE1
Inside the definition, you can see various Mule Expressions

<mule>
    ...
    <sap:connector name="SapConnector" jcoClient="100" jcoUser="mule_test" jcoPasswd="secret" jcoLang="en" jcoAsHost="sapas.mulesoft.com"
        jcoSysnr="00" jcoTrace="true" jcoPoolCapacity = "3" jcoPeakLimit="10" jcoClientExtendedProperties-ref="sapProperties"/>
    ...
    <flow name="sapExample">
        <!-- Load values into Mule Message -->
        ...
        <sap:outbound-endpoint exchange-pattern="request-response" type="function" functionName="BAPI_PO_CREATE1">
            <sap:definition>
                <![CDATA[
                <jco>
                  <import>
                    <structure name="POHEADER">
                      <field name="COMP_CODE">#[payload.value1]</field>
                      <field name="DOC_TYPE">#[message.inboundProperties['value2']]</field>
                      <field name="VENDOR">#[message.payload.value3]</field>
                      <field name="PURCH_ORG">#[xpath('//path/to/value4')]</field>
                    </structure>
                  </import>
                </jco>
                ]]>
            </sap:definition>
        </sap:outbound-endpoint>
        <sap:object-to-xml/>
        ...
        <!-- Process XML result -->
    </flow>
</mule>

Sending IDocs

There are different ways to send an IDoc:

Create an instance of com.sap.conn.idoc.IDocDocument or com.sap.conn.idoc.IDocDocumentList and send it as the payload to the SAP outbound-endpoint. In this case the following attributes will be ignored: type, definition, definitionFile. You can create the IDoc document object in a Java component or Script for example.
Generate the XML definition for the IDoc and send it as the payload (InputStream, byte[] or String) to the SAP outbound-endpoint through the <xml-to-idoc/> transformer. In this case the following attributes will be ignored: type, definition, definitionFile.
Configure definitionFile or embed the XML definition in the SAP outbound-endpoint (If both are configured then the contents of the definitionFile will override the embedded XML definition). The type attribute should be set to idoc. In this case the XML definition file may contain Mule Expressions that can be substituted in runtime with values present in the Mule Event (payload, headers, global properties, beans, etc.)

Reading a file that represents an IDoc (XML Document)

Example notes:

This example polls the directory C:/sap-test/in for IDocs XML documents, then sends them to SAP.
Extended properties are defined in the map sapProperties.
The outbount endpoint is configured with the address attribute.
The transformer <sap:xml-to-idoc /> receives a Stream, then transforms it into a SAP Object that the endpoint can process.

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesoft.org/schema/mule/core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:spring="http://www.springframework.org/schema/beans" xmlns:sap="http://www.mulesoft.org/schema/mule/sap"
    xmlns:file="http://www.mulesoft.org/schema/mule/file"
    xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-current.xsd
       http://www.mulesoft.org/schema/mule/core http://www.mulesoft.org/schema/mule/core/current/mule.xsd
       http://www.mulesoft.org/schema/mule/file http://www.mulesoft.org/schema/mule/file/current/mule-file.xsd
       http://www.mulesoft.org/schema/mule/sap http://www.mulesoft.org/schema/mule/sap/current/mule-sap.xsd">

    <spring:bean name="sapProperties" class="java.util.HashMap">
        <spring:constructor-arg>
            <spring:map>
                <spring:entry key="jco.server.unicode" value="1" />
            </spring:map>
        </spring:constructor-arg>
    </spring:bean>

    <sap:connector name="SapConnector" jcoSysnr="00" jcoPeakLimit="10"
        jcoClientExtendedProperties-ref="sapProperties" />

    <file:connector name="FileConnector" moveToDirectory="C:/sap-test/bk"
        moveToPattern="#[function:datestamp]-#[header:originalFilename]"
        streaming="false" />

    <flow name="sapExample">
        <file:inbound-endpoint address="file://C:/sap-test/in" />
        <sap:xml-to-idoc />
        <sap:outbound-endpoint
            address="sap://mule_user:password@sapas.mulesoft.com:00?lang=en&amp;jcoClient=100&amp;jcoTrace=false&amp;jcoPoolCapacity=100"
            exchange-pattern="request-response" type="idoc"/>
    </flow>
</mule>

Transactions

The SAP transport, which is based on JCo, doesn’t support distributed transactions because JCo doesn’t support XA.

The SAP outbound endpoint supports the child element transaction:

<sap:transaction action="ALWAYS_BEGIN" bapiTransaction="true|false"/>

Important Compatibility Notes

Transaction support in the SAP Connector version 1.x is very limited and only transactions of one function call are allowed.

Starting with the SAP Connector version 2.1.0 the attribute bapiTransaction is no longer present at transaction level (it was moved to the outbound endpoint).

Attribute	Description	Default Value	Since Version
action	The action attribute is part of the Mule ESB transaction standard and can have the following values: NONE, ALWAYS_BEGIN, BEGIN_OR_JOIN, ALWAYS_JOIN and JOIN_IF_POSSIBLE		1.0
bapiTransaction	When set to true , either BAPI_TRANSACTION_COMMIT or BAPI_TRANSACTION_ROLLBACK is called at the end of the transaction, depending on the result of that transaction. Since version 2.1.0 this option has being moved to the outbound-endpoint	false	1.0

Attribute

Description

Default Value

Since Version

action

The action attribute is part of the Mule ESB transaction standard and can have the following values: NONE, ALWAYS_BEGIN, BEGIN_OR_JOIN, ALWAYS_JOIN and JOIN_IF_POSSIBLE

1.0

bapiTransaction

When set to true , either BAPI_TRANSACTION_COMMIT or BAPI_TRANSACTION_ROLLBACK is called at the end of the transaction, depending on the result of that transaction. Since version 2.1.0 this option has being moved to the outbound-endpoint

false

1.0

For more information, consult: Transactions Configuration Reference.

Combining the RFC type (rfc Type) attribute defined in the outbound endpoint with the transaction facilitates different ways for the SAP transport to handle the transaction:

If a transaction is not specified, then all calls (execute function or send IDoc) are stateless.

For examples, please take a look at Outbound Endpoint Transactions.

Transformers

<sap:xml-to-function/>
<sap:xml-to-idoc/>
<sap:object-to-xml/>

MuleSoft Enterprise Java Connector for SAP

Introduction

Installation

Making Jars Available to Your Mule ESB Application

Example: Shipping all dependencies inside your application

SAP Inbound Endpoint Requirements

Namespace and Syntax

XML namespace:

Connector Syntax:

Endpoint Syntax

Inbound Endpoint

Outbound endpoint

The Connector

Configurable Attributes

Configuration Example

SAP Solution Manager

Example

Endpoints

Endpoint Address

Example of an Inbound Endpoint Address

Example of an Outbound Endpoint Address

Prioritizing Connection Properties

XML Definition

Inbound Endpoint

Example

Output Mule Message

Receiving IDocs

A Sample IDoc Server Configuration

Receiving BAPI calls

Returning to SAP

A Sample BAPI RFC Server Configuration

Configuring the TID Handler

Example of a Default In-memory TID Store

A Sample JDBC-based Mule Object Store TID Store

A Sample Database Creation Script for the JDBC Object Store

Outbound Endpoint

Multi-user Support

IDoc Versions

A Sample SAP Outbound Endpoint Configuration

A Sample SAP Outbound Endpoint Configuration to retrieve the Metadata for a BAPI (since version 2.1.0)

Input Mule Messages

Embedding the XML Definition

Executing Functions

Examples

XML input and XML output

A Sample of an Embedded XML Definition using Mule Expressions

Sending IDocs

Reading a file that represents an IDoc (XML Document)

Transactions

Transformers

Troubleshooting