SEEBURGER EDI

SAP IDoc Adapter

Version: v6.3.5.Q4

June 28, 2013

Table of Contents

1 Terms and Definitions 1

2 Introduction 2

3 Basics 3

3.1 IDoc Connector 3

3.1.1 IDoc Connector Server 3

3.1.2 IDoc Connector Client 3

3.2 Application Link Enabling (ALE) 3

3.3 Intermediate Document (IDoc) 4

3.4 Status Confirmation 4

3.5 Transactional Remote Function Call (tRFC) 4

3.6 SAP Java Connector (JCo) 4

4 Overview 5

4.1 Features and Restrictions 5

4.2 System Requirements 6

4.3 Integration 7

4.4 Logical Systems 7

5 Installation 9

5.1 SAP Java Connector (JCo) Installation 9

5.1.1 Applicable JCo Versions 9

5.1.2 Obtaining the Correct JCo Libraries from the SAP Service Marketplace 9

5.1.3 Installation 10

5.1.4 Troubleshooting 10

5.2 Available Versions of JCo for Different Architectures 11

6 Usage 13

6.1 Adapter Control over the Control Center 13

6.2 Operations 14

6.3 Monitoring 15

7 Master Data Configuration 16

7.1 Configuring Connections 16

7.2 Common Connection Settings 16

7.2.1 Settings 16

7.2.2 Send-Site (SAP inbound) 16

7.2.3 Extended 17

7.3 Configuring Addresses 19

7.4 Configuring Registrations 19

7.4.1 Settings Tab 21

7.5 Configuring File Port Listeners 21

7.5.1 Settings Tab 22

8 Process Configuration 23

8.1 Sending IDocs (SAP Inbound) 23

8.1.1 SendIDocMD 23

8.1.2 SendIDoc 24

8.2 Sending Status IDocs 26

8.2.1 SendSAPStatusReport 27

8.2.2 SendSAPStatusReportSync 27

8.2.3 SendStatus 28

8.2.4 SendStatusMD 29

8.3 Receiving IDocs (SAP Outbound) 30

8.3.1 ReceivedIDocEvent 30

8.4 Fault Messages 30

8.4.1 DtFault 30

8.5 Adapter Invocation Mode 31

8.6 Direct Invocation 31

8.7 Synchronous Adapter Invocation 32

8.8 Worklist Handler 32

9 Extended Features 34

9.1 Status IDoc Handling 34

9.1.1 Using the Generated Status IDoc Template 34

9.1.2 Queue for Status IDocs 34

9.1.3 Generation of Status IDocs in a Process 34

9.2 Customizable RFC Trigger Function for Fileport Communication 35

9.3 Connection Pool 36

10 Adapter Configuration 38

10.1 Dumping 38

10.2 Logging 39

10.2.1 JCo Logging 39

10.2.2 RFC Tracing 39

10.3 Extended Configuration Flags 39

10.4 Unicode and Code Page Settings 42

10.4.1 Unicode Code Pages 42

10.4.2 Unicode Settings in SAP 44

10.5 Memory Requirements 44

10.5.1 IDoc Connector Client Memory Management 45

10.6 Configuration within R/3 46

10.6.1 Creating a Minimum Authorization Profile for an RFC User 46

10.6.2 RFC Destination 51

10.6.3 Status Processing 52

10.7 Batching IDocs in R3 52

10.7.1 Scenario Description 52

10.7.2 Configuration in R3 53

10.7.3 Testing 53

11 Monitoring 54

11.1 Adapter Monitor 54

11.2 Filter 54

11.3 R/3 System 54

12 Adapter Interactions 56

13 Troubleshooting 58

13.1 Resolving Problems When Sending IDocs 58

13.2 Resolving Problems When Receiving IDocs 58

14 Known Restrictions 60

A Sample Scenario – Using tRFC 61

A.1 Installation 62

A.2 Master Data Configuration 62

A.3 Receiving Treatment 65

A.4 Configuration within R/3 67

A.5 Running the Sample Scenario Process 74

B Sample Scenario – Using File Port 79

B.1 File Port Configuration 79

B.2 Master Data Configuration 80

B.3 Running the Sample Scenario Process 81

C FAQ 83

D Performance Considerations 85

D.1 Size of the Transferred IDocs 85

D.2 Available Free Memory 86

5 Secure Network Communication (SNC) 87

5.1 Prerequisite 87

5.1.1 R/3 87

5.1.2 SEEBURGER System 88

5.2 Configuration 89

5.2.1 Generation of PSE file 89

5.2.2 Configuring R/3 90

5.2.3 Master Data Configuration 97

Copyright (c) 2013 SEEBURGER AG (http://www.seeburger.de). All rights reserved.

If (registered or pending) trademarks are named in this document, the rights of the respective proprietorsapply.

Note: False configuration and/or improper use of communication components may result in significantcharges from your telecommunication provider. Also consider configuration changes initiated by yourtelecommunication provider. SEEBURGER is not liable for related additional costs.

Note: Please refer to the Knowledgebase article 13379 for an important notice concerning possible incurredcharges from your telecommunication provider.

Note: The information in this document is proprietary to SEEBURGER. No part of this document may bereproduced, copied, or transmitted in any form or purpose without the express prior written permission ofSEEBURGER AG.

Note: We expressly declare that the document "SEEBURGER Legal Information" (delivered also with yourBIS installation media) is part of this documentation.

Figures

4-1 BIS Architecture 7A-1 Master Data Configuration 63A-2 Status Confirmation 64A-3 Settings 65A-4 RFC Destination 68A-5 Special Options 69A-6 Ports in Id processing 70A-7 Ports in IDoc processing 70A-8 Outbound Parameters 72A-9 Inbound Parameters 73A-10 Partner Profiles 74A-11 Test Tool for Idoc processing 75A-12 Edit control record fields 75A-13 Information 76A-14 Outbound Processing 76A-15 IDoc List 77B-1 Ports in IDoc processing 80B-2 Send-site (SAP Inbound) 81B-3 Test Tool for IDoc processing 82B-4 Edit control record fields 825-1 Transaction STRUST 915-2 Transaction STRUST - Add to certificate list 925-3 Transaction STRUST - Imported certificate 935-4 Transaction SU01 945-5 Transaction STRUST 955-6 RFC Destination - Transaction SM59 965-7 RFC Destination - Activating SNC 975-8 SAP Connections 98

SAP IDoc Adapter

SAP IDoc Adapter - v6.3.5.Q4 1

1 Terms and Definitions

Terms Definition

IDoc Intermediate Document

ALE Application Link Enabling

tRFC Transactional Remote Function Call

JCo SAP Java Connector

SAP IDoc Adapter


2 Introduction

The SEEBURGER IDoc Connector offers reliable exchange of IDocs with SAP R/3 systems. Communicationoccurs over two Application Link Enabling (ALE) technologies, Intermediate Documents (IDoc) andtransactional Remote Function Calls (tRFC).IDoc is the standard message format for data exchange among different systems, while tRFC provides atransport mechanism for IDocs with guaranteed delivery.

SAP IDoc Adapter


3 Basics

This topic gives an overview of the SEEBURGER IDoc Connector and its underlying technology.

3.1 IDoc Connector

This component supports the sending and receiving of IDocs via tRFC and via file port. Furthermore, statusconfirmations for received IDocs can be sent to the R/3 system.

The IDoc Connector consists of two separate modules, due to technical reasons: a sender and a receivermodule. They both run as separate processes in the operation system.

3.1.1 IDoc Connector Server

The IDoc Connector Sever is the receiver module of the IDoc Connector that receives IDocs from an R/3system.

On startup this module registers with the SAP gateway and waits for incoming IDocs. It sends a WSDL messageto the BIS 6 system for each packet of received IDocs. This message contains the received IDocs as itsattachment, along with some information about the sender of the IDocs.

3.1.2 IDoc Connector Client

The IDoc Connector Client is the sender module of the IDoc Connector that sends IDocs to a R/3 system.This module can also send status confirmations for IDocs to a R/3 system, which have been received by theIDoc Connector server module.

For each SendIDoc or SendIDocMD operation, the module sends the IDocs that are stored in the WSDLmessage to the target R/3 system. The module creates a status IDoc that contains the necessary status records,and sends this IDoc to the R/3 system for the SendStatus and the SendStatusMD operations.

3.2 Application Link Enabling (ALE)

ALE is a set of technologies and services that have been introduced by SAP to facilitate the exchange of dataamong R/3 systems; and between R/3 systems and external systems.

The IDoc interface is the most important ALE technology. For further information on the IDoc interface andthe IDoc format, please refer to the document IDoc Interface/Electronic Data Interchange (BC-SRV-EDI) thatis part of the SAP Library.

SAP IDoc Adapter


3.3 Intermediate Document (IDoc)

The IDoc format defines the general structure of IDocs. There are different versions of the general structure.

The IDoc Connector supports:

• IDoc version 2 (introduced with SAP Release 3.0/3.1)

• IDoc version 3 (introduced with SAP Release 4.0)

Besides the general structure, IDocs also have an application-specific structure that is determined by it's IDoctype. An application-specific structure is defined for each business case. The IDoc Connector supports all typesof IDocs, as it exclusively works on the basis of the general IDoc structure.

In addition to business data, IDocs also contain administrative information, including information on the sender,the receiver and the processing status of an IDoc. The IDoc Connector utilizes this administrative informationto send IDocs to their destination.

Usually, an IDoc is represented as a file with a fixed record size (INHOUSE format). An IDoc file may containmultiple IDocs, where each IDoc is simply appended to another. While an IDoc file may contain IDocs of differentIDoc types, all IDocs contained in one IDoc file must be of the same version. The IDoc Connector rejects IDocfiles that contain IDocs of different IDoc versions.

3.4 Status Confirmation

The R/3 system maintains status information on the processing status of each IDoc, e.g., IDoc generated, orIDoc ready for dispatch. A receiving system may send status confirmations to inform the R/3 system about theprocessing stages of a received IDoc.

The IDoc Connector optionally creates and sends status IDocs to the R/3 system. A status IDoc is a specialtype of IDoc that contains the status information for received IDocs.

3.5 Transactional Remote Function Call (tRFC)

The Remote Function Call (RFC) interface enables remote calls between two R/3 systems, or between a R/3system and a non-R/3 system. The transactional Remote Function Call (tRFC) protocol is an extension of theRFC protocol that guarantees that each function call is processed exactly once.

The IDoc Connector uses the tRFC protocol to reliably exchange IDocs with R/3 systems: The tRFC protocolassigns an unique transaction identifier (TID) to each transaction. Duplicate execution of transactions is avoidedby the receiver's system carrying out a comparison of the TID of a transaction with the TIDs of transactionsthat have already been executed.

3.6 SAP Java Connector (JCo)

SAP JCo is a toolkit for building applications written in Java and communicating with R/3 systems over theRFC interface. JCo is based on libRFC, a native programming library that implements the RFC protocol.

Since the IDoc Connector relies on JCo for communication with R/3 systems, a properly installed SAP JavaConnector (JCo) and libRFC is required.

SAP IDoc Adapter


4 Overview

4.1 Features and Restrictions

Supported Formats for Data Exchange

• IDoc version 2 (any IDoc type)

• IDoc version 3 (any IDoc type)

Support for Status Confirmations

Status records are provided by the basic IDoc type SYSTAT01 as defined by R/3 release 3.x. The followingfields can be customized for status IDocs: STATUS, SNDPOR, SNDPFC, SNDPRT, SNDPRN, CREDAT andCRETIM. When the file port is used for sending status IDocs, the fields RCVPFC, RCVPRT, and RCVPRN can also be customized.

The component supports:

• tRFC and file port based communication

• Sending IDocs to R/3 (SAP INBOUND)

• Receiving IDocs from R/3 (SAP OUTBOUND)

• Sending status confirmations to R/3 for received IDocs

• Parallel processing

• Distributed processing

• Load-balancing

• Secure Network Communication (SNC)

• Unicode R/3 Systems

• Non-Unicode R/3 Systems

Restrictions: Please refer to the topic Known Restrictions (page 60) for details.

• Memory consumption has to be kept in mind, when processing large IDocs via tRFC, please refer to thetopic Configuration within R/3 (page 46) (Performance considerations) for details.

• XML IDocs are not supported.

SAP IDoc Adapter


4.2 System Requirements

The common system requirements are described in the BIS Installation Guide. Furthermore the followingrequirements must be met in order to run the the component properly:

System Requirement

SAP Java Connector SAP JCo Version >=3.0.8

R/3 system The release 3.1h or later.

Network The TCP/IP connection to the R/3 system.

The SAP Java Connector (JCo) must be pre-installed before running the component. The SAP Java Connectoris a toolkit for the communication with R/3 systems. It can be downloaded from the SAP Service Marketplaceat http://service.sap.com/connectors. A valid SAP-OSS/customer account is required for logging into the SAP Service Marketplace. Usually all SAP customers have a corresponding account.

Note: It is strongly recommended to obtain the SAP JCo before running the BIS setup, because thesetup will ease the correct installation of the SAP JCo libraries and helps to avoid manual interactions.

IPv6 support

For accessing the SAP systems via IPv6, please refer to SAP note 1346768 first.

In the start-up scripts of both the central instance and the nodes, you have to set the environment variable SAP_IPv6_ACTIVE=1. The scripts already contain an corresponding section that only has to be commented.

The environment variable is required to activate the IPv6 support in the SAP JCo native libraries.

Attention: Setting of this environment variable is only allowed, if you use IPv6 communication. If SAP_IPv6_ACTIVE=1 is set, the IPv6 address is preferred, if both IPv4 and IPv6 addresses are available.Accessing an IPv4 address can only be achieved by using a different host name.It is furthermore recommended to comment the variable SAP_IPv6_ACTIVE=1, rather then setting it toSAP_IPv6_ACTIVE=0.Please refer to t his link in help.sap.com for further details.

CPI-C Max Connections

The network connections between the SAP JCo based on SEEBURGER adapters and an SAP system, aremanaged by a special networking layer of SAP called CPI-C. For the SAP JCo based BIS adapters CPI-C isequal to TCP/IP. The amount of such CPI-C connections is limited. For most scenarios this value is sufficient.

In cases where many parallel connections to different SAP systems are needed, the CPI-C max. conversationssetting has to be adapted. For JCo3, which is used by SEEBURGER adapters, there is a Java system propertynamed jco.cpic_maxconv. You can configure this property in the file %bisas.home%/software/sample.vm.properties in the key vmoptions (for 32bit) and vmoptions64 (for 64bit) of the central and distributed instance. Ithas a default value of 204.

Attention: Setting of a lower value then the default may result in errors because no new TCPconnections between SAP and local systems can be opened. Using a too high jco.cpic_maxconv valuemay cause connectivity problems at the SAP gateway. Before you change the value of this property,please consult the administrator of the SAP system.

https://service.sap.com/sap/support/notes/1346768

http://help.sap.com/saphelp_nwpi711/helpdata/en/46/cd5ee2c45365dde10000000a155369/content.htm

SAP IDoc Adapter


4.3 Integration

The figure below illustrates the BIS 6 architecture.

Figure 4-1: BIS Architecture

Each communication adapter runs inside the Adapter Engine. Send requests are passed from the ProcessEngine via the Queuing System Worklist, the Direct Mode or the sync connector to the appropriatecommunications adapter in the Adapter Engine.

Incoming messages received from a listener for example, are forwarded to the Process Engine using theInitiator.

4.4 Logical Systems

The SAP JCo-based adapters supports Logical Systems as described in the manual Master AdapterConfiguration Guide .

SAP IDoc Adapter


In particular, master data and runtime data belong exclusively to one Logical System. The adapter is able toprocess data and processes according to their Logical System, and therefore one instance of the adapter maybe shared across all Logical Systems.

Listeners Configuration

In order to assign the Listeners to one Logical System exclusively, some unique constraints are added to the DB tables. Every Registration must be identified by its program ID and its connection reference. Every File PortListener is identified by its local path.

For security reasons, besides the unique constraints, a check for duplicate listeners is performed on adapterstart-up.

• Each RFC/IDoc Listener is identified by:

• gateway host,

• gateway service

• program ID.

If a Listener is marked to be a duplicate, it is not started at all, and an error message is logged in theAdapter Error Monitor. The message contains the Logical System for which it is configured, and thereason why this Listener is not started.

• Each file port Listener is identified by its local path. Nonetheless the more unique criterion in this case isthe SAP side path. That’s why the file port listener's duplicate check is performed on the SAP side paths.

SAP IDoc Adapter


5 Installation

The common installation steps are described in the BIS Installation Guide.

Attention: It is strongly recommended to run the SAP JCo based communication adapters in a 64 bitJava VM in production scenarios. The 32 bit versions of SAP JCo are recommended for test and demosystems only.

Attention: It is strongly recommended for an optimized Java VM heap configuration to install the SAPJCo based communication adapters as a so-called External Node. Please refer to the Master AdapterInstallation Guide for more details about the External Node installation and refer to the topic MemoryConsumption (page 44) of this book for optimized Java VM heap configuration.

Attention: It is strongly recommended to use the latest JCO version from SAP Service Marketplace at http://service.sap.com/connector (refer also to the next topic about the retrieval of the latest and correctSAP JCo version).

5.1 SAP Java Connector (JCo) Installation

5.1.1 Applicable JCo Versions

All SAP JCo based communication adapters require JCo version 3.0.8 at least.

Note: You cannot run the SAP JCo based communication adapters with a JCo version lower then3.0.8. Although versions of SAP JCo 3.0.x branch which are higher than 3.0.8 can be used, this is notrecommended until further notice.

5.1.2 Obtaining the Correct JCo Libraries from the SAP ServiceMarketplace

1.Read SAP Note 1077727 concerning the latest information about the supported platform and OScombinations before installing any of SAP JCo based communication adapters.

2.Go to the download section at SAP Service Marketplace. The page cannot be linked directly, pleasefollow the link http://service.sap.com/connectors | SAP Java Connector | Tools and Services | click thelink Download SAP JCo Release 3.0 on the right page. (The internal component name at SAP for theSAP Java Connector is BC-MID-CON-JCO).

3.Choose

• the correct version,

http://service.sap.com/connector

SAP IDoc Adapter


• the shared libraries (depending on the operating system),• the hardware architecture on which the Java Virtual Machine is running.

5.1.3 Installation

5.1.3.1 BIS Setup

The recommended way of installing the SAP JCo Java and native libraries is copying them to the correctlocations during the setup of the central instance, because the setup will ease the correct installationof the SAP JCo libraries and helps to avoid manual interactions.A specific dialog will be shown, if an article is selected for installation that needs the SAP JCo to work properly.Copying the libraries during the setup has the advantage that the setup for distributed nodes will already includethe libraries, and the dialog will check, if the user has copied the libraries to the correct places.

The files have to be copied to the following locations (file name of native libs used exemplary here are forMicrosoft Windows/Linux platform):

<BIS6_HOME>/lib/ext/sapjco3.jar

<BIS6_HOME>/lib/native/[sapjco3.dll | libsapjco3.so]

Note: If SAP JCo libs have not been installed during the initial setup of BIS, but are deployed manuallyaccording to the above documentation, the register script has to be executed.

Note: The file names of the native libraries depend on the OS and architecture of the target system theBIS is installed to. Please refer to the topic Available Versions of JCo for Different Architectures (page11) for the list of the library names on the different architectures.

The BIS Setup copies the libs using the correct user that is used to run BIS 6 (not the root user).

AIX: For installation/update on AIX, please refer to the topic Appendix C: FAQ (page 83).

For further details on the installation of the SAP Java Connector, refer to the two files \javadoc\installation.html and \javadoc\useful.html, contained in the archive file of the SAP Java Connector.

5.1.4 Troubleshooting

If there are any difficulties in starting up SAP JCo based communication adapters, it is recommended to turn offthe Autostart feature of both adapters. Due to the usage of native libraries in SAP JCo only the first adapterstart-up attempt after a BIS (re)start will show potential problems related to these native SAP libraries, orlibraries they depend on.

All subsequent start-up attempts will simply show an error indicating the file sapjco3.jar not being available,which may be misleading in that case.

Examples for problems related to the native libraries:

• Dependent libraries may be missing.

Note: For a Linux/Unix system it may be required to install an older version of C++ libraries. The errormessage during adapter start-up tells which one is needed exactly. It is recommended to copy theselibraries to the BIS6_HOME/lib/native/ directory too.

Note: For Windows systems: Since SAP JCo 3 is part of the SAP 7.20 kernel family, SAP JCo 3needs the most recent version of Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package

SAP IDoc Adapter


(KB973544). Please refer to the SAPNote 684106 "Microsoft Runtime DLLs." and Microsoft SecurityBulletin MS09-035 to get more information which version is needed for your platform and where toobtain it.

• The incorrect bit width has been chosen. The native libraries must have the same bit width than theJava VM of BIS uses.

• The owner or the access rights may be incorrect so that the file cannot be accessed by the BIS runtimeuser.

• Old JCo version still used after update.

Note: AIX: For installation/update on AIX, please refer to the topic Appendix C: FAQ (page 83) and SAPNote 608726 .

5.2 Available Versions of JCo for Different Architectures

Obtaining the Correct Bit Width of Libraries

The JCo 3 release is supported for the following operating systems/architectures in combination with the Java6 Standard Edition of the corresponding platform vendor.

This list only shows the combinations with OSs and architecture which are available for the SEEBURGER BIS 6.

Please always refer to the SAP Note 1077727 for the latest information on the complete list of supportedplatforms and OSs for SAP JCo 3.

Note: You only need the 64bit-version of the JCo package, if you are using a 64bit Java VM. If you areusing a 32bit Java VM on a 64bit platform, please download the 32bit JCo.

Microsoft Windows

OS Architecture JVM Vendor Archive File

Windows XP, WindowsServer 2003, WindowsVista, Windows Server2008

x86 32bit Sun sapjco3-NTintel-3.0.8.zip

Windows XP, WindowsServer 2003, WindowsVista, Windows Server2008

x86_64 64bit Sun sapjco3-NTAMD64-3.0.8.zip

Native DLL name: sapjco3.dll

Linux

OS Architecture JVM Version Archive File

SuSE SLES10, RedHatEL5

x86 32bit Sun sapjco3-linuxintel-3.0.8.tgz

SuSE SLES10, RedHatEL5

x86_64 64bit Sun sapjco3-linuxx86_64-3.0.8.tgz

Native library name: libsapjco3.so


http://www.microsoft.com/technet/security/bulletin/MS09-035.mspx

http://www.microsoft.com/technet/security/bulletin/MS09-035.mspx



SAP IDoc Adapter


Solaris


Solaris 10 SPARC 64bit Sun sapjco3-sun_64-3.0.8.tgz

Solaris 10 x86_64 64bit Sun sapjco3-sunx86_64-3.0.8.tgz


AIX


AIX 5.3, AIX 6.1 Power PC 64bit IBM sapjco3-rs6000_64-3.0.8.tgz


Please refer also to the topic: First Q/A of chapter FAQ (page 83) for installation on AIX.

HP-UX


HP-UX B11.23, B11.31 Itanium 64bit HP sapjco3-hpia64-3.0.8.tgz

Native library names: libsapjco3.so

Combinations that are not mentioned as supported above may run properly, but it is strongly recommendedto follow these recommendations.

SAP IDoc Adapter


6 Usage

6.1 Adapter Control over the Control Center

To start and stop the adapter use the adapter-related Control Center. The adapter's user configuration can bealso displayed and edited there.

For more information, refer to the topic Control Center in the Master Adapter Configuration Guide.

SAP IDoc Adapter


6.2 Operations

IDoc Connector Client

Parameter Definition

SendIDoc_v2 This operation sends an IDoc to a R/3 system (SAP Inbound).

SendIDocMD_v2 This operation sends an IDoc to a R/3 system (SAP Inbound) and sets allnecessary master data in the operation.

SendStatus_v2 This operation sends a status confirmation IDoc to an R/3 system (SAPInbound) and sets all necessary master data in the operation.

SendStatusMD_v2 This operation sends a status confirmation IDoc to an R/3 system (SAPInbound) (uses the SendSAPStatusReport operation instead).

SendSAPStatusReport This operation sends a status confirmation IDoc to an R/3 system (SAPInbound). This operation relies on a template that is created by the IDocConnector Server when receiving an IDoc. The response of the sending ofthe status confirmation is NOT returned to the process.

SendSAPStatusReportSync This operation is equivalent to SendSAPStatusReport with the differencethat it contains the request and the response messages. The response ofthe sending of the status confirmation is returned to the process.

SendIDocAttention: This operation is an older version and we do notrecommend it for use. SendIDoc_v2 has an extended response andshould be used instead.

This operation sends an IDoc to an R/3 system (SAP Inbound).

SendIDocMDAttention: This operation is an older version and we do notrecommend it for use. SendIDoc_v2 has an extended response andshould be used instead.

This operation sends an IDoc to an R/3 system (SAP Inbound) and sets allnecessary master data in the operation.

SendStatusAttention: This operation is an older version and we do notrecommend it for use. SendIDoc_v2 has an extended response andshould be used instead.

This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound) and sets all necessary master data in the operation.

SendStatusMDAttention: This operation is an older version and we do notrecommend it for use. SendIDoc_v2 has an extended response andshould be used instead.

This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound) (uses the SendSAPStatusReport operation instead).

IDoc Connector Server

Parameter Definition

ReceivedIDocEvent An IDoc is received by the IDoc Connector server and is initiated to theengine.

SAP IDoc Adapter


6.3 Monitoring

The Adapter is connected to different monitors. The specific function of each monitoring tool is described inthe Master Adapter Configuration Guide.

Monitor Description

Adapter Monitor Provides runtime information.

Recovery Monitor If individual orders require recovery, they are listed in the RecoveryMonitor.

Transaction Monitor Provides information on the state of transactions of the adapter. The exactdefinition of a transaction depends on the respective adapter, but usually atransaction describes the reception or the sending of a message.

SAP IDoc Adapter


7 Master Data Configuration

7.1 Configuring Connections

The Connections master data contains the settings which are used

• to connect with an SAP application server,

• to send IDoc messages,

• to connect with an SAP gateway in order to receive IDoc messages.

7.2 Common Connection Settings

7.2.1 Settings

Parameter/Option Description

Gateway host The host name or the IP address of the computer which operates theSAP gateway. The gateway host may also be specified as a completeSAP router string. The component registers at the SAP gateway toreceive messages. This setting is also used for the SAP INBOUND files,if the Explicit application server and gateway connection type has beenselected.

Gateway service TCP service number of the SAP gateway.

The gateway service (e.g. sapgw00) is an alias for the TCP port,which is used to connect to the SAP gateway.The TCP port is a concatenation of the digits 33 (=sapgw) and thesystem number of the SAP system, e.g. 00. So sapgw00 complieswith TCP port 3300.

This list describes all available fields; the dialog does not show all applicable configurations.

7.2.2 Send-Site (SAP inbound)


User The SAP log-on user. It is recommended to create a dedicated minimumauthorization profile for this communication user.

SAP IDoc Adapter



Note: Minimum authorizations, needed for this user in short (Creating a Minimum Authorization Profile for an RFC User ):Authorization object S_RFC: ACTVT: 16; RFC_TYPE: FUGR; RFC_NAME: SYST, SYSU, ARFC, ERFC, EDINAuthorization object BC_ALE_RECV: EDI_MESTYP: e.g. SYSTAT,INVOIC

The component connects to the R/3 as the given user when SAPINBOUND files are sent to the R/3. Note that the user must exist for thecurrent SAP client. The SAP client is contained in the addresses SAP client field.*

Password This is the SAP log-on password.

Connection type This parameter specifies the way a connection is established for SAPINBOUND files sent to an R/3 system:

• Explicit Application ServerThe default gateway is used; the fields gateway host and gatewayservice are only used for receiving RFM.

• Explicit Application Server and gatewayBoth will be determined individually, unlike the option above (where thedefault gateway is automatically used).

• Load balancingThe message server port of the SAP system has to be added manuallyto the services file, defining the registered TCP services of theoperating system.On windows machines this file is located in <windows_home>/system32/drivers/etc.This entry in this file may look similar to this:

sapms<SID> 36<systemNo>/tcp

1.Replace <SID> with the System ID of the R/3 system.

2.Replace <systemNo> with the System Number of the R/3 system.

Application server The host name or the IP address of the SAP application server. Theapplication server may also be specified as a complete SAP router string.This field is not visible in Load Balancing mode.

System number The SAP system number (the instance number of the R/3 system). Thisnumber can be located e.g. in the SAP menu under Tools | Administration | Monitor | System Monitoring |Servers. The system number canbe determined by referring to the last two characters at the end of theindicated Gateway service.

Message server The host name or the IP address of the SAP message server. This field isonly visible in Load Balancing mode.

Group The name of the group of SAP Application Servers. The group isusually called PUBLIC, but this may not always apply. Note that the fieldSystem ID of the addresses determines the R/3 name for load balancedconnections. This field is only visible in Load Balancing mode.

This list describes all available fields; the dialog does not show all the applicable configurations.

7.2.3 Extended

This list describes all available fields; the dialog does not show all applicable configurations.

../../../../g6/3120-SEEDOC/13042-SEEDOC.html

SAP IDoc Adapter



Language The log-on language. This setting only affects the language of errormessages deriving from an R/3 system. Note that it is recommendedto use the default value (English). The component recognizes a fewconfusing error messages of the R/3 system, and replaces them withmore meaningful ones. This feature does not work with non-English errormessages.

Enable RFC trace If the RFC trace is enabled, low level log files containing information on thecommunication (RFC) with a R/3 system, are stored in the BISAS_HOME\log\run\CENTRAL directory. These log files can be used to help analyzecommunication problems with an R/3 system.

Attention: Enable this option only for fixing communication problems.

Enable SNC If enabled, the Secure Network Communications (SNC) layer is used forthe communication with R/3 systems. For information on the SNC settings,please refer to the SAP guide Secure Network Communications - SNCUser's Guide or Secure Network Communication (SNC) .

Security level The following security levels can be configured for SNC:

• Authentication

• Integrity protection

• Encryption

• Default setting of destination

• Max. available

It is recommended to select the Default setting defined in the SAPInstance profile.

Own SNC name The name returned by the sapgenpse get_my_name command has to beentered here.

Partner's SNC name The name of the R/3 application server. The value is returned by thecommand sapgenpse maintain_pk –l.

7.2.3.1 Send-side (SAP Inbound)

The next fields are file port processing parameters and are only IDoc specific.

Parameter Description

Use file port Enables/disables the file port specific configuration. Please note: Theattributes described below are relevant for file port communication only.

Port name SAP file port created with the transaction WE21. It must be set to aphysical directory and be accessible from both the SAP and the BISsystem. This is usually achieved by a network share.

Local path Local path for the file port's physical directory.

SAP-site path Path for the file port's physical directory.

File mask File mask for the SAP inbounds IDocs.

Port is Unicode-enabled Activate this option if the target file port is set to Unicode.

* This user is required both for tRFC, and the file port communication. IDocs being transferred by file port aretriggered via tRFC. This trigger uses the log-on data given here.

../../../../dtIDoc_6-3-1_en/2807-SEEDOC/4774-SEEDOC.html

SAP IDoc Adapter


7.3 Configuring Addresses

An address determines the destination of IDoc-type payload or status messages which are sent to the SAPR/3 systems. The address master data contains the settings for the creation of status IDoc messages. It alsodetermines the connection for message sending.

Settings


Connection to the SAP system Determines the connection for sending IDoc-type messages (both payloadand status messages) to the specified address.

System ID R/3 system name, aka. SID.It can be found in the SAP GUI's main menu under System | Status |Database data | Name.Note that this setting is only required for sending IDoc messages in Load Balancing mode.

SAP client R/3 system client.

This setting is used when the IDoc Connector logs on in order to send IDocmessages.

The SAP client also determines the address for receiving status confirmationmessages if the following two conditions are satisfied:

• The SAP client matches the client for the received IDocs.

• The connection matches the connection which originally has receivedthe IDoc messages.

Note: The combination of SAP client and connection must be unique.Otherwise, the data set is rejected by the BIS 6 Front-end.

Default encoding This setting defines the code page which should be used for IDocattachments with no encoding set at process level.

The IDoc Connector Client is not able to process binary attachments.This setting is only used for sending IDocs to SAP. It is ignored forreceiving IDocs.

For solving problems with encoding and Unicode code pages ingeneral, please refer to the topic Unicode and Code Page Settings.(page 42)

7.4 Configuring Registrations

The registration master data contains the settings for receiving IDocs from R/3.

SAP IDoc Adapter



Name This is a short, but unique name that describes the registration. Thisname is used in log files to associate log entries with the correspondingregistration.

Server type This is a demarcation for the created registration - if it will be used forIDoc Controller (IDOC), or for RFC Controller (RFC), but not for bothsimultaneously.

For using this registration with the IDoc Controller, the only allowedvalue for this property is IDOC. The registration will be ignored, if thewrong type RFC is chosen.

Default value: IDOC

Enabled If this option is disabled, this record is ignored at the IDoc Connectorserver's start-up.

Listener group This is the default value for the Listener group (DefaultGroup). A Listenerthat is part of the DefaultGroup will be started up on all nodes. Use theinstance ID that has been configured during the BIS 6 installation forgrouping the Listeners.

SAP IDoc Adapter


7.4.1 Settings Tab


Connection to SAP gateway This is the connection that is used to register with the SAP gateway. Thissetting also determines which address is used to send the status codes toR/3 for IDocs received by this registration.

Program ID This is the identification that is used to register with the SAP gateway.The value must match the corresponding field in the RFC Destination(TA SM59).

Number of connections This is the number of parallel connections that are used for receiving theIDocs.

If this value is changed, the IDoc Connector Server is restarted with theupdated configuration using the corresponding connection count.

Note: To be able to receive IDocs in parallel, it is also required toincrease the maximum count of connections of this RFC registrationin R/3. This is done in transaction SMQS.

Attention: When configuring this value remember the cpic_maxconvvalue described in System Requirements (page 6) part.

Max. retry interval forconnection problems(seconds)

This is the maximum time (in seconds) between two startup attempts incase of failures. The waiting time is doubled from initially 1 second aftereach startup failure until either the maximum value is reached, or theserver can be started successfully.

Example:n - configured valuex - number of attempt to reconnecty - interval for each reconnect in seconds

y = min(n, 2x-1)

Default value: 60 seconds

Example of the used retry intervals for the default value of maximum 60seconds: 1, 2, 4, 8, 16, 32, 60, 60, ...

7.5 Configuring File Port Listeners

The file port Listener master data contains the settings for receiving the IDocs from the target file port physicaldirectory.


Name This is a short, but unique name that describes the file port Listener. Thisname is used in log files to associate log entries with the correspondingListener.

Listener group The default value for the Listener group is DefaultGroup. A Listener that ispart of the DefaultGroup will be started up on all nodes. Use the instanceID that has been configured during the BIS 6 installation for grouping theListeners.

SAP IDoc Adapter



Attention: A file port listener should not be assigned to a group, ifthe local path is a directory which might be shared by more then onenode instance of this group.

Enabled If this option is disabled, this record is ignored at the IDoc Connectorserver's start-up.

7.5.1 Settings Tab


Connection for Status IDocs This is the connection name that determines, which address is used tosend the status codes to R/3 for IDocs received by this file port Listener.

Local path This is the local path for the file port's physical directory.

File mask This is the file mask for the SAP outbound IDocs. By default this mask isset to *.ido.

Note: The file port mask is case-sensitive.

Code page This is the encoding of the received IDoc files.

Polling interval (ms) This is the specified amount of time (in ms) after which the port will bescanned for incoming IDoc files again. By default the value is set to 500ms.

SAP IDoc Adapter


8 Process Configuration

8.1 Sending IDocs (SAP Inbound)

The IDoc Connector is not able to process binary attachments. Therefore it is absolutely mandatory to set anencoding for the attachment that carries the IDocs to be sent. Otherwise the task will be cancelled with a TASK ERROR.

Note: Sender and receiver will be swapped, if the diection flag in the control set of the transferring IDocis set to ‘1’ (outbound).

8.1.1 SendIDocMD

Note: SendIDocMD_v2 operation is corresponding to SendIDocMD, which is an older version and wedo not recommend it for use. SendIDocMD_v2 has an extended response and should be used instead.

The SendIDocMD_v2 operation sends an IDoc file to an R/3 system. It corresponds to the SendIDoc _v2 operation, with the exception that the configuration settings of SendIDocMD _v2 are included in the masterdata (MD), i. e. in the BIS 6 database. An IDoc file may contain a random number of IDocs of any messagetype. All IDocs of an IDoc file must be of the same IDoc version (either IDoc version 2, or IDoc version 3). Thefields of the IDocs must be set correctly. The following fields are excluded from this:

Control Record


SAP client (MANDT) Can be left empty. If the field is not empty, it is compared with the actual SAP client. In case of a mismatch, a warning is sent to the log file.

IDoc number (DOCNUM) Completely ignored by the IDoc Connector Client, since the IDoc numberis generated by the R/3 system when it receives the IDoc.

Direction (DIRECT) If the setting for the direction is set to 1 (outbound), the IDoc Connectorswaps the fields that identify the sender and receiver of the IDoc. Thisfeature simplifies the steps that are necessary to receive and send an IDocback to the R/3 system.

Receiver port (RCVPOR) This field can be left empty. If the field is not empty, its value is comparedwith the actual system ID (Note that the system ID is requested from theR/3 system, it is not determined from the master data or properties of theoperation). In case of a mismatch, a warning is sent to the log file.

If the setting for the direction is not set to 1 (outbound), direction 2 (inbound) is assumed.

SAP IDoc Adapter


Note: Swapping of sender and receiver:If the direction flag of the IDoc to be sent is set to ‘1’ (outbound), sender and receiver are swapped. Theflag remains unchanged in the physically transmitted IDoc, since R/3 automatically corrects this duringreception process. (The direction flag is located at offset: 35, length: 1 in a version 3 EDI_DC40 controlset).

Data Record


SAP client (MANDT) Ignored by the IDoc Connector Client.

IDoc number (DOCNUM) Ignored by the IDoc Connector Client, since the IDoc number is generatedby the R/3 system when it receives IDocs.

Segment number (SEGNUM) Ignored by the IDoc Connector Client. The segment numbers aregenerated by the IDoc Connector.

Settings for the operation:

Operation parameter Description

ClientId BIS logical system client

DestinationAddressId ID of the address data set that is the destination for the IDocs.

Attachments IDoc file that is to be sent. Note that exactly one IDoc file must bespecified.

Attention: The character encoding of the attachment must be set to avalid encoding. If the character encoding is not set, or is set to binary,the operation will be rejected.

TransactionIdAttention: This field is used internally. Never change this property!

This field stores the transaction ID of incomplete tRFC calls. The value ofthis field is deleted, when a tRFC call is completed.

8.1.2 SendIDoc

Note: SendIDoc_v2 operation is corresponding to SendIDoc, which is an older version, and we do notrecommend for use. SendIDoc_v2 operation has an extended response and should be used instead.

The SendIDoc _v2 operation sends an IDoc file to an R/3 system. All configuration settings for the operationare stored as operation properties. Therefore the master data is not used.

SAP IDoc Adapter



ClientId BIS/Logical System

Attachments IDoc file which is to be sent. Note that exactly one file has to be specified.

Attention: The character encoding of the attachment must be set to avalid encoding. If the character encoding is not set, or is set to binary,the operation will be rejected.

SapClient SAP client.

TransactionIdAttention: This field is internally used. Never change this property!

Transaction ID of incomplete tRFC calls. The value of this field will bedeleted after termination of the tRFC call.

queue Please refer to the topic Adapter Invocation Mode (page 31) .

Connection


User User.

Password Password.

Ashost SAP application server, this field must be left empty in Load Balancing mode.

Sysnr SAP system number, this field must be left empty in Load Balancing mode.

Gwhost SAP gateway host, this field is optional, but must be left empty in Load Balancing mode.

Gwserv SAP gateway service, this field is optional, but must be left empty in LoadBalancing mode.

Mshost SAP message server, this field must be set for using the Load Balancingmode. It must be left empty, if Load Balancing is not applied.

Group SAP message server, this field must be set for using the Load Balancingmode. It must be left empty, if Load Balancing is not applied.

R3name System ID of the R/3 system, this field must be set for using Load Balancing mode. It must be left empty, if Load Balancing is not applied.

Lang This is the log-on language, this field is optional.

Note: We recommend using the default value (English). TheIDoc Connector recognizes a few confusing error messages of theR/3 system, and replaces them with better ones. This feature doesnot work for non-English error messages.

RfcTrace This field enables low-level RFC logging. The RFC trace is disabled bydefault.

Note: If you change this value in the process, you have to executeReload Configuration of IDoc Client after deploying the changes.

snc_mode Secure network connection (SNC) mode. Applicable values:

• 0

SAP IDoc Adapter


Parameter DescriptionDisabled (default)

• 1Enabled.

snc_qop SNC security level. Range:1 ... 9.

This field is used only if SNC mode is enabled.

snc_libAttention: Do not use this field because it is deprecated. Changingthe SNC library path must be done via the User-Config file.

snc_myname SNC name. It overrides the default SNC partner. This field is only used ifthe SNC mode is enabled.

snc_partner SNC partner, e.g. p:CN=R3, O=XYZ-INC, C=EN. This field is only used ifthe SNC mode is enabled.

Configuring SendIDoc_v2

Connection Type Required Parameters in Connection

Explicit application server • user

• password

• lang

• ashost

• sysnr

Explicit application server andgateway

• user

• password

• lang

• ashost

• sysnr

• gwhost

• gwserv

Load balancing • user

• password

• lang

• mshost

• r3name

• group

8.2 Sending Status IDocs

This are the common properties for all send status operations:

Property Description

UNAME This is the SAP user name for tRFC.

ROUTID This is the subroutine (Split/Convert/Transmission).

STATXT This is the text of the status code.

STATYP This is the ABAP message type (A, W, E, S, I) in the status set.

SAP IDoc Adapter


These properties are filled by the IDoc Connector. The values for ROUTID, STATXT, and STATYP depend onthe Status value from the operations described below.

Status ROUTID STATXT STATYP

05 Conversion Conversion failed. E

06 Conversion Conversion successful. S

10 Processing rule found. S

11 Forwarding Forwarding of messagefailed.

E

12 Forwarding Forwarding of messagesuccessful.

S

14 Acknowledgement Report received. S

15 Acknowledgement No report received. E

8.2.1 SendSAPStatusReport

This is the preferred and recommended operation for sending Status IDoc messages back to R/3.Requirements: Sending Status IDoc files by using the SendSAPStatusReport operation requires a special IDocController report queue.


PreparedReportPart This part must contain a so-called prepared.

This part can be found as attachment of the initial ReceivedIDocEvent thatis generated by the IDoc Controller (xpath to this element: //ReceivedIDocEvent/initiationReportHandling/preparedReports/reportMessage).

Docnumbers List of IDoc numbers, for which a status is to be sent.

At least one IDoc number must be specified. Usually this list is generatedby the Splitter. A reference to all received IDoc numbers can also be foundin the ReceivedIDocEvent.

Status Status that is sent for the list of IDocs. Values range: 01 ...49.

REFINT (Optional) EDI Interchange name (reference to a file).

REFGRP (Optional) EDI-Message Group (reference to group).

REFMES (Optional) EDI-Message (reference to message).

SNDPOR (Optional) Sender port

RCVPOR (Optional) Receiver port

ARCKEY (Optional) Key of the external message archive (document ID in externalsystem).

StatusDateTime Date and time of the status change. The current system time and data isused by default.

8.2.2 SendSAPStatusReportSync

This operation SendSAPStatusReportSync provides in contrary to SendSAPStatusReport the feature that theprocess will wait for the response of the sending of the status IDoc sending. The status IDoc sending by SendSAPStatusReport does only prepare the sending and does not care and wait for the result of it.

SAP IDoc Adapter


If the result of the status sending is relevant and needed in the process, this operation SendSAPStatusReportSync should be used.

The parameters of the request message are identical to the SendSAPStatusReport, the response message isa plain DtResponse message with no IDoc specific information.

This is the preferred and recommended operation for sending Status IDoc messages back to R/3.Requirements: Sending Status IDoc files by using the SendSAPStatusReportSync operation requires a specialIDoc Controller report queue.


PreparedReportPart This part must contain a so-called prepared.

This part can be found as attachment of the initial ReceivedIDocEvent thatis generated by the IDoc Controller (xpath to this element: //ReceivedIDocEvent/initiationReportHandling/preparedReports/reportMessage).

Docnumbers List of IDoc numbers, for which a status is to be sent.

At least one IDoc number must be specified. Usually this list is generatedby the Splitter. A reference to all received IDoc numbers can also be foundin the ReceivedIDocEvent.

Status Status that is sent for the list of IDocs. Values range: 01 ...49.

REFINT (Optional) EDI Interchange name (reference to a file).

REFGRP (Optional) EDI-Message Group (reference to group).

REFMES (Optional) EDI-Message (reference to message).

ARCKEY (Optional) Key of the external message archive (document ID in externalsystem).

StatusDateTime Date and time of the status change. The current system time and data isused by default. The value provided for the StatusDateTime has to be invalid xsd:dateTime format as defined in the XML Schema specification andISO 8601 conventions

8.2.3 SendStatus

Note: SendStatus_v2 operation corresponds to SendStatus, which is an older version and we do notrecommend it for use. SendStatus_v2 has an extended response and should be used instead.

The SendStatus _v2 operation sends a status confirmation for a list of (received) IDocs to an R/3 system. Allconfiguration settings for the operation are contained in the operation properties; therefore the master datais not used.


Docnum List of IDoc numbers, specifying the messages for which a status is to besent. At least one IDoc number must be specified.

SapClient SAP client name.

Status Sent status for the list of IDocs. Applicable values range: 01 ...49.

Sndpr Profile of the R/3 partner who processes status IDocs. The value ofthe field Partner Number of the IDoc messages sender (SNDPRN) arecreated in order to send status codes to R/3.

SAP IDoc Adapter



Sndprt Profile of the R/3 partner who processes status IDocs.The value of thefield Partner Type of the IDoc messages sender (SNDPRT) are created inorder to send status codes to R/3.

Sndpfc Profile of the R/3 partner who processes status IDocs.The value of thefield Partner Role of the IDoc messages sender (SNDPFC) are createdin order to send status codes to R/3. The Partner Role is left empty bydefault.

StatusDateTime Date and time of the status change. The current system time and data isused by default.

TransactionIdAttention: This field is used internally. Never change this property!

The field stores the transaction ID of incomplete tRFC calls. The value ofthis field is deleted, when a tRFC call is completed.

Connection Connection setting properties; corresponding to the properties for the SendIDoc operation.

8.2.4 SendStatusMD

Note: SendStatusMD_v2 operation corresponds to SendStatusMD, which is an older version and we donot recommend it for use. SendStatusMD_v2 has an extended response and should be used instead.

The SendStatusMD _v2 operation sends a status confirmation to an R/3 system for a list of (received) IDocs. Itwidely corresponds to the SendStatus _v2 operation, but the configuration settings are specified in the masterdata.


ConnectionId ID of the connection that received the IDocs, for which the status is to besent. The combination of the connectionId and SAP client determines theaddress which is used to send the status.

Docnum List of IDoc numbers, specifying the messages for which a status is to besent. At least one IDoc number must be specified.

SapClient SAP client name.

Status Sent status for the list of IDocs. Applicable values range: 01 ...49.

StatusDateTime Date and time of the status change. The current system time and data isused by default. The value provided for the StatusDateTime has to be invalid xsd:dateTime as defined in the XML Schema specification and ISO8601 conventions

TransactionIdAttention: This field is internally used. Never change this property!

The field stores the transaction ID of incomplete tRFC calls. The contentwill be deleted after completion of the tRFC call.

SAP IDoc Adapter


8.3 Receiving IDocs (SAP Outbound)

8.3.1 ReceivedIDocEvent

The IDoc Connector sends the ReceivedIDocEvent operation to the BIS system for each received IDocmessage. The operation contains the meta data of the received IDoc messages.


ClientId BIS client with fix value 000.

Docnum List of IDoc numbers of received IDoc messages.

Attachments IDoc file containing all IDocs which have been received in the course ofthe transaction.

StatusFeedbackConnectionID ID of the connection record over which the IDocs have been received.This ID can be used to determine the address for receiving potential statusconfirmations.

SapClient SAP client (MANDT field) of the received IDocs. It can be used todecide how the received IDocs will be processed. The combination ofthe statusFeedbackConnectionID and the SAP client is usually used todetermine the address, to which status confirmations will be sent.

IdocCount Number of IDocs that are contained in the received IDoc file.

SystemId System ID of the R/3 system that has sent the IDocs. It can be used todecide how the received IDocs will be processed.

PreparedReport This part can be used for the SendSAPStatusReport operation.

For more details, see the topic Send SAP Status Report (page 27).Xpath of this element: ReceivedIDocEvent/initiationReportHandling/preparedReports/reportMessag

8.4 Fault Messages

8.4.1 DtFault

The SendIDoc, SendIDocMD, SendStatus, and SendStatusMD operations return an error response, if theoperation cannot be carried out. The error response contains useful information on the error. The SendingStatus field must be considered in order to guarantee that an operation is performed exactly once: If the sendingStatus is NOT_TRANSMITTED, it is safe to either retry the operation, or to discard the operation. If the sendingstatus is MAYBE_TRANSMITTED, then the operation must be retried until the operation succeeds.

SAP IDoc Adapter



FaultId This field is not supported. Therefore it is always set to none.

FaultDescription This is a short non-technical description of the error.

FaultDetail This field contains the technical description of the error. Usually thisdescription also contains the context of the error. This field is not alwaysavailable.

FaultStackTrace This field contains the program context where the error occurred. Thisinformation helps the SEEBURGER technical staff to quickly providesolutions, if there are unexpected problems with the IDoc Connector.

FaultTime This field contains the time when the error occurred.

FaultCategory This field is either set to COMPONENT_ERROR, if it is unlikely that theerror derives from a configuration error. Or TASK_ERROR/CONFIGURATION_ERROR, if the operation’s configuration is likely to be wrong. Theoperation will not succeed, unless the configuration is changed by theuser.

Retryable This field is set to true, if the operation may succeed when it is retried. Thefield is set to false, if the error is likely to be of a permanent nature.

Fatal This field is not supported. Therefore it is always set to false.

SendingStatus This field is either set to MAYBE_TRANSMITTED, if the IDoc file, orstatus IDocs may have been received by a R/3 system. In this case, theoperation must be retried to guarantee that the IDocs are received exactlyonce. Or NOT_TRANSMITTED, if the IDoc file, or status IDocs havedefinitely not been received by a R/3 system.

8.5 Adapter Invocation Mode

There are different invocation modes in which the orders can be forwarded to the adapter. The mode isconfigured using the destination or queue part within the outbound operations.

For details about the differences of the invocation modes please refer to the topic 'Adapter Invocation' in themanual 'Master Adapter Configuration Guide'.

Note: If the destination/queue part is empty, the order is executed in WLH mode.

Following three invocation modes are supported by this adapter:

8.6 Direct Invocation

The direct adapter invocation (direct mode) is used to forward orders from the process engine to the adapter.A JMS queue is used to queue the orders until the adapter is ready to handle them.

• The direct mode supports order retry handling in case of an adapter error. Independent from the errortype the order is retried based on the queue configuration.

• It is possible to connect more than one adapter to one single queue.

The direct mode can be configured over the Worklist Handler GUI. There you can directly create queues andassign nodes. Please refer to the topic Direct Mode GUI for details.

SAP IDoc Adapter


When defining a process, you have to specify a particular queue/destination name to be used. Use async: for the queue/destination part in the request (note the colon). After the colon, enter the corresponding JMSqueue's JNDI name (e.g. async:queue/ftpTestQueue).

If only async: is entered, the default queue to <PortType> is used (e.g. toDtFTPComponent). This is therecommended usage for simple architectures, since this method does not require adapter configuration andqueue definition.

Limitation: Orders relying on hardware resources like ISDN, X.31, or X.25 cannot be used with thedirect invocation since no resource management is available. Use the WorklistHandler integrationinstead.

Note: Up to version 6.3.3 direct: was used instead of async: to specify the queue/destination. You canstill use the direct: parameter.

Note: An error of the type Line-Busy does not increase the retry count of the order.

8.7 Synchronous Adapter Invocation

Beside the Direct Adapter Invocation there is the Synchronous Adapter Invocation.

This invocation method is the fastest, however is not recommended for each use case. There is no queuebetween the process and the adapter. Instead the adapter is executed synchronously from within the businessprocess. The process does not commit the transaction as it does with asynchronous invocation, meaning it willdo a blocking wait until the adapter/module has finished its work.

This invocation mode is only recommended for short running operations which will not block one of the processthreads for a long time, because there is a limit for maximum simultaneously executed processes. Also thereis no retry handling for such processes. If there is an error the adapter returns to the process immediately.

The synchronous invocation can be configured using the queue/destination part.

Syntax Description

sync: The operation is executed synchronous on any running instance.

sync:instanceid=MY_INSTANCE

The operation is executed synchronous on the node with instanceID "MY_INSTANCE".

sync:nodegroup=MY_GROUP The operation is executed synchronous on any running node of the nodegroup "MY_GROUP".

Limitation: Orders relying on hardware resources like ISDN, X.31, or X.25 cannot be used with thedirect invocation since no resource management is available. Use the WorklistHandler integrationinstead.

8.8 Worklist Handler

The SEEBURGER Worklist Handler provides an additional queuing functionality for the system (refer to thetopic Adapter Invocation for another strategy).

The Worklist Handler accepts orders and can place them in different queues. Each queue can be assigned toone, or more adapters to which the orders can be sent. The queue in which the order is placed thus determinesto which adapter it can be sent.

SAP IDoc Adapter


In contrast to the Direct Adapter Invocation the queue configuration and the order dispatching can be configuredto a more complex scenario. It supports for example polling of orders, dynamic retry handling, and resourcehandling.

To configure the process to use a WLH queue, just enter the name of the queue in the queue part of theoutbound operation.

For details about this invocation mode please refer to the topic 'Adapter Invocation' in the 'Master AdapterConfiguration Guide'.

SAP IDoc Adapter


9 Extended Features

9.1 Status IDoc Handling

There are two ways to create status IDocs for a received IDoc. The first (and strongly recommended) one is touse the Status IDoc template generated by the IDoc Controller. The second one is to use one of the operationsSendStatusMD, or SendStatus. In this case the connection ID has to be assigned from ReceivedIDocEvent/statusFeedbackConnectionID to SendStatusMD.connectionId (or even the complete master data (in case ofusing the SendStatus operation).

9.1.1 Using the Generated Status IDoc Template

This is the preferred and recommended operation for sending Status IDocs back to R/3.

Prerequisites

To be able to send Status IDocs using the SendSAPStatusReport/ SendSAPStatusReport Sync operations, aspecial IDoc Controller report queue is necessary. This queue is created automatically by the IDoc Controllerthe first time when an IDoc is received. The newly created queue (named IDocController-ReportQueue) mustthen be assigned to the appropriate IDoc Client node, which should send the Status IDocs back to the R/3. Ituses a so-called prepared report part, which contains a Status IDoc template. The template can be used duringthe processing of the originally received IDoc in order to return different status reports to the R/3.

9.1.2 Queue for Status IDocs

If sendSAPStatusReport or sendSAPStatusReport Sync operation is used, a special queue is generated forthese status IDoc templates. The queue will automatically be created when receiving the first IDoc from theR/3, but it can also be created manually. The queue must match the following naming convention:

<node caption>-ReportQueue

The name is case-sensitive. The node caption of the receiving server is IDocController per default, i.e thedefault name of the queue is IDocController-ReportQueue.

Note: Though this queue is created automatically, it has to be connected to the correspondingIDoc Connector Client manually.

9.1.3 Generation of Status IDocs in a Process

The operations sendSAPStatusReport/ sendSAPStatusReport Sync can be used at every stage ofa process that has been initiated by a ReceivedIDocEvent. The ReceivedIDocEvent message part

SAP IDoc Adapter


has a special attachment (ReceivedIDocEvent/initiaionReportHandling/preparedReports/reportMessage) thatcarries a template status IDoc request. This attachment only has to be assigned to SAPSendStatusReportMessage/preparedReportPart/AttachmentRef. So the sendSAPStatusReport-component is able to generate astatus IDoc using this template.

This is in short what has to be assigned when using these operations:

• Assign the prepared report template of the ReceivedIDocEvent (path: /ReceivedIDocEvent/initiationReportHandling/preparedReports/reportMessage) to the preparedReportPart of the sendSAPStatusReport (path: /SAPSendStatusReportMessage/preparedReportPart/AttachmentRef).

• Assign all the docnumbers of the received IDocs (path: /ReceivedIDocEvent/docnum" to the"sendSAPStatusReport (path: /SAPSendStatusReportMessage/docnumberPart/docnumbers).

• Assign the status (e.g. 10) to /SAPSendStatusReportMessage/statusPart.

9.2 Customizable RFC Trigger Function for FileportCommunication

Attention: The custom triggers are only applicable with file port communication!

The IDoc Client can communicate (send SAP Inbound IDocs) with R/3 in two ways:

• Send an IDoc via tRFC directly to a tRFC port in R/3

• Copy the files to a file port (usually a mounted network share of a R/3 directory) and then trigger theEDI_DATA_INCOMING function.

The EDI_DATA_INCOMING trigger uses the parameters PORT and PATHNAME. This functionality has beenextended. It is possible to call a custom RFC function with dynamic list of parameters.

Configuring the Trigger

Note: The customization of the trigger function is only possible with the SendIDocMD operation.

Configuring /SendIDocMDReq/fileportTrigger Element


functionName (Mandatory)Name of the custom trigger.

functionParameter (Mandatory, at least one function parameter must be entered)Array of function parameters. Each parameter has a name, a value and alength.

indexOfPathnameParameter Index showing the function parameter which identifies the remote SAPside path. For the file port communication, it is required to have thispath. If no value is added in this field, the first function parameter will beconsidered to be the path.

The index count starts with 1 and corresponds to the index of thefunction parameter elements in the process.

SAP IDoc Adapter


Configuring /SendIDocMDReq/fileportTrigger/functionParameter[n]


parameterName (Mandatory)Name of the function parameter.

parameterValue Value of the specified parameter.

maxParameterLength Maximum allowed length for this parameter.If no value is specified, the default value (255 characters) will be used.

The value of the function parameter carrying the remote SAP side path, can be entered in two ways:

• <REMOTE_DIRECTORY_PATH>/*for the files without extension.

• <REMOTE_DIRECTORY_P ATH>/*.<ext>for the files with extension.

To avoid performance problems, the IDoc Client has a special function repository for custom triggers. After thefirst call, the function is loaded in the repository and then re-used. If the dynamic list of parameters for a loadedfunction is changed during runtime, the new process (the one with the changed parameters) will finish with a LINE_BUSY error, until the old function is no longer used. Then the new one is loaded, and the returned processinstances (LINE_BUSY error) finish their execution with success.

9.3 Connection Pool

Note: The Connection pool is only used by the SAP Clients integrated in the BIS 6 environment.

JCo supports two programming models for connecting to SAP: Direct connections, which you create and holdon to as long as you want, and connection pools, from which you can take a connection when you need it, andto which you return it as soon as possible so that others can use it.

There are two benefits associated with using connection pools:

• Avoiding the overhead of logging on to SAP, because once the log-on has happened, the connectionstays open and can be re-used (JCo will close an idle, non-acquired connection in a pool after theconnection timeout period has expired).

• Limiting the maximum number of connections used concurrently, thus preventing the use of too manySAP resources.

The size of the connection pool can be configured via the Control Center | IDoc Client Configuration tab. Thedefault value is 20. I.e. 20 connections can run in parallel for one connection pool.

Attention: Be careful not to create a performance bottleneck by making the maximum number ofconnections too small, and thus creating waiting situations for your processes. Increase the pool sizewith caution, since it might lead to a heavy load peak in R/3.

Attention: If you use the DIRECT mode for sending an IDoc, keep in mind that the default maximumload of parallel jobs is 20. It is recommended to decrease this setting, instead of increasing the JCopool size in this use case.

Note: If a LINE_BUSY error is returned with the message stating that the pool is exhausted, you caneither decrease the parallel number of jobs, or increase the increase the pool size. Keep in mind thewarning concerning the DIRECT mode above.

SAP IDoc Adapter


A JCo connection pool is identified by its name and is global within the Java Virtual Machine (JVM). Allconnections in a pool use the same system/userid/client information. The IDoc Client uses the following namingconventions:

Connection Type Pool Name Form

Explicit Application ServerExplicit Application Server andGateway

ashost_user_client

Load Balancing r3name_user_client

The connection pool also provides some features for dynamic monitoring. The JCo transfer time and the JCosent bytes per connection can be viewed in the process response.

SAP IDoc Adapter


10 Adapter Configuration

10.1 Dumping

The dumping feature is for debugging purposes only. It dumps the complete IDocs, both sent and receivedones, to a file. The IDocs are dumped as close as possible to the JCo implementation. That means, the IDocsare dumped as they are passed to JCo (SAP inbound communication), or received from JCo (SAP outboundcommunication). No further processing/parsing is done between dumping the file, and passing it to JCo.

The files are named as follows:

SAP Outbound (received by IDoc Connector Server):

• IN_<Name of the registration data set>_<GMT timestamp>_<UUID>.idoc

Example: IN_XIDregistration_20051208T123609.670Z_UID35b03e60-67e7-11da-9b9b-76a60a0067ba.idoc

SAP Inbound (sent by IDoc Connector Client):

• If master data is used for sending:

OUT_<Name of the connection data set>_<Name of the address data set>_<GMTtimestamp>_<UUID>.idoc

• If no master data is used:

OUT_<application or message server>_<MANDT>_<RFCuser name>_<GMTtimestamp>_<UUID>.idoc

Example: OUT_XIDconnection_XIDaddress_20051208T135336.982Z_07b3c760-67f2-11da-a234-fb0d0a0067ba.idoc

The files are dumped to bis6_home/data/dt/idoc/dump by default. This directory is configurable. The dumpingis activated for both client and server via the .

SAP IDoc Adapter



TransmissionDataDump This property is used to switch the dumping on/off.

DumpDir This is the directory where the files are dumped to.

IDocDumpCodePage This is the code page used to write IDocs to a file, platform encoding isused as a default.

Attention: The dumping decreases the adapter throughput. Deactivate the dumping as soon aspossible.

10.2 Logging

Further information concerning the common logging configuration please refer to the topic Logging/Tracing/Dumping of the Master Adapter Configuration Guide.

10.2.1 JCo Logging

The logging for the Java part of JCo is configured via the configuration property jcoLogLevel (please refer tothe topic Extended Configuration Flags (page 39) for details). The output of this logger is merged to thelog file that is used by the client or the server.

10.2.2 RFC Tracing

The logging of the native part of SAP JCo (platform dependent libraries) is configured over environmentvariables.

Variables Description

RFC_TRACE_DIR This variable defines the location for the RFC trace files. If the directorydoes not exist, nothing is logged. If this variable is not set, the workingdirectory is used.

RFC_TRACE_DUMP If this variable is set to 1 (default is 0), the complete payload is dumped.(Really big trace files are generated!).

RFC_MAX_TRACE This variable sets the maximum file size in megabytes. Default: 8 MB.

RFC_TRACE If this variable is set to 1 (default is 0), the RFC trace is enabled for allconnections. The flag is configured in the master data connection settingsfor each connection separately. This is a global flag.

If the adapter is operated on the application server (central instance), the log files are saved in the BIS6_HOME/log/run/CENTRAL directory, which is the location of the application server's start directory. If the adapter isoperated as a node (Tomcat), the log files are saved in the NODE_HOME/bin/ directory.

Note: The connection errors are always logged, even if the trace is disabled.

Attention: The RFC tracing should be disabled as soon as possible.

10.3 Extended Configuration Flags

These flags are set in the configuration tab of the Adapter Control Center details section. This details sectionis shown by doubleclicking the respective adapter.

SAP IDoc Adapter


Property Explanation Values Available for

ExtendedJcoLogging This flag activates theJCo logging. The JCologging is written inthe log file of the IDocConnector.

Note: To get JCologs, you have torun the generallogging of theadapter at least onthe DEBUG level.

True/false; default: false Client/Server

JcoLogLevel This property definesthe log level for the JCOlogging.

Note: JCo Loglevel is a staticproperty for therunning VM. Thelast value is usedfor all componentsusing JCo traces.

Note: Startingwith level 6 thememory usageincreases rapidlyand there are alsobig performancehits caused by thedumping of theIDoc content. It isnot recommendedto run levels >=6 in a productiveenvironment for alonger time.

0 (no log) to 8 (max log);default: 5

1 - ERROR_WARNING

2 - PATH_API

3 - FULL_PATH

4 - INFO_PATH_API- JCo connection poolactivity can be seen atthis level; destination andserver data events;

6 - INFO_PATH - thecontent of the transferredIDoc tables is dumped;

7 - SHORT_DEBUG

8 - FULL_DEBUG -dispatchers' logs;

Client/ Server

SncLibPath This is the full path to theSNC library.

Note: Changingthis value needs anadapter restart forthe native librariesto reinitialize.If the path isnot existing oraccessible, this is aconfiguration errorand will be reportedas this.

[string]; default:%bisas.home%/lib/native

Client/ Server

SAP IDoc Adapter


Property Explanation Values Available for

ConnectionPoolSize This property defines theconnection pool size. Formore information referto the topic Connectionpool (page 36) .

default: 20 Client

ConnectionPoolTimeout This property defines theconnection timeout.

[minutes]; default: 5min Client

ShowPass This property logs theconnection password inclear text.

True/false; default: false Client

UseSAPNativeUTF16Codepage

This property should beused only, if there areproblems with the defaultUTF-16 code page ofreceived IDocs files. Thiscode page uses a byteorder mark, which maycause problems withsome mappings.Setting this property totrue will force the IDocController to use codepage without a byteorder mark. The codepage will be equal tothe application servercode page number of therespective SAP system.

Code page number4102 at SAPsystem will createUTF-16BE IDocsin BIS; 4103 willcreate UTF-16LErespectively. Seechapter Unicodeand Code PageSettings (page42) for details.

If this featureis enabled andtherefore the SAPApplication ServerCode Page isused for receivedIDocs, changing thecode page at SAPsystem (e.g. dueto an upgrade orreinstallation) willalso change thecode page of thereceived IDocs inBIS 6.

True/false, default: false Server

SAP IDoc Adapter


10.4 Unicode and Code Page Settings

10.4.1 Unicode Code Pages

10.4.1.1 General Information

For communicating with Unicode-enabled SAP systems by IDoc files, the UTF-16 code page is used.

Internally, the UTF-16 code page is a 2-byte character set, which means that each character consists of 2bytes. For example the ASCII character 'A' is encoded as 0x00 0x41 in UTF-16 Big Endian (UTF-16BE) or0x41 0x00 in UTF-16 Little Endian (UTF-16LE). The endianness (LE/BE) describes the technical order howthe 2 bytes have to be read to get the character 'A' again.

There are two rules how the endianness of a UTF-16 encoded character can be determined.

The first, more user-friendly way to indicate the endianness of a UTF-16 file is to use a special character, a so-called Byte Order Mark (BOM). Using a BOM the byte order needs not be known to the user as the programcan determine the byte order implicitly by reading and interpreting the BOM at the beginning of a Unicode file.

The second way does not use a byte order mark but the byte order is defined explicitly by the code page namecontaining it. Then the code pages UTF-16LE or UTF-16BE are used.

The code pages named UTF-16BE and UTF-16LE do NOT use a Byte Order Mark.

In contrary, the code page named UTF-16 MUST contain such a Byte Order Mark.

In UTF-8 a byte order mark may be used.

The table below shows the byte order marks and how they appear in HEX and in a normal, non-unicode-awareeditor at the beginning of a file:

Code Page Name Byte Order Byte Order Mark (HEX) Byte Order Mark(readable characters)

UTF-16 BE 0xFE 0xFF ÿþ

UTF-16 LE 0xFF 0xFE þÿ

UTF-16BE BE --- ---

UTF-16LE LE --- ---

UTF-8 --- 0xEF 0xBB 0xBF ï»¿

For further information on Byte Order Marks, see unicode.org .

10.4.1.2 IDoc Connector specific information

The default code page for Unicode IDocs received from SAP by tRFC is UTF-16 (with a BOM at the beginningof each file).

The default code page for Unicode IDocs received from SAP by File Port is UTF-8 (without a BOM).

In most cases tRFC is used to transfer IDocs from SAP to BIS. In this scenario the BOM at the beginning ofsuch received IDocs sometimes causes problems during the further processing, e.g. in a BIC mapping with ahard-coded, non-BOM code page UTF-16LE or UTF-16BE.

http://www.unicode.org/faq/utf_bom.html

SAP IDoc Adapter


For such a case the IDoc Controller is able to remove the BOM. This is achieved by switching from the defaultcode page UTF-16 (with a BOM) to a non-BOM code page UTF-16BE/UTF-16LE. Which of the two non-BOMcode pages is effectively used, depends on the code page that is installed at the connected SAP system. TheSAP code page number 4102 is mapped to UTF-16BE, 4103 is mapped to UTF-16LE in BIS 6). See chapterExtended Configuration (page 39) on how to enable this feature.

The specifics of handling unicode-encoded files for both IDoc Connector Client and IDoc Connector Controllerare described in this table:

Code page IDoc Connector Client IDoc Connector Server Remarks

UTF-16 (default codepage)

The IDoc message mustbe prepared with theappropriate BOM forsending. Otherwise, noparsing is possible.

UTF-16 is the defaultcode page IDocConnector uses forreceived Unicode IDocs.The post-processingsteps (e.g. mapping)must be BOM-aware.

Do not use hard-codedsource encoding settingsin mappings.

UTF-16LE/ UTF-16BE The endianness isimplicitly determined bythe very name of thecode page; therefore filesin this encoding mustnot have a BOM at thebeginning.

These code pagesare used for receivedIDocs when the extended settingUseSAPNativeUnicodeCodepage is enabled (page39). The endiannessdepends on the installedcode page at SAP (TASNL1).

These code pagesalways need to providethe used endiannessexternally, as there is noBOM that may be usedfor implicit determination.

UTF-8 without BOM 8-bit characters must beencoded with two or morebytes.

No BOM at thebeginning.

This code page isnot used for RFCtransmission.

Unicode IDoc messagesreceived via file port aremostly UTF-8 encoded.

UTF-8 with BOM The BOM cannotbe skipped by theIDoc Connectorclient. Therefore, theparsing (and sending)corresponding IDocmessages fails. (Errormessage: IDoc containsa data record where acontrol record is required.Near line 1 (IDoc number x)).

Remove the BOM beforesending UTF-8 files.

SAP is able to create fileswith a BOM. The IDocConnector server cannotskip the BOM, therefore itis also recommended toremove the BOM beforesending those files to BIS6.

The UTF-8 BOMcomprise the followingcharacters: 0xEF 0xBB0xBF (looks like this inASCII: " ï»¿ ").

10.4.1.2.1 IDoc Connector Client: Default Encoding

The IDoc Connector Client default encoding is used for IDoc attachment which should be sent to SAP thatdo not have an explicitly defined code page. It is configured in the SAP Address master data (page 19). Thissetting is not relevant for receving IDocs with IDoc Connector Controller.

SAP IDoc Adapter


10.4.2 Unicode Settings in SAP

10.4.2.1 Registration settings

If the SAP system, where BIS6 IDoc Controller connects to, has a Unicode kernel, in Transaction CodeSM59 the Unicode mode must also be enabled.

For the communication with Unicode systems, it is absolutely necessary that the Unicode mode is used,and that the character width in the target system is set to Unicode in TA SM59. Always perform theUnicode test in TA SM59.

If BIS 6 registration are configured as non-Unicode at a Unicode SAP system, the following error stringcan be seen at BIS 6 after receiving an IDoc: "IDoc contains a data record where a control record isrequired. Near line 1 (IDoc number x)"

Non-Unicode communication with Unicode systems is not supported by SAP Java Connector, which is usedby BIS6 IDoc Connector. This type of function would not make sense because Java is always based on an Unicode character set. For more information on this particular topic see the SAP note 701043

10.4.2.2 Determining the Code Page of a SAP System

To definitely determine the used Application Server Code Page of a SAP system, the transaction code SNL1.

In old SAP releases it may be needed to execute SNL1 and execute a report to see the needed result: InSNL1 choose menu "CodePages" --> "Application server codepages" --> "execeute" button: see parameterCODEPAGE in return list.

If the SAP system is Unicode-enabled, the code pages 4102 (UTF-16BE) and 4103 (UTF-16LE) areused as Application Server Code Page.

The front-end code page (GUICP in SNL1) is most likely 4110 (UTF-8). This code page is also used whencommunication by a File Port with SAP.

SAP is able to deal with BOMs since release 6.20. It is possible to skip, check for and generate BOMs in IDocsusing special ABAP functions. See SAPNote 788449 for details.

10.5 Memory Requirements

The IDoc Connector client and the IDoc Connector server require a significant amount of memory for properoperation. The required memory depends on the number of records of all IDocs that are transferred within asingle transaction.

The following table illustrates the amount of memory that is required by the IDoc Connector client and theIDoc connector server depending on the number of transferred records, if they are running on the MicrosoftWindows operating system.

No. Records of the

transferred IDocfile

Overall Java Heap Memory in [MB]

Unicode Non-Unicode Unicode Non-Unicode

Receiving IDocs from R/3 Sending IDocs to R/3

1 8 19 18 18



SAP IDoc Adapter


No. Records of the

transferred IDocfile

Overall Java Heap Memory in [MB]

Unicode Non-Unicode Unicode Non-Unicode

1.000 20 20 31 28

5.000 71 58 79 65

10.000 107 72 129 104

20.000 194 136 242 179

30.000 276 188 371 243

40.000 358 240 464 326

50.000 463 313 531 395

60.000 522 344 627 474

80.000 686 448 836 614

100.000 875 578 1011 770

120.000 1014 656 1231 913

150.000 1309 804 1491 1135

n 0.0082n + 29.801 0.0052n + 31.447 0.0096n + 51.265 0.0074n + 24.66

No. Records of the Transferred IDoc File

This column gives the number of records of all IDocs that are transferred at a particular time. That is: Thenumber of lines of an IDoc file multiplied by the number of transactions running in parallel. The maximum loadsetting of the IDoc Connector client node determines the number of parallel transactions when sending IDocsto the R/3. Respectively, the number of connections in the registration master data of the IDoc Connectorserver multiplied by the number of (active) registrations determines the number of parallel transactions whenreceiving IDocs from the R/3.

10.5.1 IDoc Connector Client Memory Management

To avoid uncontrolled out-of-memory situations, the IDoc Connector client has a possibility for memorymanagement. The client memory management can be (de)activated via the Adapter Control Center.


ActivateMemoryCheck The flag for the activation of Memory Management. By default the MemoryManagement is activated.

BasicLoadValue This is the value for the basic memory load of the server. The defaultsize is 520MByte. This value corresponds to an idle JBoss server with allDT adapters running idle, too. The basic load value is checked, also atadapter runtime (please refer to the topic Determination of the ServerBasic Load (page 46) ).

SecurityBuffer This is a relative factor defined as a percentage value based on theavailable heap for transaction. The minimum recommended size is 5%.

When the memory management is activated, a virtual memory pool is created. The pool size is determinedas follows:

Virtual memory pool = the Xmx parameter – basic load value.

The determination if an IDoc can be sent with activated memory check is based on two constraints:

SAP IDoc Adapter


• Enough heap space must be available. The needed memory for sending an IDoc must be smaller thanthe total available memory for usage (virtual memory pool size – n% of the pool size, where n% is thesecurity buffer value). If the needed memory is bigger than the available memory for usage, the order willbe rejected with a non-re-triable error. The IDoc is not processable on that system, and will have to besplit in smaller parts.

• Enough free heap available in the memory pool. The required memory for sending an IDoc must besmaller than the current virtual memory pool size – n% of the pool size, where n% is the security buffervalue. If the current available heap is too low at the moment, the order is returned with LINE_BUSY error(Worklist-Handler retry count remains unchanged), and will retry until it succeeds.

10.5.1.1 Determination of the Server Basic Load

To prevent operation of the IDoc Connector client with a non-optimal basic load, the value is recalculated atadapter runtime.

• Adapter start up: The basic load value is calculated, and then compared with the one in UserConfiguration. The smaller value is used for the initialization of the memory pool.

• Periodically: The IDoc Connector client is scheduled to check the basic load value, and to reconfigure thememory pool every 4 minutes with some additional conditions:

1.The adapter is idle, i.e. there is no running task at that time

2.The new basic load value is smaller than the old one. When these two conditions are met, the memorypool is reconfigured.

The runtime determination of the basic load is helpful for the following reason: The default basic load valuein the User Configuration file is 520Mb. This value corresponds to an idle JBoss server with all DT adaptersrunning idle, too. But when the IDoc Connector client is running idle on an external node (recommended), thebasic load value is only 270Mb. With the runtime determination, the memory pool size will always be optimaleven without changing the User Configuration file.

10.6 Configuration within R/3

This topic describes in short words what to configure, and which transactions to use to communicate withIDoc Connector.

10.6.1 Creating a Minimum Authorization Profile for an RFC User

This topic is based on SAP Note 460089 and describes how to create a new role with an underlying dedicatedminimum authorization profile for the RFC communication between an external program (i.e. the IDoc ClientConnetor) and an SAP system. We strongly recommend to apply such an authorization profile.

For sending IDocs to an SAP system it is sufficient to create a user of type "Communication" (SAP transactioncode (hereinafter referred to as TA) SU01). No dialog user is needed, unless you want to debug a calledprogram in SAP.

The minimum authorization profile for RFC communication can be defined according to the followinginstructions. The steps to create a role may be omitted if an existing role/profile is adapted only. If this is thecase, the steps 1 to 3 can be skipped.

1.Use TA PFCG to start the Role Maintenance.

2.Create a new role /SEEAG/RFCCOMM


SAP IDoc Adapter


3.Define a description and save the role for the first time.

4.Click on the button Change Authorization Data and do not select a authorization profile template if youare prompted.

SAP IDoc Adapter


5.Click on the button Manually to add a manual selection of authorizations.

6.Add the authorization object S_RFC and B_ALE_RECV to the list.

SAP IDoc Adapter


7.Expand the tree.

8.Edit the S_RFC object:

• Set Activity (ACTVT) to Execute (16).

• Set Type of the RFC object to be protected (RFC_TYPE) to Function Group (FUGR).

• Set Name of the RFC to be protected (RFC_NAME) to:

• SYST

• SYSU

• ARFC

• ERFC

• EDIN

• <maybe additional name of the RFC function module configured for processing in the partnerprofile (TA WE20)>

Note: If the function module name behind the process code in WE20 partner profile uses furthermodules than EDIN, simply send a test IDoc using a user assigned to this newly created role and checkfor the error message in SEEBURGER BIS (or in SAP system trace TA ST01).The error message could look like this:RFC_ERROR_SYSTEM_FAILURE: User <RFCUserName> has no RFC authorization for function

group <your group> .

9.Edit the BC_ALE_RECV object. Here the allowed message types to be received can be defined. If you donot want to define a restriction, simply choose *, otherwise e.g. add SYSTAT for receiving status IDocs.

10.Save the profile.

SAP IDoc Adapter


11.Generate the profile.

12.Assign the RFC user to the newly created role in tab User. Make sure that the user does not have anyother role or authorization profile assignments (use TA SU01 again to verify the assignments).

13.Start the user comparison.

SAP IDoc Adapter


14.The profile may now be used by the assigned users.

10.6.2 RFC Destination

A RFC Destination must be configured in order to receive IDocs from a R/3 system. A RFC Destination is notrequired, if it is only necessary to send IDocs to a R/3 system.

The RFC Destination has the T (TCP/IP connection) connection type, and its activation type must be set toRegistered Server Program.

The following steps describe how to create a RFC Destination:

1.Go to the transaction SM59.

2.Click on the button Create (F8).

3.Enter the name of the RFC Destination, for example SEEBURGER.

4.Enter an arbitrary description of the RFC Destination.

5.This description is mandatory for some releases of R/3, for others it is optional.

6.Select the Connection Type T Start an external program via TCP/IP.

7.Click on the button Save (Ctrl+S).

8.Select the Activation Type Registered Server Program. The Activation Type is called Registration insteadof Registered Server Program, for some releases of the R/3. If the Activation Type cannot be set in thedialog, make sure that the current entry has been saved.

9.Enter the Program ID, e.g. <hostname>.sapconnector.

10.The Program ID must be identical to the field program ID in the registration master data. In the caseof complex scenarios, to ensure that the program ID is unique, it is recommended to include thedestination’s host name in the program ID.

11.Enter the gateway host and the gateway service (usually sapgw00) in the Gateway Options. This step isoptional, depending on the configuration of the R/3 system.

12.The Gateway Options are only accessible over the Destination | Gateway Options menu, for some R/3releases.

SAP IDoc Adapter


13.Check if the RFC Destination is correctly configured, and that the network is fully functional.

14.Create the registration master data.

15.Click the button Test connection (F8) to test the connection.

16.If the R/3 system supports Unicode, click Unicode test (F5) to test whether the Unicode settings arecorrect.

Note: If the target R/3 system has Unicode support, it is not possible to operate in non-Unicode mode. Non-Unicode mode is only possible for systems that do not support Unicode at all.

For the communication with Unicode systems, it is absolutely necessary that the Unicode mode isused, and that the character width in the target system is set to Unicode in the target system in SM59.Non-Unicode communication with Unicode systems is not supported by the JCo. This type of functionwould not make sense because Java is always based on an Unicode character set. For more informationplease refer to the SAP note 701043 .

10.6.3 Status Processing

In order to process status IDocs, a process code for the STATUS message type must exist in the partnerprofiles. To add a process code for status IDocs in the partner profile perform the following steps:

1.Go to the transaction WE20.

2.Create a new Partner Profile (press F5), or open an existing one.

3.Create a new inbound parameter (click the button Create inbound parameter).

4.Optionally enter a value for the Partner Role. This value must be identical to the Partner Role field in theaddress master data.

5.Set the Message Type to STATUS.

6.Depending on the R/3 release, select the process code STA1 or STA2 (Status Record from IDoc).

10.7 Batching IDocs in R3

10.7.1 Scenario Description

There are several use cases where collecting and batching of IDocs in R/3 is reasonable. These scenarios willbe described shortly here, and the user will be given some hints concerning the configuration.

The immediate SAP outbound sending of IDocs to an ALE application (e.g. BIS 6 IDoc Controller) is thefastest way of sending information to a partner. The IDoc is received by the IDoc Controller and is immediatelyforwarded to the BIS 6 Integration Engine (with subsequent conversion and forwarding of the IDoc).

But this immediateness can be a problem for the receiving partner, because the IDoc files are all processedin different conversion/forwarding processes by the BIS 6 Integration Engine. This e.g. results in many shortEDIFACT interchanges (one for each process/received IDoc) between BIS 6 and the communication partner.

To avoid this, the IDocs should be collected in R/3 and being forwarded to BIS 6 in individual periods. Thishas two advantages for the user: Firstly the tRFC communication will get more efficient, if several IDocs arealso processed in a single tRFC call and the number of invoked processes in BIS 6 is reduced. The secondobvious advantage for the recipient of the converted IDocs is the significantly reduced number of EDIFACTinterchanges, since the files can be converted and processed in larger packets.

Another advantage of collecting IDocs in the R/3 is the individual time of processing IDocs of an individualpartner. A general collection interval in BIS 6 would have the disadvantage that all IDocs (regardless of thepartner) would be processed using the same interval. By collecting the IDocs for each partner, the packet sizeand batching interval can be configured individually.


SAP IDoc Adapter


10.7.2 Configuration in R3

In the Partner Profile (WE20) all needed outbound parameters (message types) of a partner have to beconfigured.

1.Select an outbound parameter message type, and click the View button, then set it to editable.

2.Configure the packet size, and select Collect IDocs (output mode 4) in the output mode box.

Keep in mind that an extensive size may cause trouble in sending this packet, because it might become toobig, and the tRFC transmission could run into a timeout. The report RSEOUT00 should be scheduled as batchjob (perhaps using a variant for a certain port, or partner), in order to trigger the status 30-IDocs periodically.

10.7.3 Testing

Using the test transaction WE19 it is applicable for collecting IDocs (status 30). Start a standard outboundprocessing and unselect the flag start IDoc outbound processing immediately in the dialog box. The IDocs willbe created, and are ready to be sent (status 30) afterwards. By starting the report RSEOUT00 (SE38) theseIDocs can be triggered for outbound processing to BIS 6.

This report triggers all available IDocs, disregarding the configured packet size in that way that even if theavailable IDocs are less than the configured packet size, they will be sent in an accordingly smaller packet.This also applies for numbers of available IDocs (e.g. 102) that exceed the packet size (e.g. 50). There willbe created two full packets with 50 IDocs, and the last transmission will transport the remaining (here: theremainder of 102 mod 50 == 2) IDocs.

SAP IDoc Adapter


11 Monitoring

11.1 Adapter Monitor

The IDoc Connector client and the IDoc Connector server inform the DT-Monitor of their current status, andabout errors that occurred in the component. The current status contains a short description of what thecomponent is currently doing, and a counter that counts how many tasks the component has processed sincestartup. The DT-Monitor provides a snapshot of the component's status, and a history of all reported errors.

In general, the IDoc Connector client and the IDoc Connector server report all errors, logged in their logs, to theDT-Monitor. Therefore, when troubleshooting the IDoc Connector, the DT-Monitor can be used as a convenientsubstitute for the log. However, a few classes of errors (e.g. failure to connect with the DT-Monitor) are notreported as errors to the DT-Monitor. It is therefore recommended to check the logs when in doubt.

11.2 Filter

In addition to the standard filtering in the transaction monitor, described in the Master Adapter ConfigurationGuide -> Monitoring -> Filter

The IDoc Connector Controller introduces an adapter specific filter IDoc Number. Using this field one can filterfor transactions by providing the IDoc number as a filter.

The IDoc Number filter may also contain patterned based values when using '%' as a wildcard. In such cases,leading 0-s will be trimmed.

Example:

- Filtering by '833381' and '0000000000833381' will result in displaying a transaction record with IDocnumber 833381

- Filtering by '08%81' will result in displaying a transaction record with IDoc number starting with 8 andending with 81

11.3 R/3 System

The monitoring tools within R/3 can be used for checking the structure of processed IDocs, and the connectionof the IDoc Connector Server to the R/3 system.

SAP IDoc Adapter


WE02 - Display IDoc

The transaction WE02 lists all IDocs that have been created, or received by the R/3 system for exchange withother systems. It provides an effective overview over what is happening in the R/3 system with regard to IDocexchanges.

Outbound IDocs

If the traffic light in the column status grouping is red or yellow, the R/3 system did not attempt to send the IDocto the IDoc Connector Server. This behavior definitely derives from the R/3 system. If the traffic light is green,the R/3 system has passed the IDoc on to the subsystem that is responsible for sending IDocs.

Please note that a green traffic light in combination with the IDoc-Status 3 does not guarantee that the IDochas been received by the IDoc Connector Server. The BIS monitoring facilities must be used, to ensure thatthe IDoc has been successfully received, or check the log of the IDoc Connector Server.

Inbound IDocs

If the traffic light in the column status grouping is red or yellow, the R/3 system successfully received the IDocfrom the IDoc Connector Client, but did not process the IDoc. Either the source IDoc is invalid, or the R/3system has not been properly configured to process the IDoc.

R/3 System: SM58 - Transactional RFC

The transaction SM58 shows all pending outbound tRFC calls. The list includes the transactions for outboundIDocs that are currently active, or that have failed. Furthermore incomplete transactions can be retried with theEdit | Execute LUW (F6) command.The transaction SM58 reveals the error cause, if an outbound IDoc has IDoc-Status 3, but the IDoc has notbeen received by the IDoc Connector Server.

SAP IDoc Adapter


12 Adapter Interactions

Common Information

Interactions can be used to test the adapter, the configured master data, and the partner communication,without creating a special business process. For example you can send a test file to the partner, or poll itsmailbox to see if the connection works. The interactions do not support any queuing (WLH) or resources.

The state of the interaction can be monitored as a result in the interactions form and not in the BIS Inspector.Description of the common form attributes:

Attribute Description

Number of executions Configures how often an interaction is executed after the button Executedis clicked. Default is 1.

Number of parallel executions Configures how many interactions are executed parallel. This can be usedfor testing parallel transmission of files for example. The default value is 1.The maximum parallel execution is 30.

Persist details If this flag is enabled, all information about the request and theresponse will be available for monitoring. Also the request and responseattachments will be available to show.If the flag is disabled, no information is available after the interaction isfinished. Only the protocol is shown, which states which interaction wasfinished successfully and which not.

Displayed details forinteraction number

Shows the number of the interaction for which the Request/Response tabis shown.

New button Creates a new interaction.

Execute button Starts the execution of the interaction.

Stop button Click this button to cancel all scheduled interactions. The runninginteraction will run until it is finished, but no new one will be started.

Request tab Shows the request which is forwarded to the adapter.

Response tab Shows the response the interaction got from the adapter

Protocol tab Shows which interaction was finished successfully, and which was finishedwith an error.Using the context menu the Request/Response details can be shown.

Supported interactions:

Interaction Description

Send IDoc Transmit an arbitrary IDoc file to SAP.

Send IDoc status Generate a status IDoc for a given IDoc number.

SAP IDoc Adapter


Description of the form fields:

Attribute Description

IDoc address Destination address to which the IDoc is sent (Send IDoc only).

Encoding of IDoc file Encoding of the IDoc which is transferred (Send IDoc only).

Path to file Path to IDoc file (Send IDoc only).

IDoc connection Connection to which the status IDoc is sent to (Send IDoc status only).

SAP client The SAP client (MANDT) of the receiving SAP system (Send IDoc statusonly).

IDoc number The IDoc number for which the status IDoc is generated (Send IDoc statusonly).

IDoc status code Two digit status code which is to be generated for the given IDoc number(Send IDoc status only).

SAP IDoc Adapter


13 Troubleshooting

13.1 Resolving Problems When Sending IDocs

Symptom Solution

No Status IDoc messages aresent.

Make sure that the IDocController-ReportQueue is connected to theappropriate IDoc client.

No Status IDocs are receivedin R/3, although the IDoc Clientseems to send them.

Check the Status IDoc settings in the applied SAP address (usually thesender is still empty), and make sure that the partner configured there isallowed to receive Status IDocs.

(Type STATUS must be set for inbound parameter in the used partnerdefinition in WE20).

The IDocs are sent to R/3, butin WE02, the IDoc messagesstill have status 56 and arenot processed. The Detailsview of the control set showsinterchanged sender andreceiver.

The direction flag in the control set is probably set to 1 (Outbound),although the IDoc is sent to R/3 (Inbound).

If you are trying to send an IDoc message with a control set of this format,the sender and recipient will be interchanged. (See Send IDocMD (page23)for details).

13.2 Resolving Problems When Receiving IDocs

Symptom Solution

BIS processes which shouldbe triggered by the R/3 systemare not running.

Step 1: Find out whether the R/3 system tried to send IDoc messages.

1.Go to the transaction WE02 - Display IDoc to see whether IDocmessages have been transfered to the ALE layer of the R/3 system. Ifthere are no outbound IDoc messages or the indicators ("traffic lights")for the IDocs are red or yellow, the configuration of the R/3 system isdefective. Otherwise, proceed with step 2.

Common source of errors:

• Erroneous configuration of the R/3 system.

• Erroneous BIS 6 or IDoc Connector Server configuration.

• Network problems

Step 2: Find out whether the IDoc Connector server has received IDocfiles.

SAP IDoc Adapter


Symptom Solution1.In the corresponding monitor, check for waiting messages.(Perhaps no

process has been deployed).

2. In the Recovery Monitor, check the open incoming transactions. Theymust have also an entry in R/3 transaction SM58.

Common sources of error:

• Processes are not triggered, since the settings for the initiator rules andinitiator ports are missing or incorrect.

• The IDoc Connector server’s master data does not match the R/3system’s configuration.

• Network problems.

Step 3: Fix the problem.

1.If the transaction SM58 (Transactional RFC) indicates that there areproblems with the RFC server, consult the IDoc Connector server’s logfiles to see what the IDoc Connector server is doing and whether anyerrors occurred.

2.The IDoc Connector server accepts IDoc messages from the R/3system even if BIS 6 cannot send the received messages to thecentral instance. Therefore, the transaction SM58 can only be usedto recognize problems which have directly been caused by theIDoc Connector server, the R/3 system or the network.

3. If network problems between the IDoc Connector server and theR/3 system are suspected, go to the transaction SM59, select theappropriate RFC destination from the TCP/IP connections, finally clickTest connection (F8) to test the RFC connectivity.

SAP IDoc Adapter


14 Known Restrictions

• The amount of data that can be sent or received in one transaction is limited by the amount of availablememory. Therefore, transferring very large IDocs (e.g., CAD IDocs, or files containing many IDocs) willaffect the system’s performance substantially, if the operation is executable at all. This particularly appliesfor 32bit operating systems, e.g. 32bit operating systems with a virtual address space limit of 2-GB, theIDoc files should not consist of more than 150.000 records. Hence, where transactions involving verylarge files may not work, both sending and receiving are subject to this.

• XML IDocs are not supported. They must be converted into standard IDocs first.

• IDocs must not contain End-of-File (EOF) characters. (some MS-DOS applications use EOF characters).

• The characters in Unicode IDocs must consist of characters as used in the Basic Multilingual Plane(BMP).

SAP IDoc Adapter


A Sample Scenario – Using tRFC

The quick start example assists in getting the IDoc Connector quickly up and running. After all steps of thisquick start example have been completed, the R/3 system and BIS 6 have been configured to perform thefollowing actions:

• Create IDocs in the R/3 system.

• Receive created IDoc messages from the R/3 system.

• Send received IDoc messages back to the R/3 system.

• Send status confirmations for received IDoc messages to the R/3 system.

Note: The screenshots presented for this example refer to the SAP Release 701. Other releases mayslightly differ.

The steps that are described in the quick start example refer to an environment that is described in the tablesbelow.

BIS Properties


Windows (32Bit) Operating system that hosts the IDoc Connector

d:\bis6_home BIS 6 directory

000 BIS 6 client

IDoc Properties


TXTRAW01 Basic type of the IDoc

SEEPORT Partner port

SEEDEMO Partner number

KU Partner type

partner role [empty]

SAP IDoc Adapter


Connection Properties


gatewayhost Gateway host

sapgw00 Gateway service

apphost Application server host

00 System instance number

SEERFCUSER User

100 SAP client

SAP Properties


SID R/3 system ID

sapconnector Program ID

SEEBURGER DEMO RFC destination

A.1 Installation

After installing the IDoc Connector with the BIS 6 setup procedure, perform the following steps to completeinstallation:

1.Download the file sapjco3-NTintel-3.0.8.zip (or the proper one for your system) from http://service.sap.com/connectors.

2.Extract the file sapjco3.jar to d:\bis6_home\lib\ext.

3.Extract the file sapjco3.dll to d:\bis6_home\lib\native.

Please refer to the topic SAP Java Connector (JCo) Installation (page 9) for important notes about commoninstallation problems.

A.2 Master Data Configuration

Open the tab pane Configuration in the BIS 6 Front-end to perform the following steps:

1.Create a new SAP connection.

2.Enter the connection properties into the tab pane Settings.

3.Save the data set.

4.Create a SAP address for sending IDocs and status confirmations to the R/3 system.

5.Select the previously created connection as Connection to SAP system.

6.You can leave the System ID empty, since this field is not required unless in Load Balancing mode.

SAP IDoc Adapter


Figure A-1: Master Data Configuration

7.Enter the settings for the status confirmations.


SAP IDoc Adapter


Figure A-2: Status Confirmation

9.Create a registration for receiving the IDoc from the R/3 system with server type IDOC.

10.Select the connection that was created in step 1, as Connection to SAP gateway.

11.Enter a program ID which corresponds to the program ID of the RFC Destination configured in SAPsystem.


SAP IDoc Adapter


Figure A-3: Settings

A.3 Receiving Treatment

Open the BIS 6 Process Designer and create a new process.This process will perform the following steps:

• Receive IDocs from the R/3 system.

• Send status confirmations to the R/3 system for received IDocs. (e.g. Status 10, I nterchange HandlingOK).

• Send received IDocs back to the R/3 system.

• Send status confirmations to the R/3 system for received IDocs. (e.g. Status 38, IDoc archived).

To create and configure this process carry out the following steps:

1.Make sure the sapclient.wsdl and the sapserver.wsdl are both imported in the Process Designer.

2.Add the ReceivedIDocEvent operation (from SAPConnectorServer tasks) to the process.

3. Insert the sendSAPStatusReport operation (from SAPConnectorClient tasks) after the ReceivedIDocEvent operation.

4. Insert the SendIDocMD_v2 operation (from SAPConnectorClient tasks) after the sendSAPStatusReport operation.

SAP IDoc Adapter


5.Insert the sendSAPStatusReport operation after the SendIDocMD operation.

The process should look like this:

1.Assign the properties of the first sendSAPStatusReport component of the process that are necessary tosend Status IDocs with status 10 back to the R/3 system:

• Assign the prepared report template of the ReceivedIDocEvent (path: /ReceivedIDocEvent/initiationReportHandling/preparedReports/reportMessage) to the preparedReportPart of the sendSAPStatusReport (path: /sendSAPStatusReport/preparedReportPart/AttachmentRef).

• Assign all the docnumbers of the received IDocs (path: /ReceivedIDocEvent/docnum to the sendSAPStatusReport (path: /sendSAPStatusReport/docnumberPart/docnumbers).

• Assign the status 10 to /sendSAPStatusReport/statusPart.

2.Assign the properties of the SendIDocMD _v2 component of the process that are necessary to send thereceived IDocs back to the R/3:

• Assign 000 to the SendIDocMDReq/clientID.• Assign the record ID of the address Destination SID to SendIDocMD.destinationAddressId.

To get this record ID: Go to the tab pane Administration of the address master data and copy thecontent of the Record field to the Windows clipboard.

• Assign /ReceivedIDocEvent.attachments to /SendIDocMD/attachments.• Assign IDocConnector-Queue to queue.

SAP IDoc Adapter


The queue will be generated automatically when the process is activated, but do not forget to connect it tothe IDoc Connector client.

3.Assign the properties of the second sendSAPStatusReport component of the process that are necessaryto send Status IDocs with status 38 back to the R/3 system:

• Assign the prepared report template of the ReceivedIDocEvent (path: /ReceivedIDocEvent/initiationReportHandling/preparedReports/reportMessage) to the preparedReportPart of the sendSAPStatusReport (path: /sendSAPStatusReport/preparedReportPart/AttachmentRef).

• Assign all the docnumbers of the received IDocs (path: /ReceivedIDocEvent/docnum to the sendSAPStatusReport (path: /sendSAPStatusReport/docnumberPart/docnumbers).

• Assign the status 38 to /sendSAPStatusReport/statusPart.• Save and activate the process.

An appropriate Initiator port is created and installed during the activation of the process by default. But you willhave to create an Initiator rule to start the processing when an IDoc is received by the IDoc Connector server:

1.Create a rule for port type SAPConnectorServer/ReceivedIDocEventPT.

2.Set an expression like 1=1.

3.Rooting type: process.

4.TargetPort: {http://seeburger.com/}<nameOfYourProcess>

A.4 Configuration within R/3

1.Go to transaction SM59 to create a new RFC destination.

2.Click the button Create (F8).

3.Enter SEEBURGER DEMO for the name of the RFC Destination.

4.Select the Connection Type T Start an external program via TCP/IP.

5.Click Save (Ctrl+S) to save the data set.

6.Complete the form as shown in the screenshot below.

SAP IDoc Adapter


Figure A-4: RFC Destination

If Unicode has been enabled in the R/3 system:

1.Go to the pane MDMP & Unicode.

2.Select Unicode as the Character Width in the Target System and save the data set.

SAP IDoc Adapter


Attention: If the R/3 system is Unicode enabled, the character width of the target system must be set toUnicode. The IDoc Connector Server cannot operate in non-Unicode mode if the R/3 system supportsUnicode.

Figure A-5: Special Options

1.Go to transaction WE21 to create a transactional RFC port.

2.Create the transactional RFC port called SEEPORT by clicking the Create F7 button.

SAP IDoc Adapter


Figure A-6: Ports in Id processing

3.Complete the form as shown below and save the dataset.

Figure A-7: Ports in IDoc processing

4.Go to transaction WE20 to create a Partner Profile.

5.Create the Partner Profile SEEDEMO.

6.Click the Create (F5) button.

7.Enter SEEDEMO for the Partner Number and set the Partner Type to KU (Customer).

8. In the tab pane Post Processing: Permitted Agent set the Type to US (User) and the Agent to SEERFCUSER.

9.Click the Save (Ctrl+S) button.

10.Add the outbound parameters.

SAP IDoc Adapter


11.Click the Create outbound parameter button underneath the Outbound parmtrs table.

12.Set the Message Type to TXTRAW.

13.Complete the tab pane Outbound Options as shown below.

Attention: On some R/3 releases the Pack. Size field might be hidden.

To unhide this field:

1.Set the receiver port to an empty value.

2.Click the button Save (Ctrl+S).

3.Set the Output Mode to Transfer IDoc Immed.

4.Set the receiver port back to SEEPORT.

5.Set the Output Mode back to Collect IDocs.

6.Click the button Save (Ctrl+S) and leave the screen.

SAP IDoc Adapter


Figure A-8: Outbound Parameters

7.Add the inbound parameters for status processing.

8.Click the Create Inbound Parameter button underneath the Inbound parmtrs. table.

9.Set the Message Type to STATUS.

10.Depending on the R/3 release, select the process code STA1, or STA2 (Status Record from IDoc).

11.Save the data set and leave the screen.

SAP IDoc Adapter


Figure A-9: Inbound Parameters

When this step is completed, the Partner Profile should look similar to the screenshot below.

SAP IDoc Adapter


Figure A-10: Partner Profiles

A.5 Running the Sample Scenario Process

1.Ensure that the IDoc Connector Server and the IDoc Connector client are running.

2.Go to transaction WE19 to send an IDoc of type TXTRAW01 to the IDoc Connector server.

3.Enter TXTRAW01 as BasicTyp, and click the Create (F8) button. Alternatively, you may create a new IDocbased on an existing one.

SAP IDoc Adapter


Figure A-11: Test Tool for Idoc processing

4.Click on the control record to define the receiver, and sender of the IDoc. Complete the form as shownbelow.

Figure A-12: Edit control record fields

Attention: If the IDoc has been created based on an existing IDoc, ensure that the Archive Key field ofthe control record is empty. To ensure that the Archive Key is empty, click on the All Fields button, scrolldown three pages, and check the Archive Key field. If the Archive Key is not empty, this message popsup:

SAP IDoc Adapter


Figure A-13: Information

5.Click on the data record to enter a random string, e.g. SEEBURGER DEMO.

6.Send 10 IDocs by clicking on the Standard outbound processing (F7) button.

Figure A-14: Outbound Processing

On some R/3 releases a message box with the message IDoc sent to R/3 System or external program willpop up.

Attention: The IDoc(s) will not be sent to the IDoc Connector server until the message box is closed.

Wait several seconds, then check whether the IDocs have been successfully processed by the IDoc Connector.If you have precisely followed the steps of this quick start example, then the following statements should be true.

The IDoc Connector server processed two transactions (each delivers 5 IDocs). Therefore the console ofthe IDoc Connector server and its log contains two entries that claim Task succeeded: Received IDocs weredelivered to the integration system. You may also check with the DT-Monitor that the number of finishedprocesses has been increased by two.

The process that has been created in the topic Receiving Treatment (page 65) ran two times. Thereforethe Monitoring pane of the BIS 6 Front-end should list the two instances of said process as Today's Processes.

The IDoc Connector client sent two IDoc files (each containing 5 IDocs), and sent two status confirmations.Therefore the console of the IDoc Connector client and its log contains two entries that claim Task succeeded:IDoc was sent to R/3, and two entries that claim Task succeeded: Status was sent to R/3. You may also checkwith the DT-Monitor that the number of finished processes has been increased by four.

1.Check whether the IDocs and their status confirmations have been successfully processed by the R/3system.

2.Go to the transaction WE02 to display the IDocs that have been processed.

SAP IDoc Adapter


3.Set a filter for the Partner Number to limit the amount of shown IDocs.

Figure A-15: IDoc List

4.Click the Execute (F8) button to show the IDoc list.

5.Check whether the status of the listed IDocs is correct.

If you have precisely followed the steps of this quick start example, then there are:

• 10 Outbound IDocs of type TXTRAW with status 10 (Interchange handling OK);

• 2 Inbound IDoc of type STATUS (each IDoc contains 5 status segments);

• 10 Inbound IDocs of type TXTRAW with status 56 (IDoc with errors added);

SAP IDoc Adapter


Note: The IDocs that have been sent back to the R/3 system cannot be processed, because theInbound Partner Profile is not configured to process IDocs of type TXTRAW. Therefore the traffic lightsin the status grouping column for the Inbound IDocs will be red.

To configure the Inbound Partner Profile, perform the following (optional) steps:

1.Go back to the transaction WE20.

2.Add a rule for processing inbound IDocs of the type TXTRAW. Note that a valid Process code must bespecified, e.g. ED00 (Display IDoc Using Work Item).

3.Go back to the transaction WE19 to send some IDocs to the IDoc Connector.

Note: The traffic lights in the status grouping column should be either yellow or green, depending onthe Process code. For the ED00 Process code, the traffic lights should be yellow.

SAP IDoc Adapter


B Sample Scenario – Using File Port

Before running this sample scenario, please run the one that uses tRFC. The configurations are the same.Here will be explained only the differences.

B.1 File Port Configuration

1.Go to transaction WE21 to create a file port.

2.Create the file port called SEEFILE by clicking the Create F7 button.

3.Complete the form as shown below.

4.Do the same for tabs Inbound file and Status file.


SAP IDoc Adapter


Figure B-1: Ports in IDoc processing

6.Use the physical directory path to map a network drive Z.

B.2 Master Data Configuration

1.From the Connections dialog ope the SID system.

2.Activate the Use file port and complete the form as shown below.

SAP IDoc Adapter


Figure B-2: Send-site (SAP Inbound)


4.Create a new file port Listener.

5.Set Connection for Status IDocs to SID system.

6.Set Local path to Z:\.


Note: Leave the Code page to <platform>, because the file port SEEFILE is not Unicode-enabled.

B.3 Running the Sample Scenario Process

1.Ensure that the IDoc Connector server and the IDoc Connector client are running.

2.Go to the transaction WE19 to send an IDoc of the type TXTRAW01 to the IDoc Connector server.

3.Enter TXTRAW01 as BasicTyp, and click the Create (F8) button. Alternatively, you may create a new IDocbased on an existing one.

SAP IDoc Adapter


Figure B-3: Test Tool for IDoc processing

4.Click on the control record to define the receiver, and sender of the IDoc. Complete the form as shownbelow.

Figure B-4: Edit control record fields

5.Click on the data record to enter a random string, e.g. SEEBURGER DEMO.

6.Send 10 IDocs by clicking on the Standard outbound processing (F7) button.

SAP IDoc Adapter


C FAQ

Q: Updating SAP Jco on an AIX server causes problems, JCo claims to be operated with the old version of libsapjco3.so, or returns a similar message. What has to be done in order to update the shared libraries usedby SAP JCo on AIX?

A: Updating the shared libraries of SAP JCo that are used by the BIS 6 IDoc Connector requires a specialprocedure (described below:)

Background

If AIX loads a shared library into the memory, the image of that library is kept in the memory, even if noprocess is using the library. If the on-disk copy of the library is altered, then applications using that librarystill use the in-memory copy, and not the updated disk copy. This represents the expected standardbehavior with AIX.

In the case of applying a new version of SAP JCo shared libraries, shutting down all BIS 6-JBoss stillleaves shared libraries in the memory (e.g. librfccm.so stays in memory). Copying the version of thelibraries updates the disk copy, but a subsequent startup of an IDOC Connector instance uses the in-memory library images (if they are still present).

Solution

Running slibclean before starting the update flushes libraries that are not currently in use from memory.So these are the recommended steps before applying any update of SAP JCo on AIX:

1.Shutdown BIS 6 JBoss and all external nodes (i.e. Tomcat instances) which include an IDocConnector installation.

2.Run the AIX command /usr/sbin/slibclean as root to clean all non-referenced libraries of SAP JCofrom memory.

3.Update all SAP JCo native library.4.Restart JBoss and the external nodes.

These instructions are adapted from SAPNote 608726, which includes more general descriptions onthe shared library update on SAP systems with AIX.

Q: The IDoc Connector Client cannot establish a connection to the R/3 system. The error message readspartner <IP of R/3 system> not reached. The R/3 system is located behind a firewall and its "real" IP addresscannot be accessed directly because of the network address translation (NAT) of the firewall.

A: The SAP gateway instance profile has to be extended by the alternative IP of the R/3 system. Please seeSAPNote 148832 for further details.



SAP IDoc Adapter


Q: In IDoc inbound processing via the file interface, an error message occurs: IDoc: Event for starting inboundprocessing was not triggered. But in fact the IDocs are received from the SAP system.

A: Even if received, the IDocs are not processed. However, the event starting the processing could not betriggered. The solution consists of two steps which you must edit consecutively.

1.Check the workflow Customizing. The Customizing must be complete for the workflow runtimeenvironment. You can generate the missing settings using the Auto Customize button.

2.Activate the event linkage for the IDoc inbound processing.

Q: In IDoc inbound processing via the file port, an error message occurs: First record is not an IDoc controlrecord. The same IDoc can be processed using tRFC.

A: Check the Unicode enabling in both, BIS and SAP systems. This error occurs when the file is not readcorrectly. For the same reason the following error types may occur:

• IDoc contains a data record where a control record is required.

• IDoc contains an invalid or unknown type of record.

• Conversion error when reading from file (specific for file port).

Q: In my file port directory, I noticed two types of IDocs, one starting with EDI_DC40, and others with EDI_DC40_U. Which ones are correct?

A: (file ports) If IDocs are generated in an Unicode system, they are stored in Unicode files. However, Unicodefiles are only processed with a set Unicode flag, if the control records are marked with EDI_DC40_U but notwith EDI_DC40. The answer is that they are both correct, but the ones are only applicable for Unicode enabledfile ports.

SAP IDoc Adapter


D Performance Considerations

The effective performance of the IDoc Connector depends on a number of factors. This topic explains themajor factors and presents some general guidelines for archiving a reasonably good performance with theIDoc Connector.

D.1 Size of the Transferred IDocs

For good performance it is vital to choose the right size for the transferred IDocs. For systems with a limitedamount of memory (e.g. a system with only 1GB of RAM) the number of records per transaction should rangefrom 5.000 up to 20.000. For systems with plenty of memory a bigger transfer size is preferred: The numberof records per transaction should range from 10.000 up to 100.000.

Attention: Sending and receiving of single IDocs per transaction will result in unsatisfactoryperformance of the IDoc Connector. Always queue IDocs to transfer them as one large chunk for goodperformance.

For sending IDocs the SEEBURGER Business Integration Converter (BIC) should be used to merge multipleIDocs into one IDoc file before sending the IDoc file with the IDoc Connector client.

Please note the following restrictions when merging IDocs:

• The IDoc versions of all combined IDocs must be of the same version, that is IDoc version 2 or IDocversion 3.

• All combined IDocs are sent to the same SAP client.

• All combined IDocs are sent to the same R/3 system over the same connection.

• Combined IDocs may consist of IDocs with different IDoc types, different senders (sender partner number(SNDPRN), sender partner type (SNDPRT), or sender partner role (SNDPFC)).

For receiving IDocs the R/3 system should be configured to combine multiple outgoing IDocs into onetransaction. To do so, go to transaction WE20, and set the Output Mode to Collect IDocs and the Pack. Size field to the number of IDocs that should be combined into one transaction.

Note: The Pack. Size field determines the number of IDocs that are combined into one transaction,not the number of records. Consequently, the Pack. Size must be estimated based on the expectedaverage number of records of each IDoc.

SAP IDoc Adapter


D.2 Available Free Memory

It is strongly recommended for an optimized Java VM heap configuration to install the IDoc connector as a so-called external node. Please refer to the Master Adapter Installation Guide for more details.

Generally, the more records are transferred within one transaction, the higher is the throughput of theIDoc Connector as each transaction carries significant overhead that consists of:

• Execution of processes by the BIS 6 Process Engine. This significant overhead of the application serverdoes not apply if the IDoc Controller is installed as external node.

• Exchange of the transaction IDs (TIDs) between R/3 systems and the IDoc Connector.

• Establishment of connections to R/3 systems (This only applies to the IDoc Connector Client).

By increasing the amount of records that are transferred in one transaction, the weight of the fixed-sizedoverhead is reduced, however it has to be kept in mind that larger transactions require much more memory.

SAP IDoc Adapter


5 Secure Network Communication (SNC)

SNC is a software layer in the SAP system architecture that provides an interface to an external security product.SAP Systems include basic security measures, which include the SAP authorization concept and userauthentication based on passwords. With SNC, you can extend the SAP system security beyond these basicmeasures to include the protection offered by an external security product.

Advantages of using SNC:

• SNC provides application-level end-to-end security. SNC secures all communications between two SNC-protected components.

• You receive an individual approach. You use the security product of your choice, choosing the algorithmsyou want to use.

• You can change the security product at any time without affecting SAP system business applications.

5.1 Prerequisite

There are several 3rd party provider which offer libraries that can be used to implement SNC. SAP offers aproduct for SNC too. It is named SAPCryptolib. Get SAPCryptolib from http://service.sap.com/swdc. Downloadthe SAP Cryptographic Software. For extracting the files use the tool SAPCAR according to the SAP note212876.

5.1.1 R/3

A SNC library has been installed properly on the R/3.

1.Copy the system dependent library (libsapcrypto.so or sapcrypto.dll) and the binary sapgenpse(.exe) to /usr/sap/<SID>/SYS/exe/run. (If the library SAPSeculib is used by R/3, it should be replaced by SAPCryptolib to avoid any conflicts. Furthermore SAPSeculib only supports very short key lengths and the DSAalgorithm only. See SAP note 578377 for details).

2.Copy the ticket file that is included in the SAPCryptolib package to /usr/sap/<SID>/DVEBMGS<systemno.>/sec.

3.Make sure the environment variable SECULIB is set for both the user <SID>ADM and on MS WindowsR/3 for SARService<SID> to the above created path /usr/sap/<SID>/DVEBMGSxx/sec.

4.To use the SAPCryptolib, set/create the following profile parameters (access profile via transactionRZ10):

• ssf/name = SAPCRYPTOLIB• sec/libsapsecu = $(DIR_CT_RUN)/libsapcrypto.so• ssf/ssfapi_lib = $(DIR_CT_RUN)/libsapcrypto.so• Instead of $(DIR_CT_RUN) the path /usr/sap/<SID>/SYS/exe/run can be used.

http://service.sap.com/swdc


SAP IDoc Adapter


5.To enable SNC on the application server, set/create/check the following profile parameters (TA RZ10;according SNC User's Guide. Download it at http://service.sap.com/security - Security in detail -Infrastructure Security - SNC User's Guide).

• Enable SNC: snc/enable = 1

• Protection level used by default: snc/data_protection/use = <x>

• Used values:

1.Secure authentication only

2.Data integrity protection

3.Data privacy protection

• Minimum protection level: snc/data_protection/min = 1

• Maximum protection level: snc/data_protection/max = 3

• SNC name on the application server, see TA STRUST: snc/identity/as = p:CN=<instance id>

• Path to the SNC lib for the gateway: snc/gssapi_lib = <path to libsapcrypto.so>

For other parameters or a more detailed description, please refer to SNC User’s Guide.

Licencing: SAPCryptolib It may be used to secure communications between SAP components, please makesure that your license covers the usage of SAPCryptolib with SEEBURGER products.

5.1.2 SEEBURGER System

Install the SAPCryptolib library on the SEEBURGER system.

Installation

1.Copy the system-dependent library (libsapcrypto.so or sapcrypto.dll) and the binary sapgenpse to the<BIS6_home>/lib/native directory. The binary needs to be located in the same directory as the lib.

2.Copy the ticket file that is included in the SAPCryptolib package to the <BIS6_home>/conf/dt/sap/secdirectory.

3.Make sure the environment variable SECUDIR is set to the above created path <BIS6_home>/conf/dt/sap/sec. This variable has to be set for all users using SAPCryptolib (BIS 6 runtime user and certificateadministrator). It is recommended to set this variable in the set-dir script of BIS 6 and in the environmentof the SNC certificate administrator.

4.To check the correct setting of the variable SECUDIR, run <BIS_home>/lib/native/sapgenpse. The valueof SECUDIR will be printed out. If not set, a warning will be shown.

Cluster Installations

If SNC communication is to be used in a BIS cluster installation, the steps described above need to be repeatedon each cluster node, or make the files available as a cluster resource. The same is true for the configurationfiles mentioned in the topic Configuration.

If the SEEBURGER IDoc Connector is run by another user than the one being used for the SNC configuration(this is usually the case in cluster environments), please make sure to set this user name when generatingthe configuration files.

SAP IDoc Adapter


5.2 Configuration

For SNC secured communication a so-called Personal Security Environment (PSE) for the SAP user who isused for the inbound RFC communication has to be created and mapped to this user’s account in R/3. Thisidentity will also be used by the RFC registration for SAP outbound connections.

The following instructions describe the local generation of such a PSE on the SEEBURGER system and itsexport to R/3 including the user mapping and assignment to RFC registration afterwards.

In a cluster environment it is recommended to have the SNC files being stored in the same path on all clusternodes, or being made accessible through a shared volume. So all files can be reused in the whole clusterenvironment without any change. If this is not possible, please generate a single PSE on a node and copy itto all other nodes. Then do the configuration steps omitting Generation of PSE file.

5.2.1 Generation of PSE file

1.Create a PSE (including a certificate and private key): sapgenpse gen_pse –p <filename> -noreq [-x<pin_value>]

• You will be prompted for the Distinguished name of the PSE owner. The following properties may beused – please take care to keep the correct order.

• CN: common name.

• OU: organizational unit (may be used repeatedly).

• O: organization.

• C: country.

• The comma must be used as separator character. Example: CN=bisuser, OU=Connectors,O=SEEBURGER AG, C=DE.

• It is recommended to define a file name only (not a full path) to make sure that the generated file is beingcreated in the directory defined in the SECUDIR system variable.

• The -x parameter may be omitted, if no PIN secured file is needed.

2.Add this newly generated PSE file to the list of credentials that may be used by SAPCryptolib:

• Windows: sapgenpse seclogin –p <filename> [-O <nt-domain>\<nt-username>]• Unix: sapgenpse seclogin –p <filename> [-O <User ID>]

Return message of program:Added SSO-credentials for PSE <SECUDIR>\bisuser.pse CN=bisuser, OU=Connectors,O=SEEBURGER AG, C=DE

Note: The option –O is needed if the SEEBURGER IDoc Connector is run by another user thanthe one being used for generating this PSE and credential files. This is usually the case in a clusterenvironment. Use the Windows user, or the Unix UID for the –O parameter. Use the domainSYSTEM , if the SEEBURGER IDoc Connector is run as a LocalService on Windows.

3.Determine the PSE distinguished name, needed later in BIS and R/3, therefore save this namesomewhere: sapgenpse get_my_name –p <filename>Return message: CN=bisuser, OU=Connectors, O=SEEBURGER AG, C=DE

4.Export of the generated certificate for import in R/3: sapgenpse export_own_cert –p <filename> -o<cert_filename>. The generated certificate has to be added to the list of trusted public keys that areallowed for SNC connections.

SAP IDoc Adapter


5.Import the R/3 certificate file to your local PSE sapgenpse maintain_pk –a <R/3_certificate_file> -p<pse_file>.

6.Check the correct import with a list command sapgenpse maintain_pk –l –p <pse_file>.

Result, showing the imported certificate of the sample SAP system:

*** Object <PKList> is of the type <PKList_OID> *** 1. ------------------------------------------------------------- Version: 0 (X.509v1-1988) SubjectName: CN=SEP, O=SEEBURGER IssuerName: CN=SEP, O=SEEBURGER SerialNumber: 00 Validity - NotBefore: Sun May 20 12:06:53 2007 (070520100653Z) NotAfter: Fri Jan 01 01:00:01 2038 (380101000001Z) Public Key Fingerprint: BA61 1C98 3A4B 75AC 3385 8B1E B037 F434 SubjectKey: Algorithm RSA (OID 1.2.840.113549.1.1.1), NULL

5.2.2 Configuring R/3

This installation steps are applicable for R/3 4.7 ENTERPRISE, ECC5 and ECC6. The trust manager tool isnot available on R/3 versions lower than 4.7 ENTERPRISE.

1.Import the certificate created on the SEEBURGER system.

2.Run the transaction STRUST.

3.Double-click the SNC node of your host.

4.Click the Import button and select the certificate <cert_filename> that has been exported from BIS user’sPSE before. Make sure to select BASE64 encoding.

SAP IDoc Adapter


Figure 5-1: Transaction STRUST

5.Now the certificate is displayed in SAP Gui. Click the Add to Certificate List button in order to import it asa trusted certificate for your system’s PSE.

Note: After the import do not forget to click the Save button (the disc icon) in the menu bar.

SAP IDoc Adapter


Figure 5-2: Transaction STRUST - Add to certificate list

SAP IDoc Adapter


Figure 5-3: Transaction STRUST - Imported certificate

6.Link this certificate of the RFC user to the account.

7.Start transaction SU01, open the SNC tab.

There are different naming conventions for the SNC name. The SAPCryptolib uses the syntax: p:<distinguished_name>

Example: p:CN=bisuser, OU=Connectors, O=SEEBURGER AG, C=DEIt is important that the name is determined as canonical (see the dialog), this message should be shownafter having saved the dataset.

SAP IDoc Adapter


Figure 5-4: Transaction SU01

8.Now return to the transaction STRUST and export the system’s certificate to a local file.

9.Double-click the Own certificate field, now the contents of this certificate is shown is the text fields below.

10.Then click the Export button marked with a black arrow and export the system’s certificate to a local fileon the SEEBURGER system.

SAP IDoc Adapter


Figure 5-5: Transaction STRUST

11.On the BIS system, import the locally stored file to the PSE sapgenpse maintain_pk –a<R/3_certificate_file> -p <pse_file>.

12.Check the correct import with a list command: sapgenpse maintain_pk –l –p <pse_file>.

Result, showing the imported certificate of the sample SAP system:*** Object <PKList> is of the type <PKList_OID> *** 1. ------------------------------------------------------------- Version: 0 (X.509v1-1988) SubjectName: CN=SEP, O=SEEBURGER IssuerName: CN=SEP, O=SEEBURGER SerialNumber: 00 Validity - NotBefore: Sun May 20 12:06:53 2007 (070520100653Z) NotAfter: Fri Jan 01 01:00:01 2038 (380101000001Z) Public Key Fingerprint: BA61 1C98 3A4B 75AC 3385 8B1E B037 F434 SubjectKey: Algorithm RSA (OID 1.2.840.113549.1.1.1), NULL

13.Enable SNC for the registration.

14.Start the transaction SM59 and open the registration to be secured.

15.Select the tab Logon/Security and then click the SNC button in order to enter the SNC configuration.

16.Enter the distinguished name of the PSE imported from the SEEBURGER system, usually it is the samedistinguished name as the one mapped to the RFC user account before.

SAP IDoc Adapter


Figure 5-6: RFC Destination - Transaction SM59

17.After saving these setting, select the Activate SNC button on the Logon/Security tab.

SAP IDoc Adapter


Figure 5-7: RFC Destination - Activating SNC

5.2.3 Master Data Configuration

The full path to the SAPCryptolib has to be provided as a user-config setting.

<node name="GlobalConfiguration"><property name="SncLibPath" type="java.lang.String"> <BIS6_Home>/lib/native</property></node>

SAP IDoc Adapter


Figure 5-8: SAP Connections

There are five security levels that can be configured for SNC:

• 1: Secure authentication only.

• 2: Data integrity protection (data are transmitted unencrypted, but are hash-secured to avoidmanipulations).

• 3: Data privacy protection (highest level, data are encrypted).

• 8: Use the value from snc/data_protection/use.

• 9: Use the value from snc/data_protection/max.

It is recommended to select 8 Default setting defined in the SAP Instance Profile. The SNC My Name is usedby the registrations, the distinguished name (returned by the sapgenpse get_my_name command) has to beentered there. It is vital to use the correct syntax. The prep-ended p: is to be used if the SAPCryptolib is used,there are other prefixes if a different encryption tool is used.

Note: There is no space between the p: and the distinguished name.

Example: p:CN=bisuser, OU=Connectors, O=SEEBURGER AG, C=DEThe SNC partner name is used by the client for the SAP Inbound connections. Enter the distinguished nameof the R/3 application server (the value being returned by the command sapgenpse maintain_pk –l) plus theprep-ended p: for SAPCryptolib.In our case the name p:CN=SEP, O=SEEBURGER would be used.

SAP IDoc Adapter


No double quotes are needed, if the SNC name contains spaces, which it will in most cases. If they are usedanyway, this error might occur: SNCERR_BAD_NT_PREFIX.