Chapter 127. SAP Component

Abstract

The SAP component is a package consisting of a suite of ten different SAP components. There are remote function call (RFC) components that support the sRFC, tRFC, and qRFC protocols; and there are IDoc components that facilitate communication using messages in IDoc format. The component uses the SAP Java Connector (SAP JCo) library to facilitate bidirectional communication with SAP and the SAP IDoc library to facilitate the transmission of documents in the Intermediate Document (IDoc) format.

127.1. Overview

Dependencies

Maven users need to add the following dependency to their pom.xml file to use this component:

<dependency>
    <groupId>org.fusesource</groupId>
    <artifactId>camel-sap</artifactId>
    <version>x.x.x</version>
<dependency>

Additional platform restrictions for the SAP component

Because the SAP component depends on the third-party JCo 3.0 and IDoc 3.0 libraries, it can only be installed on the platforms that these libraries support. For more details about the platform restrictions, see Red Hat JBoss Fuse Supported Configurations.

SAP JCo and SAP IDoc libraries

A prerequisite for using the SAP component is that the SAP Java Connector (SAP JCo) libraries and the SAP IDoc library are installed into the lib/ directory of the Java runtime. You must make sure that you download the appropriate set of SAP libraries for your target operating system from the SAP Service Marketplace.

The names of the library files vary depending on the target operating system, as shown in Table 127.1, “Required SAP Libraries”.

Table 127.1. Required SAP Libraries
SAP Component	Linux and UNIX	Windows
SAP JCo 3	`sapjco3.jar` `libsapjco3.so`	`sapjco3.jar` `sapjco3.dll`
SAP IDoc	`sapidoc3.jar`	`sapidoc3.jar`

Deploying in a Fuse OSGi Container (non-Fabric)

You can install the SAP JCo libraries and the SAP IDoc library into the JBoss Fuse OSGi container (non-Fabric) as follows:

Download the SAP JCo libraries and the SAP IDoc library from the SAP Service Marketplace (http://service.sap.com/public/connectors), making sure to choose the appropriate version of the libraries for your operating system.
Note
You require version 3.0.11 or greater of the JCo library and version 3.0.10 or greater of the IDoc library. You must have an SAP Service Marketplace Account in order to download and use these libraries.
Copy the sapjco3.jar, libsapjco3.so (or sapjco3.dll on Windows), and sapidoc3.jar library files into the lib/ directory of your JBoss Fuse installation.
Open both the configuration properties file, etc/config.properties, and the custom properties file, etc/custom.properties, in a text editor. In the etc/config.properties file, look for the org.osgi.framework.system.packages.extra property and copy the complete property setting (this setting extends over multiple lines, with a backslash character, \, used to indicate line continuation). Now paste this setting into the etc/custom.properties file.
You can now add the extra packages required to support the SAP libraries. In the etc/custom.properties file, add the required packages to the org.osgi.framework.system.packages.extra setting as shown:
```
org.osgi.framework.system.packages.extra = \  
 ... , \
 com.sap.conn.idoc, \  
 com.sap.conn.idoc.jco, \   
 com.sap.conn.jco, \   
 com.sap.conn.jco.ext, \   
 com.sap.conn.jco.monitor, \  
 com.sap.conn.jco.rt, \   
 com.sap.conn.jco.server
```
Tip
Don't forget to include a comma and a backslash, , \, at the end of each line preceding the new entries, so that the list is properly continued.
You need to restart the container for these changes to take effect.
You need to install the camel-sap feature in the container. In the Karaf console, enter the following command:
```
JBossFuse:karaf@root> features:install camel-sap
```

Deploying in a Fuse Fabric

A prerequisite for using the SAP component is that the SAP Java Connector (SAP JCo) libraries and the SAP IDoc library must be installed into the lib/ directory of the Java runtime: that is, sapjco3.jar, libsapjco3.so (or sapjco3.dll on Windows), and sapidoc3.jar.

In the case of a Fuse Fabric deployment, this requires some special configuration. There is no point in simply installing the SAP libraries in the Java lib directory on a single machine, because Fabric containers need to be deployable anywhere in the network. The correct approach is to define a special profile that is capable of downloading and installing the SAP JCo libraries and the SAP IDoc library on whichever host it is running on.

You can define a profile for the SAP JCo libraries and the SAP IDoc library as follows:

Deploy the JCo libraries and the IDoc library—sapjco3.jar, libsapjco3.so (or sapjco3.dll on Windows), and sapidoc3.jar—to a network accessible location. For example, you could install the libraries in a Web server, so that the JCo libraries and the IDoc library can be downloaded through HTTP URLs, http://mywebserver/sapjco3.jar, http://mywebserver/libsapjco3.so, and http://mywebserver/sapidoc3.jar.
Create a new profile, camel-sap-profile, by entering the following console command:
```
JBossFuse:karaf@root> profile-create camel-sap-profile
```
Edit the agent properties of the camel-sap-profile profile, by entering the following console command:
```
JBossFuse:karaf@root> profile-edit camel-sap-profile
```
The built-in profile editor starts up. Use this built-in text editor to add the following contents to the agent properties:
```
# Profile:my-camel-sap-profile
attribute.parents = feature-camel

# Deploy JCo3 Libs to Container
lib.sapjco3.jar = http://mywebserver/sapjco3.jar
lib.sapjco3.so = http://mywebserver/libsapjco3.so
lib.sapidoc3.jar = http://mywebserver/sapidoc3.jar

# Append JCo3 Packages and IDoc packages to OSGi system property
# in order to expose JCo3 and IDoc classes to OSGi environment
config.org.osgi.framework.system.packages.extra= \
    ... Packages from etc/config.properties file ...\
    com.sap.conn.jco, \
    com.sap.conn.jco.ext, \
    com.sap.conn.jco.monitor, \
    com.sap.conn.jco.rt, \
    com.sap.conn.jco.server, \
    com.sap.conn.idoc, \
    com.sap.conn.idoc.jco
```
Customize the property settings as follows:
lib.sapjco3.jar
Customize the HTTP URL to the actual location of the sapjco3.jar file on your Web server.
lib.sapjco3.so
Customize the HTTP URL to the actual location of the libsapjco3.so file (or sapjco3.dll) on your Web server.
lib.sapidoc3.jar
Customize the HTTP URL to the actual location of the sapidoc3.jar file on your Web server.
config.org.osgi.framework.system.packages.extra
Open the container configuration properties file, etc/config.properties, of your JBoss Fuse installation and look for the org.osgi.framework.system.packages.extra property setting. Copy the list of packages from that setting and paste them into the profile's agent properties, replacing the line:
```
    ... Packages from etc/config.properties file ...\
```
Note
The config.* prefix in config.org.osgi.framework.system.packages.extra indicates to Fabric that you are setting a container configuration property in the profile.
Note
The backslash, \, is the line continuation character (UNIX convention) and must be followed immediately by a newline character.
Type Ctrl-S to save the properties when you are finished.
You can now deploy the camel-sap-profile profile to any Fabric container where you want to run the SAP component. For example, to deploy the camel-sap-profileprofile to the sap-instance container:
```
JBossFuse:karaf@root> container-add-profile sap-instance came-sap-profile
```

Deploying in a JBoss EAP container

To deploy the SAP component in a JBoss EAP container, perform the following steps:

Download the SAP JCo libraries and the SAP IDoc library from the SAP Service Marketplace (http://service.sap.com/public/connectors), making sure to choose the appropriate version of the libraries for your operating system.
Note
You require version 3.0.11 or greater of the JCo library and version 3.0.10 or greater of the IDoc library. You must have an SAP Service Marketplace Account in order to download and use these libraries.
Copy the JCo library files and the IDoc library file into the appropriate subdirectory of your JBoss EAP installation. For example, if your host platform is 64-bit Linux (linux-x86_64), install the library files as follows:
```
cp sapjco3.jar sapidoc3.jar $JBOSS_HOME/modules/system/layers/fuse/com/sap/conn/jco/main/
mkdir -p $JBOSS_HOME/modules/system/layers/fuse/com/sap/conn/jco/main/lib/linux-x86_64
cp libsapjco3.so $JBOSS_HOME/modules/system/layers/fuse/com/sap/conn/jco/main/lib/linux-x86_64/
```
Important
For installing native libraries (such as libsapjco3.so) into the JBoss EAP installation, there is a standardized convention for naming the library subdirectory, which must be followed. In the case of 64-bit Linux, the subdirectory is linux-x86_64. For other platforms, see https://docs.jboss.org/author/display/MODULES/Native+Libraries.
Uncomment the org.switchyard.component.camel.sap module in the SwitchYard subsystem configuration. For example, to enable the SAP component in JBoss EAP standalone mode, edit the $JBOSS_HOME/standalone/configuration/standalone.xml file and look for the following line to uncomment:
```

```

URI format

There are two different kinds of endpoint provided by the SAP component: the Remote Function Call (RFC) endpoints, and the Intermediate Document (IDoc) endpoints.

The URI formats for the RFC endpoints are as follows:

sap-srfc-destination:destinationName:rfcName
sap-trfc-destination:destinationName:rfcName
sap-qrfc-destination:destinationName:queueName:rfcName
sap-srfc-server:serverName:rfcName[?options]
sap-trfc-server:serverName:rfcName[?options]

The URI formats for the IDoc endpoints are as follows:

sap-idoc-destination:destinationName:idocType[:idocTypeExtension[:systemRelease[:applicationRelease]]]
sap-idoclist-destination:destinationName:idocType[:idocTypeExtension[:systemRelease[:applicationRelease]]]
sap-qidoc-destination:destinationName:queueName:idocType[:idocTypeExtension[:systemRelease[:applicationRelease]]]
sap-qidoclist-destination:destinationName:queueName:idocType[:idocTypeExtension[:systemRelease[:applicationRelease]]]
sap-idoclist-server:serverName:idocType[:idocTypeExtension[:systemRelease[:applicationRelease]]][?options]

The URI formats prefixed by sap-endpointKind-destination are used to define destination endpoints (in other words, Camel producer endpoints) and destinationName is the name of a specific outbound connection to an SAP instance. Outbound connections are named and configured at the component level, as described in Section 127.2.2, “Destination Configuration”.

The URI formats prefixed by sap-endpointKind-server are used to define server endpoints (in other words, Camel consumer endpoints) and serverName is the name of a specific inbound connection from an SAP instance. Inbound connections are named and configured at the component level, as described in the Section 127.2.3, “Server Configuration”.

The other components of an RFC endpoint URI are as follows:

rfcName: (Required) In a destination endpoint URI, is the name of the RFC invoked by the endpoint in the connected SAP instance. In a server endpoint URI, is the name of the RFC handled by the endpoint when invoked from the connected SAP instance.
queueName: Specifies the queue this endpoint sends an SAP request to.

The other components of an IDoc endpoint URI are as follows:

idocType: (Required) Specifies the Basic IDoc Type of an IDoc produced by this endpoint.
idocTypeExtension: Specifies the IDoc Type Extension, if any, of an IDoc produced by this endpoint.
systemRelease: Specifies the associated SAP Basis Release, if any, of an IDoc produced by this endpoint.
applicationRelease: Specifes the associated Application Release, if any, of an IDoc produced by this endpoint.
queueName: Specifies the queue this endpoint sends an SAP request to.

Options for RFC destination endpoints

The RFC destination endpoints (sap-srfc-destination, sap-trfc-destination, and sap-qrfc-destination) support the following URI options:

Name	Default	Description
`stateful`	`false`	If `true`, specifies that this endpoint initiates an SAP stateful session
`transacted`	`false`	If `true`, specifies that this endpoint initiates an SAP transaction

Options for RFC server endpoints

The SAP RFC server endpoints (sap-srfc-server and sap-trfc-server) support the following URI options:

Name	Default	Description
`stateful`	`false`	If `true`, specifies that this endpoint initiates an SAP stateful session.
`propagateExceptions`	`false`	(sap-trfc-server endpoint only) If `true`, specifies that this endpoint propagates exceptions back to the caller in SAP, instead of the exchange's exception handler

Options for the IDoc List Server endpoint

The SAP IDoc List Server endpoint (sap-idoclist-server) supports the following URI options:

Name	Default	Description
`stateful`	`false`	If `true`, specifies that this endpoint initiates an SAP stateful session.
`propagateExceptions`	`false`	If `true`, specifies that this endpoint propagates exceptions back to the caller in SAP, instead of the exchange's exception handler

Summary of the RFC and IDoc endpoints

The SAP component package provides the following RFC and IDoc endpoints:

sap-srfc-destination: JBoss Fuse SAP Synchronous Remote Function Call Destination Camel component. This endpoint should be used in cases where Camel routes require synchronous delivery of requests to and responses from an SAP system.
Note
The sRFC protocol used by this component delivers requests and responses to and from an SAP system with best effort. In case of a communication error while sending a request, the completion status of a remote function call in the receiving SAP system remains in doubt.
sap-trfc-destination: JBoss Fuse SAP Transactional Remote Function Call Destination Camel component. This endpoint should be used in cases where requests must be delivered to the receiving SAP system at most once. To accomplish this, the component generates a transaction ID, tid, which accompanies every request sent through the component in a route's exchange. The receiving SAP system records the tid accompanying a request before delivering the request; if the SAP system receives the request again with the same tid it will not deliver the request. Thus if a route encounters a communication error when sending a request through an endpoint of this component, it can retry sending the request within the same exchange knowing it will be delivered and executed only once.
Note
The tRFC protocol used by this component is asynchronous and does not return a response. Thus the endpoints of this component do not return a response message.
Note
This component does not guarantee the order of a series of requests through its endpoints, and the delivery and execution order of these requests may differ on the receiving SAP system due to communication errors and resends of a request. For guaranteed delivery order, please see the JBoss Fuse SAP Queued Remote Function Call Destination Camel component.
sap-qrfc-destination: JBoss Fuse SAP Queued Remote Function Call Destination Camel component. This component extends the capabilities of the JBoss Fuse Transactional Remote Function Call Destination camel component by adding in order delivery guarantees to the delivery of requests through its endpoints. This endpoint should be used in cases where a series of requests depend on each other and must be delivered to the receiving SAP system at most once and in order. The component accomplishes the at most once delivery guarantees using the same mechanisms as the JBoss Fuse SAP Transactional Remote Function Call Destination Camel component. The ordering guarantee is accomplished by serializing the requests in the order they are received by the SAP system to an inbound queue. Inbound queues are processed by the QIN scheduler within SAP. When the inbound queue is activated, the QIN Scheduler will execute the queue requests in order.
Note
The qRFC protocol used by this component is asynchronous and does not return a response. Thus the endpoints of this component do not return a response message.
sap-srfc-server: JBoss Fuse SAP Synchronous Remote Function Call Server Camel component. This component and its endpoints should be used in cases where a Camel route is required to synchronously handle requests from and responses to an SAP system.
sap-trfc-server: JBoss Fuse SAP Transactional Remote Function Call Server Camel component. This endpoint should be used in cases where the sending SAP system requires at most once delivery of its requests to a Camel route. To accomplish this, the sending SAP system generates a transaction ID, tid, which accompanies every request it sends to the component's endpoints. The sending SAP system will first check with the component whether a given tid has been received by it before sending a series of requests associated with the tid. The component will check the list of received tids it maintains, record the sent tid if it is not in that list, and then respond to the sending SAP system, indicating whether or not the tid had already been recorded. The sending SAP system will only then send the series of requests, if the tid has not been previously recorded. This enables a sending SAP system to reliably send a series of requests once to a camel route.
sap-idoc-destination: JBoss Fuse SAP IDoc Destination Camel component. This endpoint should be used in cases where a Camel route is required to send a list of Intermediate Documents (IDocs) to an SAP system.
sap-idoclist-destination: JBoss Fuse SAP IDoc List Destination Camel component. This endpoint should be used in cases where a Camel route is required to send a list of Intermediate documents (IDocs) list to an SAP system.
sap-qidoc-destination: JBoss Fuse SAP Queued IDoc Destination Camel component. This component and its endpoints should be used in cases where a Camel route is required to send a list of Intermediate documents (IDocs) to an SAP system in order.
sap-qidoclist-destination: JBoss Fuse SAP Queued IDoc List Destination Camel component. This component and its endpoints should be used in cases where a camel route is required to send a list of Intermediate documents (IDocs) list to an SAP system in order.
sap-idoclist-server: JBoss Fuse SAP IDoc List Server Camel component. This endpoint should be used in cases where a sending SAP system requires delivery of Intermediate Document lists to a Camel route. This component uses the tRFC protocol to communicate with SAP as described in the `sap-trfc-server-standalone` quick start.

SAP RFC destination endpoint

An RFC destination endpoint supports outbound communication to SAP, which enable these endpoints to make RFC calls out to ABAP function modules in SAP. An RFC destination endpoint is configured to make an RFC call to a specific ABAP function over a specific connection to an SAP instance. An RFC destination is a logical designation for an outbound connection and has a unique name. An RFC destination is specified by a set of connection parameters called destination data.

An RFC destination endpoint will extract an RFC request from the input message of the IN-OUT exchanges it receives and dispatch that request in a function call to SAP. The response from the function call will be returned in the output message of the exchange. Since SAP RFC destination endpoints only support outbound communication, an RFC destination endpoint only supports the creation of producers.

SAP RFC server endpoint

An RFC server endpoint supports inbound communication from SAP, which enables ABAP applications in SAP to make RFC calls into server endpoints. An ABAP application interacts with an RFC server endpoint as if it were a remote function module. An RFC server endpoint is configured to receive an RFC call to a specific RFC function over a specific connection from an SAP instance. An RFC server is a logical designation for an inbound connection and has a unique name. An RFC server is specified by a set of connection parameters called server data.

An RFC server endpoint will handle an incoming RFC request and dispatch it as the input message of an IN-OUT exchange. The output message of the exchange will be returned as the response of the RFC call. Since SAP RFC server endpoints only support inbound communication, an RFC server endpoint only supports the creation of consumers.

SAP IDoc and IDoc list destination endpoints

An IDoc destination endpoint supports outbound communication to SAP, which can then perform further processing on the IDoc message. An IDoc document represents a business transaction, which can easily be exchanged with non-SAP systems. An IDoc destination is specified by a set of connection parameters called destination data.

An IDoc list destination endpoint is similar to an IDoc destination endpoint, except that the messages it handles consist of a list of IDoc documents.

SAP IDoc list server endpoint

An IDoc list server endpoint supports inbound communication from SAP, enabling a Camel route to receive a list of IDoc documents from an SAP system. An IDoc list server is specified by a set of connection parameters called server data.

Meta-data repositories

A meta-data repository is used to store the following kinds of meta-data:

Interface descriptions of function modules: This meta-data is used by the JCo and ABAP runtimes to check RFC calls to ensure the type-safe transfer of data between communication partners before dispatching those calls. A repository is populated with repository data. Repository data is a map of named function templates. A function template contains the meta-data describing all the parameters and their typing information passed to and from a function module and has the unique name of the function module it describes.
IDoc type descriptions: This meta-data is used by the IDoc runtime to ensure that the IDoc documents are correctly formatted before being sent to a communication partner. A basic IDoc type consists of a name, a list of permitted segments, and a description of the hierarchical relationship between the segments. Some additional constraints can be imposed on the segments: a segment can be mandatory or optional; and it is possible to specify a minimum/maximum range for each segment (defining the number of allowed repetitions of that segment).

SAP destination and server endpoints thus require access to a repository, in order to send and receive RFC calls and in order to send and receive IDoc documents. For RFC calls, the meta-data for all function modules invoked and handled by the endpoints must reside within the repository; and for IDoc endpoints, the meta-data for all IDoc types and IDoc type extensions handled by the endpoints must reside within the repository. The location of the repository used by a destination and server endpoint is specified in the destination data and the server data of their respective connections.

In the case of an SAP destination endpoint, the repository it uses typically resides in an SAP system and it defaults to the SAP system it is connected to. This default requires no explicit configuration in the destination data. Furthermore, the meta-data for the remote function call that a destination endpoint makes will already exist in a repository for any existing function module that it calls. The meta-data for calls made by destination endpoints thus require no configuration in the SAP component.

On the other hand, the meta-data for function calls handled by server endpoints do not typically reside in the repository of an SAP system and must instead be provided by a repository residing in the SAP component. The SAP component maintains a map of named meta-data repositories. The name of a repository corresponds to the name of the server to which it provides meta-data.