Vous êtes sur la page 1sur 106

SAP IDoc Adapter

Version: v6.3.5.Q4

June 28, 2013

Table of Contents

1 Terms and Definitions 2 Introduction 3 Basics


3.1 IDoc Connector 3.1.1 IDoc Connector Server 3.1.2 IDoc Connector Client 3.2 Application Link Enabling (ALE) 3.3 Intermediate Document (IDoc) 3.4 Status Confirmation 3.5 Transactional Remote Function Call (tRFC) 3.6 SAP Java Connector (JCo)

1 2 3
3 3 3 3 4 4 4 4

4 Overview
4.1 Features and Restrictions 4.2 System Requirements 4.3 Integration 4.4 Logical Systems

5
5 6 7 7

5 Installation
5.1 SAP Java Connector (JCo) Installation 5.1.1 Applicable JCo Versions 5.1.2 Obtaining the Correct JCo Libraries from the SAP Service Marketplace 5.1.3 Installation 5.1.4 Troubleshooting

9
9 9 9 10 10

5.2 Available Versions of JCo for Different Architectures

11

6 Usage
6.1 Adapter Control over the Control Center 6.2 Operations 6.3 Monitoring

13
13 14 15

7 Master Data Configuration


7.1 Configuring Connections 7.2 Common Connection Settings 7.2.1 Settings 7.2.2 Send-Site (SAP inbound) 7.2.3 Extended 7.3 Configuring Addresses 7.4 Configuring Registrations 7.4.1 Settings Tab 7.5 Configuring File Port Listeners 7.5.1 Settings Tab

16
16 16 16 16 17 19 19 21 21 22

8 Process Configuration
8.1 Sending IDocs (SAP Inbound) 8.1.1 SendIDocMD 8.1.2 SendIDoc 8.2 Sending Status IDocs 8.2.1 SendSAPStatusReport 8.2.2 SendSAPStatusReportSync 8.2.3 SendStatus 8.2.4 SendStatusMD 8.3 Receiving IDocs (SAP Outbound) 8.3.1 ReceivedIDocEvent 8.4 Fault Messages 8.4.1 DtFault 8.5 Adapter Invocation Mode 8.6 Direct Invocation 8.7 Synchronous Adapter Invocation

23
23 23 24 26 27 27 28 29 30 30 30 30 31 31 32

8.8 Worklist Handler

32

9 Extended Features
9.1 Status IDoc Handling 9.1.1 Using the Generated Status IDoc Template 9.1.2 Queue for Status IDocs 9.1.3 Generation of Status IDocs in a Process 9.2 Customizable RFC Trigger Function for Fileport Communication 9.3 Connection Pool

34
34 34 34 34 35 36

10 Adapter Configuration
10.1 Dumping 10.2 Logging 10.2.1 JCo Logging 10.2.2 RFC Tracing 10.3 Extended Configuration Flags 10.4 Unicode and Code Page Settings 10.4.1 Unicode Code Pages 10.4.2 Unicode Settings in SAP 10.5 Memory Requirements 10.5.1 IDoc Connector Client Memory Management 10.6 Configuration within R/3 10.6.1 Creating a Minimum Authorization Profile for an RFC User 10.6.2 RFC Destination 10.6.3 Status Processing 10.7 Batching IDocs in R3 10.7.1 Scenario Description 10.7.2 Configuration in R3 10.7.3 Testing

38
38 39 39 39 39 42 42 44 44 45 46 46 51 52 52 52 53 53

11 Monitoring
11.1 Adapter Monitor 11.2 Filter 11.3 R/3 System

54
54 54 54

12 Adapter Interactions 13 Troubleshooting


13.1 Resolving Problems When Sending IDocs 13.2 Resolving Problems When Receiving IDocs

56 58
58 58

14 Known Restrictions A Sample Scenario Using tRFC


A.1 Installation A.2 Master Data Configuration A.3 Receiving Treatment A.4 Configuration within R/3 A.5 Running the Sample Scenario Process

60 61
62 62 65 67 74

B Sample Scenario Using File Port


B.1 File Port Configuration B.2 Master Data Configuration B.3 Running the Sample Scenario Process

79
79 80 81

C FAQ D Performance Considerations


D.1 Size of the Transferred IDocs D.2 Available Free Memory

83 85
85 86

5 Secure Network Communication (SNC)


5.1 Prerequisite 5.1.1 R/3 5.1.2 SEEBURGER System 5.2 Configuration 5.2.1 Generation of PSE file 5.2.2 Configuring R/3 5.2.3 Master Data Configuration

87
87 87 88 89 89 90 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 proprietors apply. Note: False configuration and/or improper use of communication components may result in significant charges from your telecommunication provider. Also consider configuration changes initiated by your telecommunication provider. SEEBURGER is not liable for related additional costs. Note: Please refer to the Knowledgebase article 13379 for an important notice concerning possible incurred charges from your telecommunication provider. Note: The information in this document is proprietary to SEEBURGER. No part of this document may be reproduced, copied, or transmitted in any form or purpose without the express prior written permission of SEEBURGER AG. Note: We expressly declare that the document "SEEBURGER Legal Information" (delivered also with your BIS installation media) is part of this documentation.

Figures

4-1 A-1 A-2 A-3 A-4 A-5 A-6 A-7 A-8 A-9 A-10 A-11 A-12 A-13 A-14 A-15 B-1 B-2 B-3 B-4 5-1 5-2 5-3 5-4 5-5 5-6 5-7 5-8

BIS Architecture 7 Master Data Configuration 63 Status Confirmation 64 Settings 65 RFC Destination 68 Special Options 69 Ports in Id processing 70 Ports in IDoc processing 70 Outbound Parameters 72 Inbound Parameters 73 Partner Profiles 74 Test Tool for Idoc processing 75 Edit control record fields 75 Information 76 Outbound Processing 76 IDoc List 77 Ports in IDoc processing 80 Send-site (SAP Inbound) 81 Test Tool for IDoc processing 82 Edit control record fields 82 Transaction STRUST 91 Transaction STRUST - Add to certificate list Transaction STRUST - Imported certificate Transaction SU01 94 Transaction STRUST 95 RFC Destination - Transaction SM59 96 RFC Destination - Activating SNC 97 SAP Connections 98

92 93

SAP IDoc Adapter

1 Terms and Definitions

Terms IDoc ALE tRFC JCo

Definition Intermediate Document Application Link Enabling Transactional Remote Function Call SAP Java Connector

SAP IDoc Adapter - v6.3.5.Q4

SAP IDoc Adapter

2 Introduction

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

SAP IDoc Adapter - v6.3.5.Q4

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, status confirmations 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 receiver module. 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/3 system. On startup this module registers with the SAP gateway and waits for incoming IDocs. It sends a WSDL message to the BIS 6 system for each packet of received IDocs. This message contains the received IDocs as its attachment, 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 the IDoc Connector server module. For each SendIDoc or SendIDocMD operation, the module sends the IDocs that are stored in the WSDL message 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 data among 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 and the IDoc format, please refer to the document IDoc Interface/Electronic Data Interchange (BC-SRV-EDI) that is part of the SAP Library.

SAP IDoc Adapter - v6.3.5.Q4

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 IDoc type. An application-specific structure is defined for each business case. The IDoc Connector supports all types of 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 information to send IDocs to their destination. Usually, an IDoc is represented as a file with a fixed record size (INHOUSE format). An IDoc file may contain multiple IDocs, where each IDoc is simply appended to another. While an IDoc file may contain IDocs of different IDoc types, all IDocs contained in one IDoc file must be of the same version. The IDoc Connector rejects IDoc files 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, or IDoc ready for dispatch. A receiving system may send status confirmations to inform the R/3 system about the processing stages of a received IDoc. The IDoc Connector optionally creates and sends status IDocs to the R/3 system. A status IDoc is a special type 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/3 system and a non-R/3 system. The transactional Remote Function Call (tRFC) protocol is an extension of the RFC 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 protocol assigns an unique transaction identifier (TID) to each transaction. Duplicate execution of transactions is avoided by the receiver's system carrying out a comparison of the TID of a transaction with the TIDs of transactions that 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 the RFC 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 Java Connector (JCo) and libRFC is required.

SAP IDoc Adapter - v6.3.5.Q4

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 following fields can be customized for status IDocs: STATUS, SNDPOR, SNDPFC, SNDPRT, SNDPRN, CREDAT and CRETIM. 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 the topic Configuration within R/3 (page 46) (Performance considerations) for details. XML IDocs are not supported.

SAP IDoc Adapter - v6.3.5.Q4

SAP IDoc Adapter

4.2 System Requirements


The common system requirements are described in the BIS Installation Guide. Furthermore the following requirements must be met in order to run the the component properly: System SAP Java Connector R/3 system Network Requirement SAP JCo Version >=3.0.8 The release 3.1h or later. 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 Connector is a toolkit for the communication with R/3 systems. It can be downloaded from the SAP Service Marketplace at 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 the setup 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 SA P_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 to SAP_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, are managed by a special networking layer of SAP called CPI-C. For the SAP JCo based BIS adapters CPI-C is equal 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. conversations setting has to be adapted. For JCo3, which is used by SEEBURGER adapters, there is a Java system property named jco.cpic_maxconv. You can configure this property in the file %bisas.home%/software/sample.vm.pro perties in the key vmoptions (for 32bit) and vmoptions64 (for 64bit) of the central and distributed instance. It has a default value of 204. Attention: Setting of a lower value then the default may result in errors because no new TCP connections between SAP and local systems can be opened. Using a too high jco.cpic_maxconv value may cause connectivity problems at the SAP gateway. Before you change the value of this property, please consult the administrator of the SAP system.

SAP IDoc Adapter - v6.3.5.Q4

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 Process Engine via the Queuing System Worklist, the Direct Mode or the sync connector to the appropriate communications adapter in the Adapter Engine. Incoming messages received from a listener for example, are forwarded to the Process Engine using the Initiator.

4.4 Logical Systems


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

SAP IDoc Adapter - v6.3.5.Q4

SAP IDoc Adapter

In particular, master data and runtime data belong exclusively to one Logical System. The adapter is able to process data and processes according to their Logical System, and therefore one instance of the adapter may be 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 D B tables. Every Registration must be identified by its program ID and its connection reference. Every File Port Listener is identified by its local path. For security reasons, besides the unique constraints, a check for duplicate listeners is performed on adapter start-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 the Adapter Error Monitor. The message contains the Logical System for which it is configured, and the reason why this Listener is not started. Each file port Listener is identified by its local path. Nonetheless the more unique criterion in this case is the SAP side path. Thats why the file port listener's duplicate check is performed on the SAP side paths.

SAP IDoc Adapter - v6.3.5.Q4

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 bit Java VM in production scenarios. The 32 bit versions of SAP JCo are recommended for test and demo systems only. Attention: It is strongly recommended for an optimized Java VM heap configuration to install the SAP JCo based communication adapters as a so-called External Node. Please refer to the Master Adapter Installation Guide for more details about the External Node installation and refer to the topic Memory Consumption (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 correct SAP 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 then 3.0.8. Although versions of SAP JCo 3.0.x branch which are higher than 3.0.8 can be used, this is not recommended until further notice.

5.1.2 Obtaining the Correct JCo Libraries from the SAP Service Marketplace
1. Read SAP Note 1077727 concerning the latest information about the supported platform and OS combinations 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, please follow the link http://service.sap.com/connectors | SAP Java Connector | Tools and Services | click the link Download SAP JCo Release 3.0 on the right page. (The internal component name at SAP for the SAP Java Connector is BC-MID-CON-JCO). 3. Choose the correct version, 9

SAP IDoc Adapter - v6.3.5.Q4

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 correct locations during the setup of the central instance, because the setup will ease the correct installation of 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 include the 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 for Microsoft 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 manually according 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 the BIS is installed to. Please refer to the topic Available Versions of JCo for Different Architectures (page 11) 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.htm l 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 off the Autostart feature of both adapters. Due to the usage of native libraries in SAP JCo only the first adapter start-up attempt after a BIS (re)start will show potential problems related to these native SAP libraries, or libraries 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 error message during adapter start-up tells which one is needed exactly. It is recommended to copy these libraries 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 3 needs the most recent version of Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package SAP IDoc Adapter - v6.3.5.Q4 10

SAP IDoc Adapter

(KB973544). Please refer to the SAPNote 684106 "Microsoft Runtime DLLs." and Microsoft Security Bulletin MS09-035 to get more information which version is needed for your platform and where to obtain it. The incorrect bit width has been chosen. The native libraries must have the same bit width than the Java VM of BIS uses. The owner or the access rights may be incorrect so that the file cannot be accessed by the BIS runtime user. 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 Java 6 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 supported platforms 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 are using a 32bit Java VM on a 64bit platform, please download the 32bit JCo.

Microsoft Windows
OS Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008 Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008 Architecture x86 32bit Sun JVM Vendor Archive File sapjco3-NTintel-3.0.8.zip

x86_64 64bit

Sun

sapjco3-NTAMD64-3.0.8 .zip

Native DLL name: sapjco3.dll

Linux
OS SuSE SLES10, RedHat EL5 SuSE SLES10, RedHat EL5 Architecture x86 32bit x86_64 64bit Sun Sun JVM Version Archive File sapjco3-linuxintel-3.0.8.t gz sapjco3-linuxx86_64-3.0. 8.tgz

Native library name: libsapjco3.so

SAP IDoc Adapter - v6.3.5.Q4

11

SAP IDoc Adapter

Solaris
OS Solaris 10 Solaris 10 Architecture SPARC 64bit x86_64 64bit Sun Sun JVM Version Archive File sapjco3-sun_64-3.0.8.tgz sapjco3-sunx86_64-3.0.8 .tgz

Native library name: libsapjco3.so

AIX
OS AIX 5.3, AIX 6.1 Architecture Power PC 64bit IBM JVM Version Archive File sapjco3-rs6000_64-3.0.8 .tgz

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

HP-UX
OS HP-UX B11.23, B11.31 Architecture Itanium 64bit HP JVM Version Archive File 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 recommended to follow these recommendations.

SAP IDoc Adapter - v6.3.5.Q4

12

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 be also displayed and edited there. For more information, refer to the topic Control Center in the Master Adapter Configuration Guide.

SAP IDoc Adapter - v6.3.5.Q4

13

SAP IDoc Adapter

6.2 Operations
IDoc Connector Client
Parameter SendIDoc_v2 SendIDocMD_v2 SendStatus_v2 SendStatusMD_v2 SendSAPStatusReport Definition This operation sends an IDoc to a R/3 system (SAP Inbound). This operation sends an IDoc to a R/3 system (SAP Inbound) and sets all necessary master data in the operation. This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound) and sets all necessary master data in the operation. This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound) (uses the SendSAPStatusReport operation instead). This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound). This operation relies on a template that is created by the IDoc Connector Server when receiving an IDoc. The response of the sending of the status confirmation is NOT returned to the process. This operation is equivalent to SendSAPStatusReport with the difference that it contains the request and the response messages. The response of the sending of the status confirmation is returned to the process. Attention: This operation is an older version and we do not recommend it for use. SendIDoc_v2 has an extended response and should be used instead. This operation sends an IDoc to an R/3 system (SAP Inbound). SendIDocMD Attention: This operation is an older version and we do not recommend it for use. SendIDoc_v2 has an extended response and should be used instead. This operation sends an IDoc to an R/3 system (SAP Inbound) and sets all necessary master data in the operation. SendStatus Attention: This operation is an older version and we do not recommend it for use. SendIDoc_v2 has an extended response and should 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. SendStatusMD Attention: This operation is an older version and we do not recommend it for use. SendIDoc_v2 has an extended response and should be used instead. This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound) (uses the SendSAPStatusReport operation instead).

SendSAPStatusReportSync

SendIDoc

IDoc Connector Server


Parameter ReceivedIDocEvent Definition An IDoc is received by the IDoc Connector server and is initiated to the engine.

SAP IDoc Adapter - v6.3.5.Q4

14

SAP IDoc Adapter

6.3 Monitoring
The Adapter is connected to different monitors. The specific function of each monitoring tool is described in the Master Adapter Configuration Guide. Monitor Adapter Monitor Recovery Monitor Transaction Monitor Description Provides runtime information. If individual orders require recovery, they are listed in the Recovery Monitor. Provides information on the state of transactions of the adapter. The exact definition of a transaction depends on the respective adapter, but usually a transaction describes the reception or the sending of a message.

SAP IDoc Adapter - v6.3.5.Q4

15

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 Gateway host Description The host name or the IP address of the computer which operates the SAP gateway. The gateway host may also be specified as a complete SAP router string. The component registers at the SAP gateway to receive messages. This setting is also used for the SAP INBOUND files, if the Explicit application server and gateway connection type has been selected. 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 the system number of the SAP system, e.g. 00. So sapgw00 complies with TCP port 3300. This list describes all available fields; the dialog does not show all applicable configurations.

Gateway service

7.2.2 Send-Site (SAP inbound)


Parameter/Option User Description The SAP log-on user. It is recommended to create a dedicated minimum authorization profile for this communication user.

SAP IDoc Adapter - v6.3.5.Q4

16

SAP IDoc Adapter

Parameter/Option

Description 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, EDIN Authorization object BC_ALE_RECV: EDI_MESTYP: e.g. SYSTAT, INVOIC The component connects to the R/3 as the given user when SAP INBOUND files are sent to the R/3. Note that the user must exist for the current SAP client. The SAP client is contained in the addresses SAP clien t field.*

Password Connection type

This is the SAP log-on password. This parameter specifies the way a connection is established for SAP INBOUND files sent to an R/3 system: Explicit Application Server The default gateway is used; the fields gateway host and gateway service are only used for receiving RFM. Explicit Application Server and gateway Both will be determined individually, unlike the option above (where the default gateway is automatically used). Load balancing The message server port of the SAP system has to be added manually to the services file, defining the registered TCP services of the operating system. On windows machines this file is located in <windows_home>/system3 2/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. The application server may also be specified as a complete SAP router string. This field is not visible in Load Balancing mode. The SAP system number (the instance number of the R/3 system). This number can be located e.g. in the SAP menu under Tools | Administr ation | Monitor | System Monitoring |Servers. The system number can be determined by referring to the last two characters at the end of the indicated Gateway service. The host name or the IP address of the SAP message server. This field is only visible in Load Balancing mode. The name of the group of SAP Application Servers. The group is usually called PUBLIC, but this may not always apply. Note that the field System ID of the addresses determines the R/3 name for load balanced connections. This field is only visible in Load Balancing mode.

System number

Message server Group

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.

SAP IDoc Adapter - v6.3.5.Q4

17

SAP IDoc Adapter

Parameter/Option Language

Description The log-on language. This setting only affects the language of error messages deriving from an R/3 system. Note that it is recommended to use the default value (English). The component recognizes a few confusing error messages of the R/3 system, and replaces them with more meaningful ones. This feature does not work with non-English error messages. If the RFC trace is enabled, low level log files containing information on the communication (RFC) with a R/3 system, are stored in the BISAS_HOME \log\run\CENTRAL directory. These log files can be used to help analyze communication problems with an R/3 system. Attention: Enable this option only for fixing communication problems.

Enable RFC trace

Enable SNC

If enabled, the Secure Network Communications (SNC) layer is used for the communication with R/3 systems. For information on the SNC settings, please refer to the SAP guide Secure Network Communications - SNC User's Guide or Secure Network Communication (SNC) . The following security levels can be configured for SNC: Authentication Integrity protection Encryption Default setting of destination Max. available

Security level

It is recommended to select the Default setting defined in the SAP Instance profile. Own SNC name Partner's SNC name The name returned by the sapgenpse get_my_name command has to be entered here. The name of the R/3 application server. The value is returned by the command 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 Use file port Port name Description Enables/disables the file port specific configuration. Please note: The attributes described below are relevant for file port communication only. SAP file port created with the transaction WE21. It must be set to a physical directory and be accessible from both the SAP and the BIS system. This is usually achieved by a network share. Local path for the file port's physical directory. Path for the file port's physical directory. File mask for the SAP inbounds IDocs. Activate this option if the target file port is set to Unicode.

Local path SAP-site path File mask Port is Unicode-enabled

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

SAP IDoc Adapter - v6.3.5.Q4

18

SAP IDoc Adapter

7.3 Configuring Addresses


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

Settings
Parameter Description

Connection to the SAP system Determines the connection for sending IDoc-type messages (both payload and 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 B alancing mode. R/3 system client. This setting is used when the IDoc Connector logs on in order to send IDoc messages. The SAP client also determines the address for receiving status confirmation messages 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 received the 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 IDoc attachments 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 for receiving IDocs. For solving problems with encoding and Unicode code pages in general, please refer to the topic Unicode and Code Page Settings. (page 42)

SAP client

7.4 Configuring Registrations


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

SAP IDoc Adapter - v6.3.5.Q4

19

SAP IDoc Adapter

Parameter/Option Name

Description This is a short, but unique name that describes the registration. This name is used in log files to associate log entries with the corresponding registration. This is a demarcation for the created registration - if it will be used for IDoc Controller (IDOC), or for RFC Controller (RFC), but not for both simultaneously. For using this registration with the IDoc Controller, the only allowed value for this property is IDOC. The registration will be ignored, if the wrong type RFC is chosen. Default value: IDOC

Server type

Enabled Listener group

If this option is disabled, this record is ignored at the IDoc Connector server's start-up. This is the default value for the Listener group (DefaultGroup). A Listener that is part of the DefaultGroup will be started up on all nodes. Use the instance ID that has been configured during the BIS 6 installation for grouping the Listeners.

SAP IDoc Adapter - v6.3.5.Q4

20

SAP IDoc Adapter

7.4.1 Settings Tab


Parameter/Option Connection to SAP gateway Description This is the connection that is used to register with the SAP gateway. This setting also determines which address is used to send the status codes to R/3 for IDocs received by this registration. 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). This is the number of parallel connections that are used for receiving the IDocs. If this value is changed, the IDoc Connector Server is restarted with the updated configuration using the corresponding connection count. Note: To be able to receive IDocs in parallel, it is also required to increase the maximum count of connections of this RFC registration in R/3. This is done in transaction SMQS. Attention: When configuring this value remember the cpic_maxconv value described in System Requirements (page 6) part. Max. retry interval for connection problems (seconds) This is the maximum time (in seconds) between two startup attempts in case of failures. The waiting time is doubled from initially 1 second after each startup failure until either the maximum value is reached, or the server can be started successfully. Example: n - configured value x - number of attempt to reconnect y - 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 60 seconds: 1, 2, 4, 8, 16, 32, 60, 60, ...

Program ID

Number of connections

7.5 Configuring File Port Listeners


The file port Listener master data contains the settings for receiving the IDocs from the target file port physical directory. Parameter Name Description This is a short, but unique name that describes the file port Listener. This name is used in log files to associate log entries with the corresponding Listener. The default value for the Listener group is DefaultGroup. A Listener that is part of the DefaultGroup will be started up on all nodes. Use the instance ID that has been configured during the BIS 6 installation for grouping the Listeners.

Listener group

SAP IDoc Adapter - v6.3.5.Q4

21

SAP IDoc Adapter

Parameter

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

Enabled

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

7.5.1 Settings Tab


Parameter/Option Connection for Status IDocs Local path File mask Description This is the connection name that determines, which address is used to send the status codes to R/3 for IDocs received by this file port Listener. This is the local path for the file port's physical directory. This is the file mask for the SAP outbound IDocs. By default this mask is set to *.ido. Note: The file port mask is case-sensitive. Code page Polling interval (ms) This is the encoding of the received IDoc files. This is the specified amount of time (in ms) after which the port will be scanned for incoming IDoc files again. By default the value is set to 500 ms.

SAP IDoc Adapter - v6.3.5.Q4

22

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 an encoding for the attachment that carries the IDocs to be sent. Otherwise the task will be cancelled with a T ASK ERROR. Note: Sender and receiver will be swapped, if the diection flag in the control set of the transferring IDoc is set to 1 (outbound).

8.1.1 SendIDocMD
Note: SendIDocMD_v2 operation is corresponding to SendIDocMD, which is an older version and we do 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 master data (MD), i. e. in the BIS 6 database. An IDoc file may contain a random number of IDocs of any message type. All IDocs of an IDoc file must be of the same IDoc version (either IDoc version 2, or IDoc version 3). The fields of the IDocs must be set correctly. The following fields are excluded from this: Control Record Parameter SAP client (MANDT) IDoc number (DOCNUM) Direction (DIRECT) Description Can be left empty. If the field is not empty, it is compared with the actual S AP client. In case of a mismatch, a warning is sent to the log file. Completely ignored by the IDoc Connector Client, since the IDoc number is generated by the R/3 system when it receives the IDoc. If the setting for the direction is set to 1 (outbound), the IDoc Connector swaps the fields that identify the sender and receiver of the IDoc. This feature simplifies the steps that are necessary to receive and send an IDoc back to the R/3 system. This field can be left empty. If the field is not empty, its value is compared with the actual system ID (Note that the system ID is requested from the R/3 system, it is not determined from the master data or properties of the operation). In case of a mismatch, a warning is sent to the log file.

Receiver port (RCVPOR)

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

SAP IDoc Adapter - v6.3.5.Q4

23

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. The flag remains unchanged in the physically transmitted IDoc, since R/3 automatically corrects this during reception process. (The direction flag is located at offset: 35, length: 1 in a version 3 EDI_DC40 control set). Data Record Parameter SAP client (MANDT) IDoc number (DOCNUM) Segment number (SEGNUM) Settings for the operation: Operation parameter ClientId DestinationAddressId Attachments Description BIS logical system client ID of the address data set that is the destination for the IDocs. IDoc file that is to be sent. Note that exactly one IDoc file must be specified. Attention: The character encoding of the attachment must be set to a valid encoding. If the character encoding is not set, or is set to binary, the operation will be rejected. TransactionId Attention: This field is used internally. Never change this property! This field stores the transaction ID of incomplete tRFC calls. The value of this field is deleted, when a tRFC call is completed. Description Ignored by the IDoc Connector Client. Ignored by the IDoc Connector Client, since the IDoc number is generated by the R/3 system when it receives IDocs. Ignored by the IDoc Connector Client. The segment numbers are generated by the IDoc Connector.

8.1.2 SendIDoc
Note: SendIDoc_v2 operation is corresponding to SendIDoc, which is an older version, and we do not recommend 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 operation are stored as operation properties. Therefore the master data is not used.

SAP IDoc Adapter - v6.3.5.Q4

24

SAP IDoc Adapter

Parameter ClientId Attachments

Description BIS/Logical System 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 a valid encoding. If the character encoding is not set, or is set to binary, the operation will be rejected.

SapClient TransactionId

SAP client. Attention: This field is internally used. Never change this property! Transaction ID of incomplete tRFC calls. The value of this field will be deleted after termination of the tRFC call.

queue

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

Connection
Parameter User Password Ashost Sysnr Gwhost Gwserv Mshost Group R3name Lang Description User. Password. SAP application server, this field must be left empty in Load Balancing mode. SAP system number, this field must be left empty in Load Balancing mode. SAP gateway host, this field is optional, but must be left empty in Load Bal ancing mode. SAP gateway service, this field is optional, but must be left empty in Load Balancing mode. SAP message server, this field must be set for using the Load Balancing mode. It must be left empty, if Load Balancing is not applied. SAP message server, this field must be set for using the Load Balancing mode. It must be left empty, if Load Balancing is not applied. System ID of the R/3 system, this field must be set for using Load Balancin g mode. It must be left empty, if Load Balancing is not applied. This is the log-on language, this field is optional. Note: We recommend using the default value (English). The IDoc Connector recognizes a few confusing error messages of the R/3 system, and replaces them with better ones. This feature does not work for non-English error messages. RfcTrace This field enables low-level RFC logging. The RFC trace is disabled by default. Note: If you change this value in the process, you have to execute Reload Configuration of IDoc Client after deploying the changes. snc_mode Secure network connection (SNC) mode. Applicable values: SAP IDoc Adapter - v6.3.5.Q4 0 25

SAP IDoc Adapter

Parameter

Description Disabled (default) 1 Enabled. SNC security level. Range:1 ... 9. This field is used only if SNC mode is enabled.

snc_qop

snc_lib

Attention: Do not use this field because it is deprecated. Changing the SNC library path must be done via the User-Config file. SNC name. It overrides the default SNC partner. This field is only used if the SNC mode is enabled. SNC partner, e.g. p:CN=R3, O=XYZ-INC, C=EN. This field is only used if the SNC mode is enabled.

snc_myname snc_partner

Configuring SendIDoc_v2
Connection Type Explicit application server Required Parameters in Connection user password lang ashost sysnr user password lang ashost sysnr gwhost gwserv user password lang mshost r3name group

Explicit application server and gateway

Load balancing

8.2 Sending Status IDocs


This are the common properties for all send status operations: Property UNAME ROUTID STATXT STATYP SAP IDoc Adapter - v6.3.5.Q4 Description This is the SAP user name for tRFC. This is the subroutine (Split/Convert/Transmission). This is the text of the status code. This is the ABAP message type (A, W, E, S, I) in the status set. 26

SAP IDoc Adapter

These properties are filled by the IDoc Connector. The values for ROUTID, STATXT, and STATYP depend on the Status value from the operations described below. Status 05 06 10 11 12 14 15 Forwarding Forwarding Acknowledgement Acknowledgement ROUTID Conversion Conversion STATXT Conversion failed. Conversion successful. Processing rule found. Forwarding of message failed. Forwarding of message successful. Report received. No report received. STATYP E S S E S S 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 IDoc Controller report queue. Parameter PreparedReportPart Description This part must contain a so-called prepared. This part can be found as attachment of the initial ReceivedIDocEvent that is generated by the IDoc Controller (xpath to this element: //ReceivedIDoc Event/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 generated by the Splitter. A reference to all received IDoc numbers can also be found in the ReceivedIDocEvent. Status REFINT REFGRP REFMES SNDPOR RCVPOR ARCKEY StatusDateTime Status that is sent for the list of IDocs. Values range: 01 ...49. (Optional) EDI Interchange name (reference to a file). (Optional) EDI-Message Group (reference to group). (Optional) EDI-Message (reference to message). (Optional) Sender port (Optional) Receiver port (Optional) Key of the external message archive (document ID in external system). Date and time of the status change. The current system time and data is used by default.

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

SAP IDoc Adapter - v6.3.5.Q4

27

SAP IDoc Adapter

If the result of the status sending is relevant and needed in the process, this operation SendSAPStatusRep ortSync should be used. The parameters of the request message are identical to the SendSAPStatusReport, the response message is a 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 special IDoc Controller report queue. Parameter PreparedReportPart Description This part must contain a so-called prepared. This part can be found as attachment of the initial ReceivedIDocEvent that is generated by the IDoc Controller (xpath to this element: //ReceivedIDoc Event/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 generated by the Splitter. A reference to all received IDoc numbers can also be found in the ReceivedIDocEvent. Status REFINT REFGRP REFMES ARCKEY StatusDateTime Status that is sent for the list of IDocs. Values range: 01 ...49. (Optional) EDI Interchange name (reference to a file). (Optional) EDI-Message Group (reference to group). (Optional) EDI-Message (reference to message). (Optional) Key of the external message archive (document ID in external system). Date and time of the status change. The current system time and data is used by default. The value provided for the StatusDateTime has to be in valid xsd:dateTime format as defined in the XML Schema specification and ISO 8601 conventions

8.2.3 SendStatus
Note: SendStatus_v2 operation corresponds to SendStatus, which is an older version and we do not recommend 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. All configuration settings for the operation are contained in the operation properties; therefore the master data is not used. Parameter Docnum SapClient Status Sndpr Description List of IDoc numbers, specifying the messages for which a status is to be sent. At least one IDoc number must be specified. SAP client name. Sent status for the list of IDocs. Applicable values range: 01 ...49. Profile of the R/3 partner who processes status IDocs. The value of the field Partner Number of the IDoc messages sender (SNDPRN) are created in order to send status codes to R/3.

SAP IDoc Adapter - v6.3.5.Q4

28

SAP IDoc Adapter

Parameter Sndprt

Description Profile of the R/3 partner who processes status IDocs.The value of the field Partner Type of the IDoc messages sender (SNDPRT) are created in order to send status codes to R/3. Profile of the R/3 partner who processes status IDocs.The value of the field Partner Role of the IDoc messages sender (SNDPFC) are created in order to send status codes to R/3. The Partner Role is left empty by default. Date and time of the status change. The current system time and data is used by default. Attention: This field is used internally. Never change this property! The field stores the transaction ID of incomplete tRFC calls. The value of this field is deleted, when a tRFC call is completed.

Sndpfc

StatusDateTime TransactionId

Connection

Connection setting properties; corresponding to the properties for the Send IDoc operation.

8.2.4 SendStatusMD
Note: SendStatusMD_v2 operation corresponds to SendStatusMD, which is an older version and we do not 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. It widely corresponds to the SendStatus _v2 operation, but the configuration settings are specified in the master data. Parameter ConnectionId Description ID of the connection that received the IDocs, for which the status is to be sent. The combination of the connectionId and SAP client determines the address which is used to send the status. List of IDoc numbers, specifying the messages for which a status is to be sent. At least one IDoc number must be specified. SAP client name. Sent status for the list of IDocs. Applicable values range: 01 ...49. Date and time of the status change. The current system time and data is used by default. The value provided for the StatusDateTime has to be in valid xsd:dateTime as defined in the XML Schema specification and ISO 8601 conventions Attention: This field is internally used. Never change this property! The field stores the transaction ID of incomplete tRFC calls. The content will be deleted after completion of the tRFC call.

Docnum SapClient Status StatusDateTime

TransactionId

SAP IDoc Adapter - v6.3.5.Q4

29

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 IDoc message. The operation contains the meta data of the received IDoc messages. Parameter ClientId Docnum Attachments StatusFeedbackConnectionID Description BIS client with fix value 000. List of IDoc numbers of received IDoc messages. IDoc file containing all IDocs which have been received in the course of the transaction. ID of the connection record over which the IDocs have been received. This ID can be used to determine the address for receiving potential status confirmations. SAP client (MANDT field) of the received IDocs. It can be used to decide how the received IDocs will be processed. The combination of the statusFeedbackConnectionID and the SAP client is usually used to determine the address, to which status confirmations will be sent. Number of IDocs that are contained in the received IDoc file. System ID of the R/3 system that has sent the IDocs. It can be used to decide how the received IDocs will be processed. 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/prepar edReports/reportMessag

SapClient

IdocCount SystemId PreparedReport

8.4 Fault Messages


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

SAP IDoc Adapter - v6.3.5.Q4

30

SAP IDoc Adapter

Parameter FaultId FaultDescription FaultDetail

Description This field is not supported. Therefore it is always set to none. This is a short non-technical description of the error. This field contains the technical description of the error. Usually this description also contains the context of the error. This field is not always available. This field contains the program context where the error occurred. This information helps the SEEBURGER technical staff to quickly provide solutions, if there are unexpected problems with the IDoc Connector. This field contains the time when the error occurred. This field is either set to COMPONENT_ERROR, if it is unlikely that the error derives from a configuration error. Or TASK_ERROR/CONFIGURA TION_ERROR, if the operations configuration is likely to be wrong. The operation will not succeed, unless the configuration is changed by the user. This field is set to true, if the operation may succeed when it is retried. The field is set to false, if the error is likely to be of a permanent nature. This field is not supported. Therefore it is always set to false. This field is either set to MAYBE_TRANSMITTED, if the IDoc file, or status IDocs may have been received by a R/3 system. In this case, the operation must be retried to guarantee that the IDocs are received exactly once. Or NOT_TRANSMITTED, if the IDoc file, or status IDocs have definitely not been received by a R/3 system.

FaultStackTrace

FaultTime FaultCategory

Retryable Fatal SendingStatus

8.5 Adapter Invocation Mode


There are different invocation modes in which the orders can be forwarded to the adapter. The mode is configured 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 the manual '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 error type 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 and assign nodes. Please refer to the topic Direct Mode GUI for details.

SAP IDoc Adapter - v6.3.5.Q4

31

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 JMS queue'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 the recommended usage for simple architectures, since this method does not require adapter configuration and queue definition. Limitation: Orders relying on hardware resources like ISDN, X.31, or X.25 cannot be used with the direct invocation since no resource management is available. Use the WorklistHandler integration instead. Note: Up to version 6.3.3 direct: was used instead of async: to specify the queue/destination. You can still 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 queue between the process and the adapter. Instead the adapter is executed synchronously from within the business process. The process does not commit the transaction as it does with asynchronous invocation, meaning it will do 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 process threads for a long time, because there is a limit for maximum simultaneously executed processes. Also there is 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 sync: sync:instanceid=MY_INSTAN CE sync:nodegroup=MY_GROUP Description The operation is executed synchronous on any running instance. The operation is executed synchronous on the node with instanceID "MY_INSTANCE". The operation is executed synchronous on any running node of the node group "MY_GROUP".

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

8.8 Worklist Handler


The SEEBURGER Worklist Handler provides an additional queuing functionality for the system (refer to the topic Adapter Invocation for another strategy). The Worklist Handler accepts orders and can place them in different queues. Each queue can be assigned to one, or more adapters to which the orders can be sent. The queue in which the order is placed thus determines to which adapter it can be sent. SAP IDoc Adapter - v6.3.5.Q4 32

SAP IDoc Adapter

In contrast to the Direct Adapter Invocation the queue configuration and the order dispatching can be configured to a more complex scenario. It supports for example polling of orders, dynamic retry handling, and resource handling. To configure the process to use a WLH queue, just enter the name of the queue in the queue part of the outbound operation. For details about this invocation mode please refer to the topic 'Adapter Invocation' in the 'Master Adapter Configuration Guide'.

SAP IDoc Adapter - v6.3.5.Q4

33

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 to use the Status IDoc template generated by the IDoc Controller. The second one is to use one of the operations SendStatusMD, 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 of using 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, a special IDoc Controller report queue is necessary. This queue is created automatically by the IDoc Controller the first time when an IDoc is received. The newly created queue (named IDocController-ReportQueue) must then be assigned to the appropriate IDoc Client node, which should send the Status IDocs back to the R/3. It uses a so-called prepared report part, which contains a Status IDoc template. The template can be used during the 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 for these status IDoc templates. The queue will automatically be created when receiving the first IDoc from the R/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 the default name of the queue is IDocController-ReportQueue. Note: Though this queue is created automatically, it has to be connected to the corresponding IDoc Connector Client manually.

9.1.3 Generation of Status IDocs in a Process


The operations sendSAPStatusReport/ sendSAPStatusReport Sync can be used at every stage of a process that has been initiated by a ReceivedIDocEvent. The ReceivedIDocEvent message part SAP IDoc Adapter - v6.3.5.Q4 34

SAP IDoc Adapter

has a special attachment (ReceivedIDocEvent/initiaionReportHandling/preparedReports/reportMessage) that carries a template status IDoc request. This attachment only has to be assigned to SAPSendStatusReportM essage/preparedReportPart/AttachmentRef. So the sendSAPStatusReport-component is able to generate a status 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/initiationRe portHandling/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 Fileport Communication


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 the EDI_DATA_INCOMING function.

The EDI_DATA_INCOMING trigger uses the parameters PORT and PATHNAME. This functionality has been extended. 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


Parameter functionName functionParameter Description (Mandatory) Name of the custom trigger. (Mandatory, at least one function parameter must be entered) Array of function parameters. Each parameter has a name, a value and a length. Index showing the function parameter which identifies the remote SAP side path. For the file port communication, it is required to have this path. If no value is added in this field, the first function parameter will be considered to be the path. The index count starts with 1 and corresponds to the index of the function parameter elements in the process.

indexOfPathnameParameter

SAP IDoc Adapter - v6.3.5.Q4

35

SAP IDoc Adapter

Configuring /SendIDocMDReq/fileportTrigger/functionParameter[n]
Parameter parameterName parameterValue maxParameterLength Description (Mandatory) Name of the function parameter. Value of the specified parameter. 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 the first call, the function is loaded in the repository and then re-used. If the dynamic list of parameters for a loaded function is changed during runtime, the new process (the one with the changed parameters) will finish with a LI NE_BUSY error, until the old function is no longer used. Then the new one is loaded, and the returned process instances (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 hold on to as long as you want, and connection pools, from which you can take a connection when you need it, and to 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 connection stays open and can be re-used (JCo will close an idle, non-acquired connection in a pool after the connection timeout period has expired). Limiting the maximum number of connections used concurrently, thus preventing the use of too many SAP resources.

The size of the connection pool can be configured via the Control Center | IDoc Client Configuration tab. The default 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 of connections too small, and thus creating waiting situations for your processes. Increase the pool size with 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 maximum load of parallel jobs is 20. It is recommended to decrease this setting, instead of increasing the JCo pool size in this use case. Note: If a LINE_BUSY error is returned with the message stating that the pool is exhausted, you can either decrease the parallel number of jobs, or increase the increase the pool size. Keep in mind the warning concerning the DIRECT mode above. SAP IDoc Adapter - v6.3.5.Q4 36

SAP IDoc Adapter

A JCo connection pool is identified by its name and is global within the Java Virtual Machine (JVM). All connections in a pool use the same system/userid/client information. The IDoc Client uses the following naming conventions: Connection Type Pool Name Form

Explicit Application Server ashost_user_client Explicit Application Server and Gateway Load Balancing r3name_user_client

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

SAP IDoc Adapter - v6.3.5.Q4

37

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 received ones, to a file. The IDocs are dumped as close as possible to the JCo implementation. That means, the IDocs are dumped as they are passed to JCo (SAP inbound communication), or received from JCo (SAP outbound communication). 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-76a60a0067b a.idoc

SAP Inbound (sent by IDoc Connector Client):


If master data is used for sending: OUT_<Name of the connection timestamp>_<UUID>.idoc If no master data is used: OUT_<application or timestamp>_<UUID>.idoc message server>_<MANDT>_<RFCuser name>_<GMT data set>_<Name of the address data set>_<GMT

Example: OUT_XIDconnection_XIDaddress_20051208T135336.982Z_07b3c760-67f2-11da-a234-fb0d0a00 67ba.idoc The files are dumped to bis6_home/data/dt/idoc/dump by default. This directory is configurable. The dumping is activated for both client and server via the .

SAP IDoc Adapter - v6.3.5.Q4

38

SAP IDoc Adapter

Property TransmissionDataDump DumpDir IDocDumpCodePage

Description This property is used to switch the dumping on/off. This is the directory where the files are dumped to. This is the code page used to write IDocs to a file, platform encoding is used as a default.

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

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 to the topic Extended Configuration Flags (page 39) for details). The output of this logger is merged to the log 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 environment variables. Variables RFC_TRACE_DIR Description This variable defines the location for the RFC trace files. If the directory does not exist, nothing is logged. If this variable is not set, the working directory is used. If this variable is set to 1 (default is 0), the complete payload is dumped. (Really big trace files are generated!). This variable sets the maximum file size in megabytes. Default: 8 MB. If this variable is set to 1 (default is 0), the RFC trace is enabled for all connections. The flag is configured in the master data connection settings for each connection separately. This is a global flag.

RFC_TRACE_DUMP RFC_MAX_TRACE RFC_TRACE

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 is operated 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 section is shown by doubleclicking the respective adapter. SAP IDoc Adapter - v6.3.5.Q4 39

SAP IDoc Adapter

Property ExtendedJcoLogging

Explanation This flag activates the JCo logging. The JCo logging is written in the log file of the IDoc Connector. Note: To get JCo logs, you have to run the general logging of the adapter at least on the DEBUG level.

Values True/false; default: false

Available for Client/Server

JcoLogLevel

This property defines the log level for the JCO logging. Note: JCo Log level is a static property for the running VM. The last value is used for all components using JCo traces. Note: Starting with level 6 the memory usage increases rapidly and there are also big performance hits caused by the dumping of the IDoc content. It is not recommended to run levels >= 6 in a productive environment for a longer 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 pool activity can be seen at this level; destination and server data events; 6 - INFO_PATH - the content of the transferred IDoc tables is dumped; 7 - SHORT_DEBUG 8 - FULL_DEBUG dispatchers' logs;

Client/ Server

SncLibPath

This is the full path to the [string]; default: Client/ Server SNC library. %bisas.home%/lib/native Note: Changing this value needs an adapter restart for the native libraries to reinitialize. If the path is not existing or accessible, this is a configuration error and will be reported as this.

SAP IDoc Adapter - v6.3.5.Q4

40

SAP IDoc Adapter

Property ConnectionPoolSize

Explanation

Values

Available for Client

This property defines the default: 20 connection pool size. For more information refer to the topic Connection pool (page 36) . This property defines the connection timeout. This property logs the connection password in clear text. [minutes]; default: 5min True/false; default: false

ConnectionPoolTimeout ShowPass

Client Client

UseSAPNativeUTF16Co depage

This property should be True/false, default: false used only, if there are problems with the default UTF-16 code page of received IDocs files. This code page uses a byte order mark, which may cause problems with some mappings. Setting this property to true will force the IDoc Controller to use code page without a byte order mark. The code page will be equal to the application server code page number of the respective SAP system. Code page number 4102 at SAP system will create UTF-16BE IDocs in BIS; 4103 will create UTF-16LE respectively. See chapter Unicode and Code Page Settings (page 42) for details. If this feature is enabled and therefore the SAP Application Server Code Page is used for received IDocs, changing the code page at SAP system (e.g. due to an upgrade or reinstallation) will also change the code page of the received IDocs in BIS 6.

Server

SAP IDoc Adapter - v6.3.5.Q4

41

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 2 bytes. For example the ASCII character 'A' is encoded as 0x00 0x41 in UTF-16 Big Endian (UTF-16BE) or 0x41 0x00 in UTF-16 Little Endian (UTF-16LE). The endianness (LE/BE) describes the technical order how the 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 socalled Byte Order Mark (BOM). Using a BOM the byte order needs not be known to the user as the program can 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 name containing 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-aware editor at the beginning of a file: Code Page Name UTF-16 UTF-16 UTF-16BE UTF-16LE UTF-8 Byte Order BE LE BE LE --Byte Order Mark (HEX) 0xFE 0xFF 0xFF 0xFE ----0xEF 0xBB 0xBF Byte Order Mark (readable characters) ----

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 beginning of 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 of such received IDocs sometimes causes problems during the further processing, e.g. in a BIC mapping with a hard-coded, non-BOM code page UTF-16LE or UTF-16BE. SAP IDoc Adapter - v6.3.5.Q4 42

SAP IDoc Adapter

For such a case the IDoc Controller is able to remove the BOM. This is achieved by switching from the default code page UTF-16 (with a BOM) to a non-BOM code page UTF-16BE/UTF-16LE. Which of the two non-BOM code pages is effectively used, depends on the code page that is installed at the connected SAP system. The SAP code page number 4102 is mapped to UTF-16BE, 4103 is mapped to UTF-16LE in BIS 6). See chapter Extended Configuration (page 39) on how to enable this feature. The specifics of handling unicode-encoded files for both IDoc Connector Client and IDoc Connector Controller are described in this table: Code page UTF-16 (default code page) IDoc Connector Client The IDoc message must be prepared with the appropriate BOM for sending. Otherwise, no parsing is possible. IDoc Connector Server UTF-16 is the default code page IDoc Connector uses for received Unicode IDocs. The post-processing steps (e.g. mapping) must be BOM-aware. These code pages are used for received IDocs when the extended setting UseSAPNativeUnicodeCo depage is enabled (page 39). The endianness depends on the installed code page at SAP (TA SNL1). Remarks Do not use hard-coded source encoding settings in mappings.

UTF-16LE/ UTF-16BE

The endianness is implicitly determined by the very name of the code page; therefore files in this encoding must not have a BOM at the beginning.

These code pages always need to provide the used endianness externally, as there is no BOM that may be used for implicit determination.

UTF-8 without BOM

8-bit characters must be This code page is encoded with two or more not used for RFC bytes. transmission. No BOM at the beginning. Unicode IDoc messages received via file port are mostly UTF-8 encoded. SAP is able to create files with a BOM. The IDoc Connector server cannot skip the BOM, therefore it is also recommended to remove the BOM before sending those files to BIS 6. The UTF-8 BOM comprise the following characters: 0xEF 0xBB 0xBF (looks like this in ASCII: " ").

UTF-8 with BOM

The BOM cannot be skipped by the IDoc Connector client. Therefore, the parsing (and sending) corresponding IDoc messages fails. (Error message: IDoc contains a data record where a control record is required. Near line 1 (IDoc number x)). Remove the BOM before sending UTF-8 files.

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 that do not have an explicitly defined code page. It is configured in the SAP Address master data (page 19). This setting is not relevant for receving IDocs with IDoc Connector Controller.

SAP IDoc Adapter - v6.3.5.Q4

43

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 Code SM59 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 the Unicode test in TA SM59. If BIS 6 registration are configured as non-Unicode at a Unicode SAP system, the following error string can be seen at BIS 6 after receiving an IDoc: "IDoc contains a data record where a control record is required. Near line 1 (IDoc number x)" Non-Unicode communication with Unicode systems is not supported by SAP Java Connector, which is used by BIS6 IDoc Connector. This type of function would not make sense because Java is always based on an U nicode 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: In SNL1 choose menu "CodePages" --> "Application server codepages" --> "execeute" button: see parameter CODEPAGE in return list. If the SAP system is Unicode-enabled, the code pages 4102 (UTF-16BE) and 4103 (UTF-16LE) are used 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 when communication 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 IDocs using 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 proper operation. The required memory depends on the number of records of all IDocs that are transferred within a single transaction. The following table illustrates the amount of memory that is required by the IDoc Connector client and the IDoc connector server depending on the number of transferred records, if they are running on the Microsoft Windows operating system. No. Records of the Overall Java Heap Memory in [MB] transferred file IDoc Unicode 1 8 Non-Unicode 19 Unicode 18 Non-Unicode 18 44

Receiving IDocs from R/3

Sending IDocs to R/3

SAP IDoc Adapter - v6.3.5.Q4

SAP IDoc Adapter

No. Records of the Overall Java Heap Memory in [MB] transferred file 1.000 5.000 10.000 20.000 30.000 40.000 50.000 60.000 80.000 100.000 120.000 150.000 n IDoc Unicode 20 71 107 194 276 358 463 522 686 875 1014 1309 0.0082n + 29.801 Non-Unicode 20 58 72 136 188 240 313 344 448 578 656 804 0.0052n + 31.447 Unicode 31 79 129 242 371 464 531 627 836 1011 1231 1491 0.0096n + 51.265 Non-Unicode 28 65 104 179 243 326 395 474 614 770 913 1135 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: The number of lines of an IDoc file multiplied by the number of transactions running in parallel. The maximum load setting of the IDoc Connector client node determines the number of parallel transactions when sending IDocs to the R/3. Respectively, the number of connections in the registration master data of the IDoc Connector server multiplied by the number of (active) registrations determines the number of parallel transactions when receiving 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 memory management. The client memory management can be (de)activated via the Adapter Control Center. Property ActivateMemoryCheck BasicLoadValue Description The flag for the activation of Memory Management. By default the Memory Management is activated. This is the value for the basic memory load of the server. The default size is 520MByte. This value corresponds to an idle JBoss server with all DT adapters running idle, too. The basic load value is checked, also at adapter runtime (please refer to the topic Determination of the Server Basic Load (page 46) ). This is a relative factor defined as a percentage value based on the available heap for transaction. The minimum recommended size is 5%.

SecurityBuffer

When the memory management is activated, a virtual memory pool is created. The pool size is determined as 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 - v6.3.5.Q4 45

SAP IDoc Adapter

Enough heap space must be available. The needed memory for sending an IDoc must be smaller than the total available memory for usage (virtual memory pool size n% of the pool size, where n% is the security buffer value). If the needed memory is bigger than the available memory for usage, the order will be rejected with a non-re-triable error. The IDoc is not processable on that system, and will have to be split in smaller parts. Enough free heap available in the memory pool. The required memory for sending an IDoc must be smaller than the current virtual memory pool size n% of the pool size, where n% is the security buffer value. 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 at adapter runtime. Adapter start up: The basic load value is calculated, and then compared with the one in User Configuration. 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 the memory 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 memory pool is reconfigured. The runtime determination of the basic load is helpful for the following reason: The default basic load value in the User Configuration file is 520Mb. This value corresponds to an idle JBoss server with all DT adapters running idle, too. But when the IDoc Connector client is running idle on an external node (recommended), the basic load value is only 270Mb. With the runtime determination, the memory pool size will always be optimal even 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 with IDoc 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 dedicated minimum authorization profile for the RFC communication between an external program (i.e. the IDoc Client Connetor) 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 transaction code (hereinafter referred to as TA) SU01). No dialog user is needed, unless you want to debug a called program in SAP. The minimum authorization profile for RFC communication can be defined according to the following instructions. The steps to create a role may be omitted if an existing role/profile is adapted only. If this is the case, 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 - v6.3.5.Q4

46

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 you are prompted.

SAP IDoc Adapter - v6.3.5.Q4

47

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 - v6.3.5.Q4

48

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 partner profile (TA WE20)>

Note: If the function module name behind the process code in WE20 partner profile uses further modules than EDIN, simply send a test IDoc using a user assigned to this newly created role and check for 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 do not want to define a restriction, simply choose *, otherwise e.g. add SYSTAT for receiving status IDocs. 10.Save the profile.

SAP IDoc Adapter - v6.3.5.Q4

49

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 any other role or authorization profile assignments (use TA SU01 again to verify the assignments). 13.Start the user comparison.

SAP IDoc Adapter - v6.3.5.Q4

50

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 not required, 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 to Registered 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 instead of Registered Server Program, for some releases of the R/3. If the Activation Type cannot be set in the dialog, 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 case of complex scenarios, to ensure that the program ID is unique, it is recommended to include the destinations host name in the program ID. 11.Enter the gateway host and the gateway service (usually sapgw00) in the Gateway Options. This step is optional, 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/3 releases. SAP IDoc Adapter - v6.3.5.Q4 51

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 are correct.

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 is used, 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 function would not make sense because Java is always based on an Unicode character set. For more information please 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 partner profiles. 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 the address 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 will be 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 the fastest way of sending information to a partner. The IDoc is received by the IDoc Controller and is immediately forwarded 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 processed in different conversion/forwarding processes by the BIS 6 Integration Engine. This e.g. results in many short EDIFACT 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. This has two advantages for the user: Firstly the tRFC communication will get more efficient, if several IDocs are also processed in a single tRFC call and the number of invoked processes in BIS 6 is reduced. The second obvious advantage for the recipient of the converted IDocs is the significantly reduced number of EDIFACT interchanges, 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 individual partner. A general collection interval in BIS 6 would have the disadvantage that all IDocs (regardless of the partner) would be processed using the same interval. By collecting the IDocs for each partner, the packet size and batching interval can be configured individually. SAP IDoc Adapter - v6.3.5.Q4 52

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 be configured. 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 too big, and the tRFC transmission could run into a timeout. The report RSEOUT00 should be scheduled as batch job (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 outbound processing and unselect the flag start IDoc outbound processing immediately in the dialog box. The IDocs will be created, and are ready to be sent (status 30) afterwards. By starting the report RSEOUT00 (SE38) these IDocs 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 the available 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 will be created two full packets with 50 IDocs, and the last transmission will transport the remaining (here: the remainder of 102 mod 50 == 2) IDocs.

SAP IDoc Adapter - v6.3.5.Q4

53

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, and about errors that occurred in the component. The current status contains a short description of what the component is currently doing, and a counter that counts how many tasks the component has processed since startup. 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 the DT-Monitor. Therefore, when troubleshooting the IDoc Connector, the DT-Monitor can be used as a convenient substitute for the log. However, a few classes of errors (e.g. failure to connect with the DT-Monitor) are not reported 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 Configuration Guide -> Monitoring -> Filter The IDoc Connector Controller introduces an adapter specific filter IDoc Number. Using this field one can filter for 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 IDoc number 833381 - Filtering by '08%81' will result in displaying a transaction record with IDoc number starting with 8 and ending 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 connection of the IDoc Connector Server to the R/3 system.

SAP IDoc Adapter - v6.3.5.Q4

54

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 with other systems. It provides an effective overview over what is happening in the R/3 system with regard to IDoc exchanges.

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 IDoc to 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 IDoc has been received by the IDoc Connector Server. The BIS monitoring facilities must be used, to ensure that the 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 IDoc from the IDoc Connector Client, but did not process the IDoc. Either the source IDoc is invalid, or the R/3 system 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 outbound IDocs that are currently active, or that have failed. Furthermore incomplete transactions can be retried with the Edit | Execute LUW (F6) command. The transaction SM58 reveals the error cause, if an outbound IDoc has IDoc-Status 3, but the IDoc has not been received by the IDoc Connector Server.

SAP IDoc Adapter - v6.3.5.Q4

55

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 its mailbox 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 Number of executions Number of parallel executions Description Configures how often an interaction is executed after the button Executed is clicked. Default is 1. Configures how many interactions are executed parallel. This can be used for testing parallel transmission of files for example. The default value is 1. The maximum parallel execution is 30. If this flag is enabled, all information about the request and the response will be available for monitoring. Also the request and response attachments will be available to show. If the flag is disabled, no information is available after the interaction is finished. Only the protocol is shown, which states which interaction was finished successfully and which not. Shows the number of the interaction for which the Request/Response tab is shown. Creates a new interaction. Starts the execution of the interaction. Click this button to cancel all scheduled interactions. The running interaction will run until it is finished, but no new one will be started. Shows the request which is forwarded to the adapter. Shows the response the interaction got from the adapter Shows which interaction was finished successfully, and which was finished with an error. Using the context menu the Request/Response details can be shown.

Persist details

Displayed details for interaction number New button Execute button Stop button Request tab Response tab Protocol tab

Supported interactions: Interaction Send IDoc Send IDoc status SAP IDoc Adapter - v6.3.5.Q4 Description Transmit an arbitrary IDoc file to SAP. Generate a status IDoc for a given IDoc number. 56

SAP IDoc Adapter

Description of the form fields: Attribute IDoc address Encoding of IDoc file Path to file IDoc connection SAP client IDoc number IDoc status code Description Destination address to which the IDoc is sent (Send IDoc only). Encoding of the IDoc which is transferred (Send IDoc only). Path to IDoc file (Send IDoc only). Connection to which the status IDoc is sent to (Send IDoc status only). The SAP client (MANDT) of the receiving SAP system (Send IDoc status only). The IDoc number for which the status IDoc is generated (Send IDoc status only). Two digit status code which is to be generated for the given IDoc number (Send IDoc status only).

SAP IDoc Adapter - v6.3.5.Q4

57

SAP IDoc Adapter

13 Troubleshooting

13.1 Resolving Problems When Sending IDocs


Symptom No Status IDoc messages are sent. Solution Make sure that the IDocController-ReportQueue is connected to the appropriate IDoc client.

No Status IDocs are received Check the Status IDoc settings in the applied SAP address (usually the in R/3, although the IDoc Client sender is still empty), and make sure that the partner configured there is seems to send them. allowed to receive Status IDocs. (Type STATUS must be set for inbound parameter in the used partner definition in WE20). The IDocs are sent to R/3, but in WE02, the IDoc messages still have status 56 and are not processed. The Details view of the control set shows interchanged sender and receiver. 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 (page 23)for details).

13.2 Resolving Problems When Receiving IDocs


Symptom Solution BIS processes which should Step 1: Find out whether the R/3 system tried to send IDoc messages. be triggered by the R/3 system are not running. 1. Go to the transaction WE02 - Display IDoc to see whether IDoc messages have been transfered to the ALE layer of the R/3 system. If there are no outbound IDoc messages or the indicators ("traffic lights") for the IDocs are red or yellow, the configuration of the R/3 system is defective. 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 IDoc files.

SAP IDoc Adapter - v6.3.5.Q4

58

SAP IDoc Adapter

Symptom

Solution 1. In the corresponding monitor, check for waiting messages.(Perhaps no process has been deployed). 2. In the Recovery Monitor, check the open incoming transactions. They must have also an entry in R/3 transaction SM58. Common sources of error: Processes are not triggered, since the settings for the initiator rules and initiator ports are missing or incorrect. The IDoc Connector servers master data does not match the R/3 systems configuration. Network problems.

Step 3: Fix the problem. 1. If the transaction SM58 (Transactional RFC) indicates that there are problems with the RFC server, consult the IDoc Connector servers log files to see what the IDoc Connector server is doing and whether any errors occurred. 2. The IDoc Connector server accepts IDoc messages from the R/3 system even if BIS 6 cannot send the received messages to the central instance. Therefore, the transaction SM58 can only be used to recognize problems which have directly been caused by the IDoc Connector server, the R/3 system or the network. 3. If network problems between the IDoc Connector server and the R/3 system are suspected, go to the transaction SM59, select the appropriate RFC destination from the TCP/IP connections, finally click Test connection (F8) to test the RFC connectivity.

SAP IDoc Adapter - v6.3.5.Q4

59

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 available memory. Therefore, transferring very large IDocs (e.g., CAD IDocs, or files containing many IDocs) will affect the systems performance substantially, if the operation is executable at all. This particularly applies for 32bit operating systems, e.g. 32bit operating systems with a virtual address space limit of 2-GB, the IDoc files should not consist of more than 150.000 records. Hence, where transactions involving very large 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 - v6.3.5.Q4

60

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 this quick start example have been completed, the R/3 system and BIS 6 have been configured to perform the following 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 may slightly differ. The steps that are described in the quick start example refer to an environment that is described in the tables below.

BIS Properties
Property Windows (32Bit) d:\bis6_home 000 Description Operating system that hosts the IDoc Connector BIS 6 directory BIS 6 client

IDoc Properties
Property TXTRAW01 SEEPORT SEEDEMO KU partner role Description Basic type of the IDoc Partner port Partner number Partner type [empty]

SAP IDoc Adapter - v6.3.5.Q4

61

SAP IDoc Adapter

Connection Properties
Property gatewayhost sapgw00 apphost 00 SEERFCUSER 100 Description Gateway host Gateway service Application server host System instance number User SAP client

SAP Properties
Property SID sapconnector SEEBURGER DEMO Description R/3 system ID Program ID RFC destination

A.1 Installation
After installing the IDoc Connector with the BIS 6 setup procedure, perform the following steps to complete installation: 1. Download the file sapjco3-NTintel-3.0.8.zip (or the proper one for your system) from http://service.sap.co m/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 common installation 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 - v6.3.5.Q4

62

SAP IDoc Adapter

Figure A-1: Master Data Configuration

7. Enter the settings for the status confirmations. 8. Save the data set.

SAP IDoc Adapter - v6.3.5.Q4

63

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 SAP system. 12.Save the data set.

SAP IDoc Adapter - v6.3.5.Q4

64

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 Handling OK). 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 ReceivedIDocEven t operation. 4. Insert the SendIDocMD_v2 operation (from SAPConnectorClient tasks) after the sendSAPStatusReport operation. SAP IDoc Adapter - v6.3.5.Q4 65

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 to send Status IDocs with status 10 back to the R/3 system: Assign the prepared report template of the ReceivedIDocEvent (path: /ReceivedIDocEvent/initiatio nReportHandling/preparedReports/reportMessage) to the preparedReportPart of the sendSAPStat usReport (path: /sendSAPStatusReport/preparedReportPart/AttachmentRef). Assign all the docnumbers of the received IDocs (path: /ReceivedIDocEvent/docnum to the sendS APStatusReport (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 the received 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 the content of the Record field to the Windows clipboard. Assign /ReceivedIDocEvent.attachments to /SendIDocMD/attachments. Assign IDocConnector-Queue to queue. 66

SAP IDoc Adapter - v6.3.5.Q4

SAP IDoc Adapter

The queue will be generated automatically when the process is activated, but do not forget to connect it to the IDoc Connector client. 3. Assign the properties of the second sendSAPStatusReport component of the process that are necessary to send Status IDocs with status 38 back to the R/3 system: Assign the prepared report template of the ReceivedIDocEvent (path: /ReceivedIDocEvent/initiatio nReportHandling/preparedReports/reportMessage) to the preparedReportPart of the sendSAPStat usReport (path: /sendSAPStatusReport/preparedReportPart/AttachmentRef). Assign all the docnumbers of the received IDocs (path: /ReceivedIDocEvent/docnum to the sendS APStatusReport (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 will have 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 - v6.3.5.Q4

67

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 - v6.3.5.Q4

68

SAP IDoc Adapter

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

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 - v6.3.5.Q4

69

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 SEERFCU SER. 9. Click the Save (Ctrl+S) button. 10.Add the outbound parameters. SAP IDoc Adapter - v6.3.5.Q4 70

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 - v6.3.5.Q4

71

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 - v6.3.5.Q4

72

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 - v6.3.5.Q4

73

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 IDoc based on an existing one.

SAP IDoc Adapter - v6.3.5.Q4

74

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 shown below.

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 of the control record is empty. To ensure that the Archive Key is empty, click on the All Fields button, scroll down three pages, and check the Archive Key field. If the Archive Key is not empty, this message pops up:

SAP IDoc Adapter - v6.3.5.Q4

75

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 will pop 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 of the IDoc Connector server and its log contains two entries that claim Task succeeded: Received IDocs were delivered to the integration system. You may also check with the DT-Monitor that the number of finished processes has been increased by two. The process that has been created in the topic Receiving Treatment (page 65) ran two times. Therefore the 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 check with 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/3 system. 2. Go to the transaction WE02 to display the IDocs that have been processed. SAP IDoc Adapter - v6.3.5.Q4 76

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 - v6.3.5.Q4

77

SAP IDoc Adapter

Note: The IDocs that have been sent back to the R/3 system cannot be processed, because the Inbound Partner Profile is not configured to process IDocs of type TXTRAW. Therefore the traffic lights in 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 be specified, 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 on the Process code. For the ED00 Process code, the traffic lights should be yellow.

SAP IDoc Adapter - v6.3.5.Q4

78

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. 5. Save the data set.

SAP IDoc Adapter - v6.3.5.Q4

79

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 - v6.3.5.Q4

80

SAP IDoc Adapter

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

3. Save the data set. 4. Create a new file port Listener. 5. Set Connection for Status IDocs to SID system. 6. Set Local path to Z:\. 7. Save the data set.

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 IDoc based on an existing one.

SAP IDoc Adapter - v6.3.5.Q4

81

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 shown below.

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 - v6.3.5.Q4

82

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 l ibsapjco3.so, or returns a similar message. What has to be done in order to update the shared libraries used by SAP JCo on AIX? A: Updating the shared libraries of SAP JCo that are used by the BIS 6 IDoc Connector requires a special procedure (described below:) Background If AIX loads a shared library into the memory, the image of that library is kept in the memory, even if no process is using the library. If the on-disk copy of the library is altered, then applications using that library still use the in-memory copy, and not the updated disk copy. This represents the expected standard behavior with AIX. In the case of applying a new version of SAP JCo shared libraries, shutting down all BIS 6-JBoss still leaves shared libraries in the memory (e.g. librfccm.so stays in memory). Copying the version of the libraries updates the disk copy, but a subsequent startup of an IDOC Connector instance uses the inmemory 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 IDoc Connector installation. 2. Run the AIX command /usr/sbin/slibclean as root to clean all non-referenced libraries of SAP JCo from 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 on the 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 reads partner <IP of R/3 system> not reached. The R/3 system is located behind a firewall and its "real" IP address cannot 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 see SAPNote 148832 for further details.

SAP IDoc Adapter - v6.3.5.Q4

83

SAP IDoc Adapter

Q: In IDoc inbound processing via the file interface, an error message occurs: IDoc: Event for starting inbound processing 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 be triggered. The solution consists of two steps which you must edit consecutively. 1. Check the workflow Customizing. The Customizing must be complete for the workflow runtime environment. 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 control record. 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 read correctly. 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, Unicode files are only processed with a set Unicode flag, if the control records are marked with EDI_DC40_U but not with EDI_DC40. The answer is that they are both correct, but the ones are only applicable for Unicode enabled file ports.

SAP IDoc Adapter - v6.3.5.Q4

84

SAP IDoc Adapter

D Performance Considerations

The effective performance of the IDoc Connector depends on a number of factors. This topic explains the major factors and presents some general guidelines for archiving a reasonably good performance with the IDoc 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 limited amount of memory (e.g. a system with only 1GB of RAM) the number of records per transaction should range from 5.000 up to 20.000. For systems with plenty of memory a bigger transfer size is preferred: The number of records per transaction should range from 10.000 up to 100.000. Attention: Sending and receiving of single IDocs per transaction will result in unsatisfactory performance of the IDoc Connector. Always queue IDocs to transfer them as one large chunk for good performance. For sending IDocs the SEEBURGER Business Integration Converter (BIC) should be used to merge multiple IDocs 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 IDoc version 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 one transaction. 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 expected average number of records of each IDoc.

SAP IDoc Adapter - v6.3.5.Q4

85

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 socalled 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 the IDoc 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 server does 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-sized overhead is reduced, however it has to be kept in mind that larger transactions require much more memory.

SAP IDoc Adapter - v6.3.5.Q4

86

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 user authentication based on passwords. With SNC, you can extend the SAP system security beyond these basic measures 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 SNCprotected components. You receive an individual approach. You use the security product of your choice, choosing the algorithms you want to use. You can change the security product at any time without affecting SAP system business applications.

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

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 SAPCry ptolib to avoid any conflicts. Furthermore SAPSeculib only supports very short key lengths and the DSA algorithm only. See SAP note 578377 for details). 2. Copy the ticket file that is included in the SAPCryptolib package to /usr/sap/<SID>/DVEBMGS<system no.>/sec. 3. Make sure the environment variable SECULIB is set for both the user <SID>ADM and on MS Windows R/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 transaction RZ10): 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. 87

SAP IDoc Adapter - v6.3.5.Q4

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 Users Guide. Licencing: SAPCryptolib It may be used to secure communications between SAP components, please make sure 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/sec directory. 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 certificate administrator). It is recommended to set this variable in the set-dir script of BIS 6 and in the environment of the SNC certificate administrator. 4. To check the correct setting of the variable SECUDIR, run <BIS_home>/lib/native/sapgenpse. The value of 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 repeated on each cluster node, or make the files available as a cluster resource. The same is true for the configuration files 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 generating the configuration files.

SAP IDoc Adapter - v6.3.5.Q4

88

SAP IDoc Adapter

5.2 Configuration
For SNC secured communication a so-called Personal Security Environment (PSE) for the SAP user who is used for the inbound RFC communication has to be created and mapped to this users account in R/3. This identity 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 its export 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 cluster nodes, or being made accessible through a shared volume. So all files can be reused in the whole cluster environment without any change. If this is not possible, please generate a single PSE on a node and copy it to 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 be used 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 being created 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 O=SEEBURGER AG, C=DE

PSE

<SECUDIR>\bisuser.pse

CN=bisuser,

OU=Connectors,

Note: The option O is needed if the SEEBURGER IDoc Connector is run by another user than the one being used for generating this PSE and credential files. This is usually the case in a cluster environment. Use the Windows user, or the Unix UID for the O parameter. Use the domain SYSTEM , 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 name somewhere: 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 are allowed for SNC connections.

SAP IDoc Adapter - v6.3.5.Q4

89

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 is not 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 users PSE before. Make sure to select BASE64 encoding.

SAP IDoc Adapter - v6.3.5.Q4

90

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 as a trusted certificate for your systems PSE.

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

SAP IDoc Adapter - v6.3.5.Q4

91

SAP IDoc Adapter

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

SAP IDoc Adapter - v6.3.5.Q4

92

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:<distinguis hed_name> Example: p:CN=bisuser, OU=Connectors, O=SEEBURGER AG, C=DE It is important that the name is determined as canonical (see the dialog), this message should be shown after having saved the dataset.

SAP IDoc Adapter - v6.3.5.Q4

93

SAP IDoc Adapter

Figure 5-4: Transaction SU01

8. Now return to the transaction STRUST and export the systems 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 systems certificate to a local file on the SEEBURGER system.

SAP IDoc Adapter - v6.3.5.Q4

94

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 same distinguished name as the one mapped to the RFC user account before.

SAP IDoc Adapter - v6.3.5.Q4

95

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 - v6.3.5.Q4

96

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"> <!-- If SNC is enabled, the full SNC library path must be provided here. --> <property name="SncLibPath" type="java.lang.String"> <BIS6_Home>/lib/native</property> </node>

SAP IDoc Adapter - v6.3.5.Q4

97

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 avoid manipulations). 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 used by the registrations, the distinguished name (returned by the sapgenpse get_my_name command) has to be entered 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=DE The SNC partner name is used by the client for the SAP Inbound connections. Enter the distinguished name of the R/3 application server (the value being returned by the command sapgenpse maintain_pk l) plus the prep-ended p: for SAPCryptolib. In our case the name p:CN=SEP, O=SEEBURGER would be used. SAP IDoc Adapter - v6.3.5.Q4 98

SAP IDoc Adapter

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

SAP IDoc Adapter - v6.3.5.Q4

99