Configuring the SAP Suite Adapter for JCo 3.x
Whether you plan to create a business process that includes the SAP Suite adapter for JCo 3.x or use the predefined business processes, you must create a service configuration of the SAP Suite adapter for JCo 3.x. For more information, see Managing Services and Adapters.
Users can run both the existing SAP Suite adapter 2.x and SAP Suite adapter for JCo 3.x on the same Sterling B2B Integrator system. Ensure that both the JCo 2.x and JCo 3.x libraries are installed on Sterling B2B Integrator.
- JCo 3.x.x and later requires Visual Studio C/C++ run time libraries on Microsoft Windows operating system. For information on installing Visual Studio C/C++ runtime libraries, see SAP note 2786882.
- When you upgrade IBM® Sterling
B2B Integration from version 5.2.4 to 5.2.6.1 or later versions, the SAP JCo JAR files are uninstalled. So, you
must install the SAP JCo JAR files again after the upgrade.
You can install the JAR files explicitly using third-party script -
./install3rdParty.sh <vendorName> <vendorVersion> -l <sharedLib>.so.
For example for the SAP Java Connector:
./install3rdParty.sh sapjco 3_0 -l libsapjco3.so.
After making the above changes,
bin/dynamic_os.sh
contains the correct library path.
Field | Description |
---|---|
Name | Unique, meaningful name for the adapter configuration. Required. |
Description | Meaningful description for the adapter configuration, for reference purposes. Required. |
Select a Group | Select a Service Group to associate with this
adapter. Valid values:
|
SAP Integration Mode (Mode) | Integration mode that enables Sterling B2B Integrator
to communicate with an SAP system and with transfer documents. Required.
Valid values:
|
Document Storage Type | New parameter for SAP Suite adapter for JCo
3.x. Required. Select the document storage type where the documents
are persisted. Valid values are:
|
SAP system is load balanced (LoadBalanced) | Whether Sterling B2B Integrator is connecting
to a single SAP system or cluster of SAP systems. Required. Valid
values:
|
The integration mode and load-balancing determine which of the following parameters display for configuration. Refer to the following sections to determine the information that you must provide to continue creating the SAP Suite adapter for JCo 3.x service configuration:
- Synchronous BAPI
- Synchronous RFC
- File-based IDoc RFC
- ALE-based IDoc RFC
- User Properties
- RFC Server Configuration (Outbound)
- Connection Pool Settings
- Application User Settings
Synchronous BAPI
The following table describes the fields to configure for synchronous BAPI:
Field | Description |
---|---|
Load Balanced | |
SAP Message Server | Name that identifies the message server for the cluster of SAP systems. Required. Configure the Connection Retry settings to enable the adapter to automatically reconnect to the remote SAP system. For information about the Connection Retry settings, see Connection Retry Property. |
R/3 Name (R3name) | Name of the SAP system. Required. |
SAP Group (Group) | Group name that is configured for the cluster of SAP systems. Required. |
Not Load Balanced | |
SAP Application Server | Name of the server for the SAP application. Required. Configure the Connection Retry settings to enable the adapter to automatically reconnect to the remote SAP system. For information about the Connection Retry settings, see Connection Retry Property. |
SAP System Number | Number of the SAP system. Required. |
Synchronous RFC
The following table describes the fields to configure for synchronous RFC:
Field | Description |
---|---|
Load Balanced | |
SAP Message Server | Name that identifies the message server for the cluster of SAP systems. Required. Configure the Connection Retry settings to enable the adapter to automatically reconnect to the remote SAP system. For information about the Connection Retry settings, see Connection Retry Property. |
R/3 Name (R3name) | Name of the SAP system. Required. |
SAP Group (Group) | Group name that is configured for the cluster of SAP systems. Required. |
Not Load Balanced | |
SAP Application Server | Name of the server for the SAP application. Required. Configure the Connection Retry settings to enable the adapter to automatically reconnect to the remote SAP system. For information about the Connection Retry settings, see Connection Retry Property. |
SAP System Number | Number of the SAP system. Required. |
File-based IDoc RFC
The following table describes the fields to configure for File-based IDoc RFC :
Field | Description |
---|---|
Load Balanced | |
SAP Message Server | Name that identifies the message server for the cluster of SAP systems. Required. Configure the Connection Retry settings to enable the adapter to automatically reconnect to the remote SAP system. For information about the Connection Retry settings, see Connection Retry Property. |
R/3 Name (R3name) | Name of the SAP system. Required. |
SAP Group (Group) | Group name that is configured for the cluster of SAP systems. Required. |
SAP Port (Port) | Port or communication type that enables the SAP system to communicate with external systems during electronic data interchange. For example, for EDI subsystems that read IDocs in the form of sequential files, the SAP port is File. Required. |
Map SAP IDoc path to local path | Enable Sterling B2B Integrator to map the local directory path to the IDoc on the SAP system. |
Local Path (MapPath) | Local directory path to the IDoc on the SAP system. Required if you selected the Map SAP IDoc path to local path check box. |
Not Load Balanced | |
SAP Application Server | Name of the server for the SAP application. Required. Configure the Connection Retry settings to enable the adapter to automatically reconnect to the remote SAP system. For information about the Connection Retry settings, see Connection Retry Property. |
SAP System Number | Number of the SAP system. Required. |
SAP Port (Port) | Port or communication type that enables the SAP system to communicate with external systems during electronic data interchange. For example, for EDI subsystems that read IDocs in the form of sequential files, the SAP port is File. Required. |
Map SAP IDoc path to local path | Enable Sterling B2B Integrator to map the local directory path to the IDoc on the SAP system. |
Local Path (MapPath) | Local directory path to the IDoc on the SAP system. Required if you selected the Map SAP IDoc path to local path check box. |
XML Special Character Handling
Field | Description |
---|---|
Special Character Handling in XML Tags (XMLSpecialCharHandling) | New parameter for SAP Suite adapter for JCo 3.x. Required for BAPI and synchronous RFC modes. Handles invalid characters in XML tags. Valid values are Yes and No. The default value is No. |
Special Character Handling in XML Nodes (XMLNodesSpecialHandling) | New parameter for SAP Suite adapter for JCo 3.x. Required for BAPI and synchronous RFC modes. Handles invalid characters in XML nodes. Valid values are Yes and No. The default value is No. |
Enable verbose logging for XML processing (XMLNodesSpecialHandling) | New parameter for SAP Suite adapter for JCo 3.x. Optional parameter available for BAPI and synchronous RFC modes. Enables verbose logging support during XML processing. |
ALE-based IDoc RFC
SAP Outbound IDoc processing must be registered with two RFC libraries. For example, INBOUND_IDOC_PROCESS (IDoc version 3) and IDOC_INBOUND_ASYNCHRONOUS (IDoc version 4). The ALEServer, which is responsible for ALE-based IDoc processing, is registered with only one RFC library at a time, when the RFC list is not specified in the service configuration. It uses the SAP version (3 or 4) that is set in the adapter settings.
Once the RFC list is specified using online or offline mode in the adapter configuration page, ALEServer is registered and starts with all RFCs, and is able to dynamically call the correct RFC per inbound IDoc version from the SAP system.
The following table describes the fields to configure for ALE-based IDoc RFC:
Field | Description |
---|---|
Load Balanced | |
SAP Message Server | Name that identifies the message server for the cluster of SAP systems. Required. Configure the Connection Retry settings to enable the adapter to automatically reconnect to the remote SAP system. For information about the Connection Retry settings, see Connection Retry Property. |
R/3 Name (R3name) | Name of the SAP system. Required. |
SAP Group (Group) | Group name that is configured for the cluster of SAP systems. Required. |
SAP Version (SAPVersion) | Version of the SAP system. Required. |
Retry Sending IDocs | Check if SAP Suite adapter for JCo 3.x should automatically retry to deliver the IDoc to the SAP system. |
Max Retries | Sets how often the retry should take place. Setting the value to 0 causes the SAP Suite adapter for JCo 3.x to retry infinitely. |
Retry Sending Interval | Delay in seconds between two retries. |
Not Load Balanced | |
SAP Application Server | Name that identifies the application server for the cluster of SAP systems. Required. Configure the Connection Retry settings to enable the adapter to automatically reconnect to the remote SAP system. For information about the Connection Retry settings, see Connection Retry Property. |
SAP System Number | Number of the SAP system. Required. |
SAP Version (SAPVersion) | Version of the SAP system to control IDoc version.
Required. Valid values are:
|
Retry Sending IDocs | Check if SAP Suite adapter for JCo 3.x should automatically retry to deliver the IDoc to the SAP system. |
Max Retries | Sets how often the retry should take place. Setting the value to 0 causes the SAP Suite adapter for JCo 3.x to retry infinitely. |
Retry Sending Interval | Delay in seconds between two retries. |
Connection Retry Property
Connection Retry is used when the SAP Suite adapter for JCo 3.x is started and the remote SAP system is not running, for example, because of maintenance. When configuring SAP Suite adapter for JCo 3.x, select the Retry Connection to SAP in the Connection Retry Settings page to enable the adapter to keep retrying to connect to the remote SAP system until it successfully establishes a connection with the remote SAP system. If this parameter is not set and the remote SAP system is not running, the adapter returns an error and remains in the 'Startup Failed' state.
You can configure the Max. Connection Retries (0 = unlimited) parameter to set the maximum number of retries to connect to the remote SAP system. Ensure that you enter a numeric value. The default value is 0 (unlimited retries). You can also configure the Retry Connection Interval (seconds) parameter to set the delay interval between two subsequent connection retries in seconds. The default value is 60 seconds.
However, for some permanent login error types, no retry is performed. For example, if the configuration has a wrong SAP user password, then no retry is performed because the error has to be resolved manually (by entering the correct password).
Sometimes, the SAP user that is used to login by the SAP Suite adapter for JCo 3.x is locked during SAP maintenance, and then unlocked after the maintenance. In this case, the User locked error must be treated as a temporary error condition and a connection retry is required so that the RFC Server can reconnect automatically after the SAP user is unlocked.
The following table describes the fields to configure for Connection Retry Property.
Field | Description |
---|---|
Retry Connection to SAP | Select this option when the adapter is started and the remote SAP system is not running, for example, because of maintenance. Select this parameter to enable the adapter to keep retrying to connect to the remote SAP system until it successfully establishes a connection. If this parameter is not set and the remote SAP system is not running, the adapter returns an error and remains in the 'Startup Failed' state. |
Max. Connection Retries (0=unlimited) | You can configure this parameter if you have enabled ‘Retry Connection to SAP'. Specify the maximum number of retries to connect to the remote SAP system. When the maximum number is exceeded, the adapter start ends with an error. Valid value is any number. The default value is 0 (unlimited). |
Retry Connection Interval (seconds) | You can configure this parameter if you have enabled ‘Retry Connection to SAP'. Specify the delay interval between two subsequent connection retries in seconds. The default value is 60 seconds. |
User Properties
The following table describes the fields to configure user properties.
Field | Description |
---|---|
Client (Client) | Name of the client in the SAP system. Required. |
User (User) | Name of the authorized user of the SAP account. Required. |
Password (Password) | Password of the authorized user of the SAP account. Required. The maximum length of the password is 40 characters. |
Language (Lang) | Language used by the SAP account. Required. Valid value is EN (English). |
Code Page (Codepage) | Code page of this SAP system—for example, 1100 for English and most European languages. Optional. |
RFC Server Configuration (Outbound)
The following table describes the fields to configure RFC properties:
Field | Description |
---|---|
Start RFC Server automatically | Start the local RFC server automatically. The RFC server is required for SAP outbound. |
Gateway Host (Gwhost) | Name of the host running the SAP gateway server. You can use an IP address. Required. |
Gateway Service (Gwserv) | Gateway service of the SAP system. Required.
Specify either the service name, sapgw<xx> or
the service port, 33<xx> , where xx is
the number of the SAP system. If you specify only the service port,
the service name lookup in the services file is not required. The
service files are located:
|
Program ID (Program ID) | The SAP system program ID used to tie the SAP Suite adapter for JCo 3.x instance to the correct SAP system for handling outbound requests. The value provided here should match the value of the Program ID parameter configured in the SAP RFC Destination. |
RFC Server Connection Count | New parameter for SAP Suite adapter for JCo 3.x. A value of greater than 1 allows parallel outbound processing of server instances. |
RFC Server Minimum Thread Count | New parameter for SAP Suite adapter for JCo 3.x. Defines the minimum number of JCo Server worker threads for receiving calls from SAP. The default value is 1. If JCo Server is idle, the specified number of minimum threads are kept running in the thread pool. |
RFC Server Maximum Thread Count | New parameter for SAP Suite adapter for JCo 3.x. Defines the maximum number of JCo Server worker threads in the thread pool. To enable parallel outbound processing, use a value greater than 1. The default value is 2. It is recommended you use a value of 4 to process a high number of small messages. |
Outbound Process to Start | Select the name of the business process that Sterling B2B Integrator should run after receiving an IDoc from SAP. |
Outbound Encoding | Set the character encoding for the outbound document. |
Wait for synchronous RFC Outbound response | Enables support for synchronous responses in case of outbound SAP RFC calls. |
Response Timeout | After this timeout (in seconds), the RFC server closes the connection to the SAP system. After this timeout, if Sterling B2B Integrator wants to send a response back to SAP, an error is returned. |
Register Remote Function | To be able to handle outbound BAPI or RFC calls, the call structures have to
be registered in Sterling B2B Integrator. Options are:
|
Filter online RFC list by | Filters the RFC list. |
Connection Pool Settings
- Connections: Physical connections to an SAP system. Connections can be in either closed or open status.
- Sessions: Logical connections to an SAP system. Each session object contains a connection object. A session can be in either used, unused, or called status.
The following table describes the fields to configure a connection pool.
Field | Description |
---|---|
Connection Pool Capacity (PoolCapacity) | New parameter for SAP Suite adapter for JCo 3.x. Required. Maximum number of idle connections kept open. The default value is 4. |
Connection Peak Limit (ConnPeakLimit) | New parameter for SAP Suite adapter for JCo 3.x. Required. Maximum number of simultaneous connections that are active. The default value is 4. |
Connection Expiration Time (ConnExpirationTime) | New parameter for SAP Suite adapter for JCo 3.x. Required. Time (in seconds) after which the idle connections can be closed. The default value is 300 seconds. |
Connection Expiration Time Check Period (ConnExpTimeCheckPeriod) | New parameter for SAP Suite adapter for JCo 3.x. Required. Check interval (in seconds) for expired connections. The default value is 30 seconds. |
Maximum time to wait for a connection (MaxGetClientTime) | New parameter for SAP Suite adapter for JCo 3.x. Required. Maximum time to wait for a connection after peak limit is reached. The default value is 300 seconds. |
In the default configuration, 4 connections to SAP are kept open even if the system is idle for longer than the value set in Connection Expiration Time. If the value set in the Connection Peak Limit parameter is reached, and an additional call is made with a delay longer than the value set for the Maximum time to wait for a connection parameter, the connection pool returns an exception and the call ends in an error. To resolve this issue, increase the value of the Connection Peak Limit parameter.
Application User Settings
The following table contains the user setting for the service configuration.
Field | Description |
---|---|
User ID | Name of the user to associate with the business process that includes this service configuration. |
- Create a business process that includes the SAP Suite adapter for JCo 3.x.
- Configure SAP business processes for implementation.