123.2. Configuration

Abstract

The SAP component maintains three maps to store destination data, server data and repository data. The destination data store and the server data store are configured on a special configuration object, SapConnectionConfiguration, which automatically gets injected into the SAP component (in the context of Blueprint XML configuration or Spring XML configuration files). The repository data store must be configured directly on the relevant SAP component.

123.2.1. Configuration Overview

Overview

The SAP component maintains three maps to store destination data, server data and repository data. The component’s property, destinationDataStore, stores destination data keyed by destination name, the property, serverDataStore, stores server data keyed by server name and the property, repositoryDataStore, stores repository data keyed by repository name. These configurations must be passed to the component during its initialization.

Example

The following example shows how to configure a sample destination data store and a sample server data store in a Blueprint XML file. The sap-configuration bean (of type SapConnectionConfiguration) will automatically be injected into any SAP component that is used in this XML file.
<?xml version="1.0" encoding="UTF-8"?>
<blueprint ... >
    ...
    <!-- Configures the Inbound and Outbound SAP Connections -->
    <bean id="sap-configuration"
        class="org.fusesource.camel.component.sap.SapConnectionConfiguration">
        <property name="destinationDataStore">
            <map>
                <entry key="quickstartDest" value-ref="quickstartDestinationData" />
            </map>
        </property>
        <property name="serverDataStore">
            <map>
                <entry key="quickstartServer" value-ref="quickstartServerData" />
            </map>
        </property>
    </bean>

    <!-- Configures an Outbound SAP Connection -->
    <!-- *** Please enter the connection property values for your environment *** -->
    <bean id="quickstartDestinationData"
        class="org.fusesource.camel.component.sap.model.rfc.impl.DestinationDataImpl">
        <property name="ashost" value="example.com" />
        <property name="sysnr" value="00" />
        <property name="client" value="000" />
        <property name="user" value="username" />
        <property name="passwd" value="passowrd" />
        <property name="lang" value="en" />
    </bean>

    <!-- Configures an Inbound SAP Connection -->
    <!-- *** Please enter the connection property values for your environment ** -->
    <bean id="quickstartServerData"
        class="org.fusesource.camel.component.sap.model.rfc.impl.ServerDataImpl">
        <property name="gwhost" value="example.com" />
        <property name="gwserv" value="3300" />
        <!-- The following property values should not be changed -->
        <property name="progid" value="QUICKSTART" />
        <property name="repositoryDestination" value="quickstartDest" />
        <property name="connectionCount" value="2" />
    </bean>
</blueprint>

123.2.2. Destination Configuration

Overview

The configurations for destinations are maintained in the destinationDataStore property of the SAP component. Each entry in this map configures a distinct outbound connection to an SAP instance. The key for each entry is the name of the outbound connection and is used in the destinationName component of a destination endpoint URI as described in the URI format section.
The value for each entry is a destination data configuration object - org.fusesource.camel.component.sap.model.rfc.impl.DestinationDataImpl - that specifies the configuration of an outbound SAP connection.

Sample destination configuration

The following Blueprint XML code shows how to configure a sample destination with the name, quickstartDest.
<?xml version="1.0" encoding="UTF-8"?>
<blueprint ... >
    ...
    <!-- Configures the Inbound and Outbound SAP Connections -->
    <bean id="sap-configuration"
        class="org.fusesource.camel.component.sap.SapConnectionConfiguration">
        <property name="destinationDataStore">
            <map>
                <entry key="quickstartDest" value-ref="quickstartDestinationData" />
            </map>
        </property>
    </bean>

    <!-- Configures an Outbound SAP Connection -->
    <!-- *** Please enter the connection property values for your environment 
        *** -->
    <bean id="quickstartDestinationData"
        class="org.fusesource.camel.component.sap.model.rfc.impl.DestinationDataImpl">
        <property name="ashost" value="example.com" />
        <property name="sysnr" value="00" />
        <property name="client" value="000" />
        <property name="user" value="username" />
        <property name="passwd" value="password" />
        <property name="lang" value="en" />
    </bean>

</blueprint>
For example, after configuring the destination as shown in the preceding Blueprint XML file, you could invoke the BAPI_FLCUST_GETLIST remote function call on the quickstartDest destination using the following URI:
sap-srfc-destination:quickstartDest:BAPI_FLCUST_GETLIST

Logon and authentication options

Name Default Value Description
client SAP client, mandatory logon parameter
user Logon user, logon parameter for password based authentication
aliasUser Logon user alias, can be used instead of logon user
userId User identity which is used for logon to the ABAP AS. Used by the JCo runtime, if the destination configuration uses SSO/assertion ticket, certificate, current user ,or SNC environment for authentication. The user ID is mandatory, if neither user nor user alias is set. This ID will never be sent to the SAP backend, it will be used by the JCo runtime locally.
passwd Logon password, logon parameter for password-based authentication
lang Logon language, if not defined, the default user language is used
mysapsso2 Use the specified SAP Cookie Version 2 as logon ticket for SSO based authentication
x509cert Use the specified X509 certificate for certificate based authentication
lcheck Postpone the authentication until the first call - 1 (enable). Used in special cases only .
useSapGui Use a visible, hidden, or do not use SAP GUI
codePage Additional logon parameter to define the codepage that will used to convert the logon parameters. Used in special cases only
getsso2 Order a SSO ticket after logon, the obtained ticket is available in the destination attributes
denyInitialPassword If set to 1, using initial passwords will lead to an exception (default is 0).

Connection options

Name Default Value Description
saprouter SAP Router string for connection to systems behind a SAP Router. SAP Router string contains the chain of SAP Routers and its port numbers and has the form: (/H/<host>[/S/<port>])+
sysnr System number of the SAP ABAP application server, mandatory for a direct connection
ashost SAP ABAP application server, mandatory for a direct connection
mshost SAP message server, mandatory property for a load balancing connection
msserv SAP message server port, optional property for a load balancing connection. In order to resolve the service names sapmsXXX a lookup in etc/services is performed by the network layer of the operating system. If using port numbers instead of symbolic service names, no look-ups are performed and no additional entries are needed.
gwhost Allows specifying a concrete gateway, which should be used for establishing the connection to an application server. If not specified the gateway on the application server is used
gwserv Should be set, when using gwhost. Allows specifying the port used on that gateway. If not specified the port of the gateway on the application server is used. In order to resolve the service names sapgwXXX a lookup in etc/services is performed by the network layer of the operating system. If using port numbers instead of symbolic service names, no lookups are performed and no additional entries are needed.
r3name System ID of the SAP system, mandatory property for a load balancing connection.
group Group of SAP application servers, mandatory property for a load balancing connection

Connection pool options

Name Default Value Description
peakLimit 0 Maximum number of active outbound connections that can be created for a destination simultaneously. A value of 0 allows an unlimited number of active connections, otherwise if the value is less than the value of jpoolCapacity, it will be automatically increased to this value. Default setting is the value of poolCapacity, or in case of poolCapacity not being specified as well, the default is 0 (unlimited).
poolCapacity 1 Maximum number of idle outbound connections kept open by the destination. A value of 0 has the effect that there is no connection pooling (default is 1).
expirationTime Time in milliseconds after which a free connection held internally by the destination can be closed
expirationPeriod Period in milliseconds after which the destination checks the released connections for expiration.
maxGetTime Maximum time in milliseconds to wait for a connection, if the maximum allowed number of connections has already been allocated by the application.

Secure network connection options

Name Default Value Description
sncMode Secure network connection (SNC) mode, 0 (off) or 1 (on)
sncPartnername SNC partner, for example: p:CN=R3, O=XYZ-INC, C=EN
sncQop SNC level of security: 1 to 9
sncMyname Own SNC name. Overrides environment settings
sncLibrary Path to library that provides SNC service

Repository options

Name Default Value Description
repositoryDest Specifies which destination should be used as repository.
repositoryUser If a repository destination is not set, and this property is set, it will be used as user for repository calls. This enables you to use a different user for repository look-ups.
repositoryPasswd The password for a repository user. Mandatory, if a repository user should be used.
repositorySnc (Optional) If SNC is used for this destination, it is possible to turn it off for repository connections, if this property is set to 0. Default setting is the value of jco.client.snc_mode. For special cases only.
repositoryRoundtripOptimization
Enable the RFC_METADATA_GET API, which provides repository data in one single round trip.
1
Activates use of RFC_METADATA_GET in ABAP System,
0
Deactivates RFC_METADATA_GET in ABAP System.
If the property is not set, the destination initially does a remote call to check whether RFC_METADATA_GET is available. If it is available, the destination will use it.
Note: If the repository is already initialized (for example because it is used by some other destination) this property does not have any effect. Generally, this property is related to the ABAP System, and should have the same value on all destinations pointing to the same ABAP System. See note 1456826 for backend prerequisites.

Trace configuration options

Name Default Value Description
trace Enable/disable RFC trace (0 or 1)
cpicTrace Enable/disable CPIC trace [0..3]

123.2.3. Server Configuration

Overview

The configurations for servers are maintained in the serverDataStore property of the SAP component. Each entry in this map configures a distinct inbound connection from an SAP instance. The key for each entry is the name of the outbound connection and is used in the serverName component of a server endpoint URI as described in the URI format section.
The value for each entry is a server data configuration object, org.fusesource.camel.component.sap.model.rfc.impl.ServerDataImpl, that defines the configuration of an inbound SAP connection.

Sample server configuration

The following Blueprint XML code shows how to create a sample server configuration with the name, quickstartServer.
<?xml version="1.0" encoding="UTF-8"?>
<blueprint ... >
    ...
    <!-- Configures the Inbound and Outbound SAP Connections -->
    <bean id="sap-configuration"
        class="org.fusesource.camel.component.sap.SapConnectionConfiguration">
        <property name="destinationDataStore">
            <map>
                <entry key="quickstartDest" value-ref="quickstartDestinationData" />
            </map>
        </property>
        <property name="serverDataStore">
            <map>
                <entry key="quickstartServer" value-ref="quickstartServerData" />
            </map>
        </property>
    </bean>

    <!-- Configures an Outbound SAP Connection -->
    <!-- *** Please enter the connection property values for your environment *** -->
    <bean id="quickstartDestinationData"
        class="org.fusesource.camel.component.sap.model.rfc.impl.DestinationDataImpl">
        <property name="ashost" value="example.com" />
        <property name="sysnr" value="00" />
        <property name="client" value="000" />
        <property name="user" value="username" />
        <property name="passwd" value="passowrd" />
        <property name="lang" value="en" />
    </bean>

    <!-- Configures an Inbound SAP Connection -->
    <!-- *** Please enter the connection property values for your environment ** -->
    <bean id="quickstartServerData"
        class="org.fusesource.camel.component.sap.model.rfc.impl.ServerDataImpl">
        <property name="gwhost" value="example.com" />
        <property name="gwserv" value="3300" />
        <!-- The following property values should not be changed -->
        <property name="progid" value="QUICKSTART" />
        <property name="repositoryDestination" value="quickstartDest" />
        <property name="connectionCount" value="2" />
    </bean>
</blueprint>
Notice how this example also configures a destination connection, quickstartDest, which the server uses to retrieve meta-data from a remote SAP instance. This destination is configured in the server data through the repositoryDestination option. If you do not configure this option, you would need to create a local meta-data repository instead (see Section 123.2.4, “Repository Configuration”).
For example, after configuring the destination as shown in the preceding Blueprint XML file, you could handle the BAPI_FLCUST_GETLIST remote function call from an invoking client, using the following URI:
sap-srfc-server:quickstartServer:BAPI_FLCUST_GETLIST

Required options

The required options for the server data configuration object are, as follows:
Name Default Value Description
gwhost Gateway host on which the server connection should be registered.
gwserv Gateway service, which is the port on which a registration can be done. In order to resolve the service names sapgwXXX, a look-up in etc/services is performed by the network layer of the operating system. If using port numbers instead of symbolic service names, no look-ups are performed and no additional entries are needed.
progid The program ID with which the registration is done. Serves as identifier on the gateway and in the destination in the ABAP system.
repositoryDestination Specifies a destination name that the server can use in order to retrieve meta-data from a meta-data repository hosted in a remote SAP server.
connectionCount The number of connections that should be registered at the gateway.

Secure network connection options

The secure network connection options for the server data configuration object are, as follows:
Name Default Value Description
sncMode Secure network connection (SNC) mode, 0 (off) or 1 (on)
sncQop SNC level of security, 1 to 9
sncMyname SNC name of your server. Overrides the default SNC name. Typically something like p:CN=JCoServer, O=ACompany, C=EN.
sncLib Path to library which provides SNC service. If this property is not provided, the value of the jco.middleware.snc_lib property is used instead

Other options

The other options for the server data configuration object are, as follows:
Name Default Value Description
saprouter SAP router string to use for a system protected by a firewall, which can therefore only be reached through a SAProuter, when registering the server at the gateway of that ABAP System. A typical router string is /H/firewall.hostname/H/
maxStartupDelay The maximum time (in seconds) between two start-up attempts in case of failures. The waiting time is doubled from initially 1 second after each start-up failure until either the maximum value is reached or the server could be started successfully.
trace Enable/disable RFC trace (0 or 1)
workerThreadCount The maximum number of threads used by the server connection. If not set, the value for the connectionCount is used as the workerThreadCount. The maximum number of threads can not exceed 99.
workerThreadMinCount The minimum number of threads used by server connection. If not set, the value for connectionCount is used as the workerThreadMinCount.

123.2.4. Repository Configuration

Overview

The configuration for repositories are maintain in the repositoryDataStore property of the SAP Component. Each entry in this map configures a distinct repository. The key for each entry is the name of the repository and this key also corresponds to the name of server to which this repository is attached.
The value of each entry is a repository data configuration object, org.fusesource.camel.component.sap.model.rfc.impl.RepositoryDataImpl, that defines the contents of a meta-data repository. A repository data object is a map of function template configuration objects, org.fuesource.camel.component.sap.model.rfc.impl.FunctionTemplateImpl. Each entry in this map specifies the interface of a function module and the key for each entry is the name of the function module specified.

Repository data example

<?xml version="1.0" encoding="UTF-8"?>
<blueprint ... >
    ...
    <!-- Configures the sap-srfc-server component -->
    <bean id="sap-srfc-server"
        class="org.fusesource.camel.component.sap.SapSynchronousRfcServerComponent">
        <property name="repositoryDataStore">
            <map>
                <entry key="nplServer" value-ref="nplRepositoryData" />
            </map>
        </property>
    </bean>

    <!-- Configures a Meta-Data Repository -->
    <bean id="nplRepositoryData"
        class="org.fusesource.camel.component.sap.model.rfc.impl.RepositoryDataImpl">
        <property name="functionTemplates">
            <map>
                <entry key="BOOK_FLIGHT" value-ref="bookFlightFunctionTemplate" />
            </map>
        </property>
    </bean>
    ...
</blueprint>

Function template properties

The interface of a function module consists of four parameter lists by which data is transferred back and forth to the function module in an RFC call. Each parameter list consists of one or more fields, each of which is a named parameter transferred in an RFC call. The following parameter lists and exception list are supported:
  • The import parameter list contains parameter values that are sent to a function module in an RFC call;
  • The export parameter list contains parameter values that are returned by a function module in an RFC call;
  • The changing parameter list contains parameter values that are sent to and returned by a function module in an RFC call;
  • The table parameter list contains internal table values that are sent to and returned by a function module in an RFC call.
  • The interface of a function module also consists of an exception list of ABAP exceptions that may be raised when the module is invoked in an RFC call.
A function template describes the name and type of parameters in each parameter list of a function interface and the ABAP exceptions thrown by the function. A function template object maintains five property lists of meta-data objects, as described in the following table.
Property Description
importParameterList A list of list field meta-data objects, org.fusesource.camel.component.sap.model.rfc.impl.ListFieldMeataDataImpl. Specifies the parameters that are sent in an RFC call to a function module.
changingParameterList A list of list field meta-data objects, org.fusesource.camel.component.sap.model.rfc.impl.ListFieldMeataDataImpl. Specifies the parameters that sent and returned in an RFC call to and from a function module.
exportParameterList A list of list field meta-data objects, org.fusesource.camel.component.sap.model.rfc.impl.ListFieldMeataDataImpl. Specifies the parameters that are returned in an RFC call from a function module.
tableParameterList A list of list field meta-data objects, org.fusesource.camel.component.sap.model.rfc.impl.ListFieldMeataDataImpl. Specifies the table parameters that are sent and returned in an RFC call to and from a function module.
exceptionList A list of ABAP exception meta-data objects, org.fusesource.camel.component.sap.model.rfc.impl.AbapExceptionImpl. Specifies the ABAP exceptions potentially raised in an RFC call of function module.

Function template example

The following example shows an outline of how to configure a function template:
<bean id="bookFlightFunctionTemplate"
    class="org.fusesource.camel.component.sap.model.rfc.impl.FunctionTemplateImpl">
    <property name="importParameterList">
        <list>
            ...
        </list>
    </property>
    <property name="changingParameterList">
        <list>
            ...
        </list>
    </property>
    <property name="exportParameterList">
        <list>
            ...
        </list>
    </property>
    <property name="tableParameterList">
        <list>
            ...
        </list>
    </property>
    <property name="exceptionList">
        <list>
            ...
        </list>
    </property>
</bean>

List field meta-data properties

A list field meta-data object, org.fusesource.camel.component.sap.model.rfc.impl.ListFieldMeataDataImpl, specifies the name and type of a field in a parameter list. For an elementary parameter field (CHAR, DATE, BCD, TIME, BYTE, NUM, FLOAT, INT, INT1, INT2, DECF16, DECF34, STRING, XSTRING), the following table lists the configuration properties that may be set on a list field meta-data object:
Name Default Value Description
name - The name of the parameter field.
type - The parameter type of the field.
byteLength - The field length in bytes for a non-Unicode layout. This value depends on the parameter type. See Section 123.3, “Message Body for RFC”.
unicodeByteLength - The field length in bytes for a Unicode layout. This value depends on the parameter type. See Section 123.3, “Message Body for RFC”.
decimals 0 The number of decimals in field value; only required for parameter types BCD and FLOAT. See Section 123.3, “Message Body for RFC”.
optional false If true, the field is optional and need not be set in a RFC call
Note that all elementary parameter fields require that the name, type, byteLength and unicodeByteLength properties be specified in the field meta-data object. In addition, the BCD, FLOAT, DECF16 and DECF34 fields require the decimal property to be specified in the field meta-data object.
For a complex parameter field of type TABLE or STRUCTURE, the following table lists the configuration properties that may be set on a list field meta-data object:
Name Default Value Description
name - The name of the parameter field
type - The parameter type of the field
recordMetaData - The meta-data for the structure or table. A record meta-data object, org.fusesource.camel.component.sap.model.rfc.impl.RecordMetaDataImpl, is passed to specify the fields in the structure or table rows.
optional false If true, the field is optional and need not be set in a RFC call
Note that all complex parameter fields require that the name, type and recordMetaData properties be specified in the field meta-data object. The value of the recordMetaData property is a record field meta-data object, org.fusesource.camel.component.sap.model.rfc.impl.RecordMetaDataImpl, which specifies the structure of a nested structure or the structure of a table row.

Elementary list field meta-data example

The following meta-data configuration specifies an optional, 24-digit packed BCD number parameter with two decimal places named TICKET_PRICE:
<bean    class="org.fusesource.camel.component.sap.model.rfc.impl.ListFieldMetaDataImpl">
    <property name="name" value="TICKET_PRICE" />
    <property name="type" value="BCD" />
    <property name="byteLength" value="12" />
    <property name="unicodeByteLength" value="24" />
    <property name="decimals" value="2" />
    <property name="optional" value="true" />
</bean>

Complex list field meta-data example

The following meta-data configuration specifies a required TABLE parameter named CONNINFO with a row structure specified by the connectionInfo record meta-data object:
<bean    class="org.fusesource.camel.component.sap.model.rfc.impl.ListFieldMetaDataImpl">
    <property name="name" value="CONNINFO" />
    <property name="type" value="TABLE" />
    <property name="recordMetaData" ref="connectionInfo" />
</bean>

Record meta-data properties

A record meta-data object, org.fusesource.camel.component.sap.model.rfc.impl.RecordMetaDataImpl, specifies the name and contents of a nested STRUCTURE or the row of a TABLE parameter. A record meta-data object maintains a list of record field meta data objects, org.fusesource.camel.component.sap.model.rfc.impl.FieldMetaDataImpl, which specify the parameters that reside in the nested structure or table row.
The following table lists configuration properties that may be set on a record meta-data object:
Name Default Value Description
name - The name of the record.
recordFieldMetaData - The list of record field meta-data objects, org.fusesource.camel.component.sap.model.rfc.impl.FieldMetaDataImpl. Specifies the fields contained within the structure.
Note
All properties of the record meta-data object are required.

Record meta-data example

The following example shows how to configure a record meta-data object:
<bean    id="connectionInfo"
        class="org.fusesource.camel.component.sap.model.rfc.impl.RecordMetaDataImpl">
    <property name="name" value="CONNECTION_INFO" />
    <property name="recordFieldMetaData">
        <list>
            ...
        </list>
    </property>
</bean>

Record field meta-data properties

A record field meta-data object, org.fusesource.camel.component.sap.model.rfc.impl.FieldMetaDataImpl, specifies the name and type of a parameter field withing a structure.
A record field meta-data object is similar to a parameter field meta-data object, except that the offsets of the individual field locations within the nested structure or table row must be additionally specified. The non-Unicode and Unicode offsets of an individual field must be calculated and specified from the sum of non-Unicode and Unicode byte lengths of the preceding fields in the structure or row. Note that failure to properly specify the offsets of fields in nested structures and table rows will cause the field storage of parameters in the underlying JCo and ABAP runtimes to overlap and prevent the proper transfer of values in RFC calls.
For an elementary parameter field (CHAR, DATE, BCD, TIME, BYTE, NUM, FLOAT, INT, INT1, INT2, DECF16, DECF34, STRING, XSTRING), the following table lists the configuration properties that may be set on a record field meta-data object:
Name Default Value Description
name - The name of the parameter field
type - The parameter type of the field
byteLength - The field length in bytes for a non-Unicode layout. This value depends on the parameter type. See Section 123.3, “Message Body for RFC”.
unicodeByteLength - The field length in bytes for a Unicode layout. This value depends on the parameter type. See Section 123.3, “Message Body for RFC”.
byteOffset - The field offset in bytes for non-Unicode layout. This offset is the byte location of the field within the enclosing structure.
unicodeByteOffset - The field offset in bytes for Unicode layout. This offset is the byte location of the field within the enclosing structure.
decimals 0 The number of decimals in field value; only required for parameter types BCD and FLOAT. See Section 123.3, “Message Body for RFC”.
For a complex parameter field of type TABLE or STRUCTURE, the following table lists the configuration properties that may be set on a record field meta-data object:
Name Default Value Description
name - The name of the parameter field
type - The parameter type of the field
byteOffset - The field offset in bytes for non-Unicode layout. This offset is the byte location of the field within the enclosing structure.
unicodeByteOffset - The field offset in bytes for Unicode layout. This offset is the byte location of the field within the enclosing structure.
recordMetaData - The meta-data for the structure or table. A record meta-data object, org.fusesource.camel.component.sap.model.rfc.impl.RecordMetaDataImpl, is passed to specify the fields in the structure or table rows.

Elementary record field meta-data example

The following meta-data configuration specifies a DATE field parameter named ARRDATE located 85 bytes into the enclosing structure in the case of a non-Unicode layout and located 170 bytes into the enclosing structure in the case of a Unicode layout:
<bean    class="org.fusesource.camel.component.sap.model.rfc.impl.FieldMetaDataImpl">
    <property name="name" value="ARRDATE" />
    <property name="type" value="DATE" />
    <property name="byteLength" value="8" />
    <property name="unicodeByteLength" value="16" />
    <property name="byteOffset" value="85" />
    <property name="unicodeByteOffset" value="170" />
</bean>

Complex record field meta-data example

The following meta-data configuration specifies a STRUCTURE field parameter named FLTINFO with a structure specified by the flightInfo record meta-data object. The parameter is located at the beginning of the enclosing structure in both the case of a non-Unicode and Unicode layout.
<bean    class="org.fusesource.camel.component.sap.model.rfc.impl.FieldMetaDataImpl">
    <property name="name" value="FLTINFO" />
    <property name="type" value="STRUCTURE" />
    <property name="byteOffset" value="0" />
    <property name="unicodeByteOffset" value="0" />
    <property name="recordMetaData" ref="flightInfo" />
</bean>