SEEBURGER EDI

SAP IDoc Adapter

Version: v6.3.5.Q4

June 28, 2013

Table of Contents

1 Terms and Definitions

1

2 Introduction

2

3 Basics

3

3.1 IDoc Con Connector

3

3.1.1 IDoc Connector Server

3

3.1.2 IDoc Connector Client

3

3.2 Applicatio Application Link Enabling (ALE)

3

3.3 Intermedi Intermediate Document (IDoc)

4

3.4 Status Co Confirmation

4

3.5 Transacti Transactional Remote Function Call (tRFC)

4

3.6 SAP Java Java Connector (JCo)

4

4 Overview

5

4.1 Features a Features an nd Restrictions

5

4.2 Sys System Requirements

6

4.3 Integration

7

4.4 Log Logical Systems

7

5 Installat Installation

9

5.1 SAP Java Connector (JCo) Installation

9

5.1.1 Applicable JCo Versions

9

5.1.2 Obtaining the Correct JCo Libraries from the SAP Service Marketplace

9

5.1.3 Installation

10

5.1.4 Troubleshooting

10

Table of Contents


1

2 Introduction

2

3 Basics

3

3.1 IDoc Con Connector

3

3.1.1 IDoc Connector Server

3

3.1.2 IDoc Connector Client

3

3.2 Applicatio Application Link Enabling (ALE)

3

3.3 Intermedi Intermediate Document (IDoc)

4

3.4 Status Co Confirmation

4

3.5 Transacti Transactional Remote Function Call (tRFC)

4

3.6 SAP Java Java Connector (JCo)

4

4 Overview

5

4.1 Features a Features an nd Restrictions

5

4.2 Sys System Requirements

6

4.3 Integration

7

4.4 Log Logical Systems

7

5 Installat Installation

9

5.1 SAP Java Connector (JCo) Installation

9

5.1.1 Applicable JCo Versions

9

5.1.2 Obtaining the Correct JCo Libraries from the SAP Service Marketplace

9

5.1.3 Installation

10

5.1.4 Troubleshooting

10

5.2 Available Versions of JCo for Different Architectures

6 Usage

11

13

6.1 Adapter Control over the Control Center

13

6.2 Operations

14

6.3 Monitoring

15

7 Master Data Configuration

16

7.1 Configuring Connections

16

7.2 Common Connection Settings

16

7.2.1 Settings

16

7.2.2 Send-Site (SAP inbound)

16

7.2.3 Extended

17

7.3 Configuring Addresses

19

7.4 Configuring Registrations

19

7.4.1 Settings Tab 7.5 Configuring File Port Listeners 7.5.1 Settings Tab

8 Process Process Configuration 8.1 Sending IDocs (SAP Inbound)

21 21 22

23 23

8.1.1 SendIDocMD

23

8.1.2 SendIDoc

24

8.2 Sending Status IDocs

26

8.2.1 SendSAPStatusReport

27

8.2.2 SendSAPStatusReportSync

27

8.2.3 SendStatus

28

8.2.4 SendStatusMD

29

8.3 Receiving IDocs (SAP Outbound)

30

8.3.1 ReceivedIDocEvent

30

8.4 Fault Messages

30

8.4.1 DtFault

30

8.5 Adapter Invocation Mode

31

8.6 Direct Invocation

31

8.7 Synchronous Adapter Invocation

32

8.8 Worklist Handler

9 Extended Features 9.1 Status IDoc Handling

32

34 34

9.1.1 Using the Generated Status IDoc Template

34

9.1.2 Queue for Status IDocs

34

9.1.3 Generation of Status IDocs in a Process

34

9.2 Customizable RFC Trigger Function for Fileport Communication

35

9.3 Connection Pool

36

10 Adapter Configuration

38

10.1 Dumping

38

10.2 Logging

39

10.2.1 JCo Logging

39

10.2.2 RFC Tracing

39

10.3 Extended Configuration Flags

39

10.4 Unicode and Code Page Settings

42

10.4.1 Unicode Code Pages

42

10.4.2 Unicode Settings in SAP

44

10.5 Memory Requirements 10.5.1 IDoc Connector Client Memory Management 10.6 Configuration within R/3

44 45 46

10.6.1 Creating a Minimum Authorization Profile for an RFC User

46

10.6.2 RFC Destination

51

10.6.3 Status Processing

52

10.7 Batching IDocs in R3

52

10.7.1 Scenario Description

52

10.7.2 Configuration in R3

53

10.7.3 Testing

53

11 Monitoring

54

11.1 Adapter Monitor

54

11.2 Filter

54

11.3 R/3 System

54

12 Adapter Interactions

56

13 Troubleshooting

58

13.1 Resolving Problems When Sending IDocs

58

13.2 Resolving Problems When Receiving IDocs

58

14 Known Restrictions

60

A Sample Scenario – Using tRFC

61

A.1 Installation

62

A.2 Master Data Configuration

62

A.3 Receiving Treatment

65

A.4 Configuration within R/3

67

A.5 Running the Sample Scenario Process

74

B Sample Scenario – Using File Port

79

B.1 File Port Configuration

79

B.2 Master Data Configuration

80

B.3 Running the Sample Scenario Process

81

C FAQ

83

D Performance Considerations

85

D.1 Size of the Transferred IDocs

85

D.2 Available Free Memory

86

5 Secure Network Communication (SNC)

87

5.1 Prerequisite

87

5.1.1 R/3

87

5.1.2 SEEBURGER System

88

5.2 Configuration

89

5.2.1 Generation of PSE file

89

5.2.2 Configuring R/3

90

5.2.3 Master Data Configuration

97

Copyright (c) 2013 SEEBURGER AG (http://www.seeburger.de). All rights reserved. If (registered or pending) trademarks are named in this document, the rights of the respective 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


Terms

Definition

IDoc

Intermediate Document

ALE

Application Link Enabling

tRFC

Transactional Remote Function Call

JCo

SAP Java Connector

SAP IDoc Adapter - v6.3.5.Q4

1

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.


2

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.


3

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 con tain 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.


4

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.


5

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

Requirement

SAP Java Connector

SAP JCo Version >=3.0.8

R/3 system

The release 3.1h or later.

Network

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

The SAP Java Connector (JCo) must be pre-installed before running the component. The SAP Java 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.


6

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 .


7

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 therefor e 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. That’s why the file port listener's duplicate check is performed on the SAP side paths.


8

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

• •

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): /lib/ext/sapjco3.jar

/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


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

Architecture

JVM Vendor

Archive File

Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008

x86 32bit

Sun

sapjco3-NTintel-3.0.8.zip

Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008

x86_64 64bit

Sun

sapjco3-NTAMD64-3.0.8 .zip

Native DLL name: sapjco3.dll

Linux OS

Architecture

JVM Version

Archive File

SuSE SLES10, RedHat EL5

x86 32bit

Sun

sapjco3-linuxintel-3.0.8.t gz

SuSE SLES10, RedHat EL5

x86_64 64bit

Sun

sapjco3-linuxx86_64-3.0. 8.tgz

Native library name: libsapjco3.so


11

SAP IDoc Adapter

Solaris OS

Architecture

JVM Version

Archive File

Solaris 10

SPARC 64bit

Sun

sapjco3-sun_64-3.0.8.tgz

Solaris 10

x86_64 64bit

Sun

sapjco3-sunx86_64-3.0.8 .tgz

Native library name: libsapjco3.so

AIX OS AIX 5.3, AIX 6.1

Architecture Power PC 64bit

JVM Version IBM

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) fo r installation on AIX.

HP-UX OS HP-UX B11.23, B11.31

Architecture Itanium 64bit

JVM Version HP

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.


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.


13

SAP IDoc Adapter

6.2 Operations IDoc Connector Client Parameter

Definition

SendIDoc_v2

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

SendIDocMD_v2

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

SendStatus_v2

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

SendStatusMD_v2

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

SendSAPStatusReport

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.

SendSAPStatusReportSync

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.

SendIDoc

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).

IDoc Connector Server Parameter

Definition

ReceivedIDocEvent

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


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

Description

Adapter Monitor

Provides runtime information.

Recovery Monitor

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

Transaction 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.


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

Description

Gateway host

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.

Gateway service

TCP service number of the SAP gateway. The gateway service (e.g. sapgw00 ) is an alias for the TCP port, which is used to connect to the SAP gateway. The TCP port is a concatenation of the digits 33 (=sapgw ) and 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.

7.2.2 Send-Site (SAP inbound) Parameter/Option

Description

User

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


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

This is the SAP log-on password.

Connection type

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 /system3 2/drivers/etc . This entry in this file may look similar to this: sapms

36/tcp

1.Replace with the System ID of the R/3 system. 2.Replace 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.

System number

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 .

Message server

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

Group

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.

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.


17

SAP IDoc Adapter

Parameter/Option

Description

Language

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.

Enable RFC trace

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 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) .

Security level

The following security levels can be configured for SNC: •

Authentication

•

Integrity protection

•

Encryption

•

Default setting of destination

•

Max. available

It is recommended to select the Default setting defined in the SAP Instance profile. Own SNC name

The name returned by the sapgenpse get_my_name command has to be entered here.

Partner's SNC name

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

Description

Use file port

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

Port name

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

Local path for the file port's physical directory.

SAP-site path

Path for the file port's physical directory.

File mask

File mask for the SAP inbounds IDocs.

Port is Unicode-enabled

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

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


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.

SAP client

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)

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


19

SAP IDoc Adapter

Parameter/Option

Description

Name

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.

Server type

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

Enabled

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

Listener group

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.


20

SAP IDoc Adapter

7.4.1 Settings Tab Parameter/Option

Description

Connection to SAP gateway

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.

Program ID

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

Number of connections

This is the number of parallel connections that are used for receiving 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, ...

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

Description

Name

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.

Listener group

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.


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

Description

Connection for Status IDocs

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.

Local path

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

File mask

This is the file mask for the SAP outbound IDocs. By default this mask is set to *.ido . Note: The file port mask is case-sensitive.

Code page

This is the encoding of the received IDoc files.

Polling interval (ms)

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


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

Description

SAP client (MANDT )

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.

IDoc number (DOCNUM )

Completely ignored by the IDoc Connector Client, since the IDoc number is generated by the R/3 system when it receives the IDoc.

Direction (DIRECT )

If the setting for the direction is set to 1 (outbound), the IDoc 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.

Receiver port (RCVPOR )

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.

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


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

Description

SAP client (MANDT )

Ignored by the IDoc Connector Client.

IDoc number (DOCNUM )

Ignored by the IDoc Connector Client, since the IDoc number is generated by the R/3 system when it receives IDocs.

Segment number (SEGNUM )

Ignored by the IDoc Connector Client. The segment numbers are generated by the IDoc Connector.

Settings for the operation: Operation parameter

Description

ClientId

BIS logical system client

DestinationAddressId

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

Attachments

IDoc file that is to be sent. Note that exactly one IDoc file must 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.

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.


24

SAP IDoc Adapter

Parameter

Description

ClientId

BIS/Logical System

Attachments

IDoc file which is to be sent. Note that exactly one file has to be specified. Attention: The character encoding of the attachment must be set to a valid encoding. If the character encoding is not set, or is set to binary, the operation will be rejected.

SapClient

SAP client.

TransactionId

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

Description

User

User.

Password

Password.

Ashost

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

Sysnr

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

Gwhost

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

Gwserv

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

Mshost

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.

Group

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.

R3name

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.

Lang

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: •


0 25

SAP IDoc Adapter

Parameter

Description Disabled (default) •

snc_qop

1 Enabled.

SNC security level. Range:1 ... 9 . This field is used only if SNC mode is enabled .

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_myname

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

snc_partner

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

Configuring SendIDoc_v2 Connection Type

Required Parameters in Connection

Explicit application server

•

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

Description

UNAME

This is the SAP user name for tRFC.

ROUTID

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

STATXT

This is the text of the status code.

STATYP

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


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

ROUTID

STATXT

STATYP

05

Conversion

Conversion failed.

E

06

Conversion

Conversion successful.

S

Processing rule found.

S

10 11

Forwarding

Forwarding of message failed.

E

12

Forwarding

Forwarding of message successful.

S

14

Acknowledgement

Report received.

S

15

Acknowledgement

No report received.

E

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

Description

PreparedReportPart

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

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

REFINT

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

REFGRP

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

REFMES

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

SNDPOR

(Optional) Sender port

RCVPOR

(Optional) Receiver port

ARCKEY

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

StatusDateTime

Date and time of the status change. The current system time and data is used by default.

8.2.2 SendSAPStatusReportSync This operation SendSAPStatusReport Sync 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.


27

SAP IDoc Adapter

If the result of the status sending is relevant and needed in the process, this operation SendSAPStatusRep ort Sync 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

Description

PreparedReportPart

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

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

REFINT

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

REFGRP

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

REFMES

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

ARCKEY

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

StatusDateTime

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 SendStatu s, 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

Description

Docnum

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

SapClient

SAP client name.

Status

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

Sndpr

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


28

SAP IDoc Adapter

Parameter

Description

Sndprt

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.

Sndpfc

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.

StatusDateTime

Date and time of the status change. The current system time and data is used by default.

TransactionId

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.

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

Description

ConnectionId

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.

Docnum

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

SapClient

SAP client name.

Status

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

StatusDateTime

Date and time of the status change. The current system time and data 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

TransactionId

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.


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

Description

ClientId

BIS client with fix value 000 .

Docnum

List of IDoc numbers of received IDoc messages.

Attachments

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

StatusFeedbackConnectionID

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

SapClient

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.

IdocCount

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

SystemId

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

PreparedReport

This part can be used for the SendSAPStatusReport operation. For more details, see the topic Send SAP Status Report (page 27). Xpath of this element: ReceivedIDocEvent/initiationReportHandling/prepar edReports/reportMessag

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.


30

SAP IDoc Adapter

Parameter

Description

FaultId

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

FaultDescription

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

FaultDetail

This field contains the technical description of the error. Usually this description also contains the context of the error. This field is not always available.

FaultStackTrace

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.

FaultTime

This field contains the time when the error occurred.

FaultCategory

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 operation’s configuration is likely to be wrong. The operation will not succeed, unless the configuration is changed by the user.

Retryable

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.

Fatal

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

SendingStatus

This field is either set to MAYBE_TRANSMITTED , if the IDoc file, 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.

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.


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 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

Description

sync:

The operation is executed synchronous on any running instance.

sync:instanceid=MY_INSTAN CE

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

sync:nodegroup=MY_GROUP

The operation is executed synchronous on any running node of the 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 conf igured 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'.


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: -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

Description

functionName

(Mandatory) Name of the custom trigger.

functionParameter

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

indexOfPathnameParameter

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.


35

SAP IDoc Adapter

Configuring /SendIDocMDReq/fileportTrigger/fun /SendIDocMDReq/fileportTrigger/functionParameter[ ctionParameter[n ] Parameter

Description

parameterName

(Mandatory) Name of the function parameter.

parameterValue

Value of the specified parameter.

maxParameterLength

Maximum a alllowed le length fo for tth his pa 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: •

/* for the files without extension.

•

/*. 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 on e with the changed parameters) will finish with a LI error, until the old function is no longer used. Then the new one on e is loaded, and the returned process NE_BUSY error, instances (LINE_BUSY error) error) finish their execution with success.

9.3 Connection Pool Note: 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 Avoiding the overhea overhead d of logging logging on to SAP, because once the the log-on has happened, happened, the the connection 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 Limiting the maximum maximum number number of connecti connections ons used used concurrently concurrently,, thus preventi preventing ng the use use of too many many SAP resources.

The size of the connection pool can be configured via the Control Center | IDoc Client Configuration tab tab. The default value is 20 . I.e. 20 connections can run in parallel for one connection pool. Attention: 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: Attention: If you use the DIRECT mode for 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: 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. 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. information. The IDoc Client uses the following naming conventions: Connection Type

Pool Name Form

Explicit Application Server Explicit Application Server and Gateway

ashost_user_client

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.


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 inbound communication), or received from JCo (SAP outbound 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_____. UID>.idoc idoc Example: IN_XIDregistration_20051208T123609.670Z_UID35b03e60-67e7-11da-9b9b-76a60a0067b a.idoc

SAP Inbound (sent by IDoc Connector Client): •

If ma mast ster er dat data a is is use used d for for sendi sending ng:: OUT__.idoc

•

data

set>_
of

the

address

data

set>_
If no ma mast ster er data data is used used:: OUT__.idoc

message

server>__
name>_
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 .


38

SAP IDoc Adapter

Property

Description

TransmissionDataDump

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

DumpDir

This is the directory where the files are dumped to.

IDocDumpCodePage

This is the code page used to write IDocs to a file, platform encoding 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

Description

RFC_TRACE_DIR

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.

RFC_TRACE_DUMP

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

RFC_MAX_TRACE

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

RFC_TRACE

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

If the adapter is operated on the application server (central instance), the log files are saved in the BIS6_HOME/ log/run/CENTRAL directory, which is the location of the application server's start directory. If the adapter 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

Explanation

Values

Available for

ExtendedJcoLogging

This flag activates the JCo logging. The JCo logging is written in the log file of the IDoc Connector.

True/false; default: false

Client/Server

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

Client/ Server

Note: To get JCo logs, you have to run the general logging of the adapter at least on the DEBUG level. JcoLogLevel

This property defines the log level for the JCO logging.

1 - ERROR_WARNING 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. SncLibPath

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;

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.


40

SAP IDoc Adapter

Property

Explanation

Values

ConnectionPoolSize

This property defines the default: 20 connection pool size. For more information refer to the topic Connection pool (page 36) .

Client

ConnectionPoolTimeout

This property defines the [minutes]; default: 5min connection timeout.

Client

ShowPass

This property logs the connection password in clear text.

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.

True/false; default: false

Available for

Server

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

Byte Order

Byte Order Mark (HEX)

Byte Order Mark (readable characters)

UTF-16

BE

0xFE 0xFF

ÿþ

UTF-16

LE

0xFF 0xFE

þÿ

UTF-16BE

BE

---

---

UTF-16LE

LE

---

---

UTF-8

---

0xEF 0xBB 0xBF

ï»¿

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

10.4.1.2 IDoc Connector specific information The default code page for Unicode IDocs received from SAP by tRFC is UTF-16 (with a BOM at the 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

IDoc Connector Client

IDoc Connector Server

Remarks

UTF-16 (default code page)

The IDoc message must be prepared with the appropriate BOM for sending. Otherwise, no parsing is possible.

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.

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 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).

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.

UTF-8 with BOM

No BOM at the beginning.

Unicode IDoc messages received via file port are mostly UTF-8 encoded.

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)).

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: " "). ï»¿

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.


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, che ck 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

Non-Unicode

Unicode

Non-Unicode

Receiving IDocs from R/3

Sending IDocs to R/3

8

18


19

18 44

SAP IDoc Adapter

No. Records of the Overall Java Heap Memory in [MB] transferred file

IDoc Unicode

Non-Unicode

Unicode

Non-Unicode

1.000

20

20

31

28

5.000

71

58

79

65

10.000

107

72

129

104

20.000

194

136

242

179

30.000

276

188

371

243

40.000

358

240

464

326

50.000

463

313

531

395

60.000

522

344

627

474

80.000

686

448

836

614

100.000

875

578

1011

770

120.000

1014

656

1231

913

150.000

1309

804

1491

1135

n

0.0082n + 29.801

0.0052n + 31.447

0.0096n + 51.265

0.0074n + 24.66

No. Records of the Transferred IDoc File This column gives the number of records of all IDocs that are transferred at a particular time. That is: 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

Description

ActivateMemoryCheck

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

BasicLoadValue

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) ).

SecurityBuffer

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

When the memory management is activated, a virtual memory pool is created. The pool size is 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


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.


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.


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

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 has no RFC authorization for function 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.


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.


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. .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 destination’s 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.


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, logg ed 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.


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.


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

Description

Number of executions

Configures how often an interaction is executed after the button Executed is clicked. Default is 1.

Number of parallel executions

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.

Persist details

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.

Displayed details for interaction number

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

New button

Creates a new interaction.

Execute button

Starts the execution of the interaction.

Stop button

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

Request tab

Shows the request which is forwarded to the adapter.

Response tab

Shows the response the interaction got from the adapter

Protocol tab

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

Supported interactions: Interaction

Description

Send IDoc

Transmit an arbitrary IDoc file to SAP.

Send IDoc status

Generate a status IDoc for a given IDoc number.


56

SAP IDoc Adapter

Description of the form fields: Attribute

Description

IDoc address

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

Encoding of IDoc file

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

Path to file

Path to IDoc file (Send IDoc only).

IDoc connection

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

SAP client

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

IDoc number

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

IDoc status code

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


57

SAP IDoc Adapter

13 Troubleshooting

13.1 Resolving Problems When Sending IDocs Symptom

Solution

No Status IDoc messages are sent.

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.


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 server’s master data does not match the R/3 system’s 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 server’s 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.


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 system’s 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).


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

Description

Windows (32Bit)

Operating system that hosts the IDoc Connector

d:\bis6_home

BIS 6 directory

000

BIS 6 client

IDoc Properties Property

Description

TXTRAW01

Basic type of the IDoc

SEEPORT

Partner port

SEEDEMO

Partner number

KU

Partner type

partner role

[empty]


61

SAP IDoc Adapter

Connection Properties Property

Description

gatewayhost

Gateway host

sapgw00

Gateway service

apphost

Application server host

00

System instance number

SEERFCUSER

User

100

SAP client

SAP Properties Property

Description

SID

R/3 system ID

sapconnector

Program ID

SEEBURGER DEMO

RFC destination

A.1 Installation After installing the IDoc Connector with the BIS 6 setup procedure, perform the following steps to 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.


62

SAP IDoc Adapter

Figure A-1: Master Data Configuration

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


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.


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 SAPConnectorClien t 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

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 o f 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/}

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.


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.


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.


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.


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.


72

SAP IDoc Adapter

Figure A-9: Inbound Parameters

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


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.


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:


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 S ystem 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 );


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.


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.


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.


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 , 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.


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.


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 libra ry 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 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.


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.


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.


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.


86

SAP IDoc Adapter

5 Secure Network Communication (SNC)

SNC is a software layer in the SAP system 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 system security beyond these basic measures to include the protection offered by an external security product. Advantages of using SNC: • • •

SNC provides provides applicat application-le ion-level vel end-to-end end-to-end security. security. SNC SNC secures secures all communica communications tions between between two SNCSNCprotected components. You receive receive an individual individual approach. approach. You use the security security product product of of your choice, choice, choosin choosing g the algorithm algorithms s you want to use. You can can change change the the securit security y product product at any any time with without out affec affectin ting g SAP system business applications.

5.1 Prerequisite rd

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

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 is used by R/3, it should be replaced by SAPCry /usr/sap//SYS/exe/run /usr/sap//SYS/exe/run . (If the library SAPSeculib is to avoid any conflicts. Furthermore SAPSeculib only only supports very short key lengths and the DSA ptolib to algorithm only. See SAP note 578377 for details). 2.Copy the ticket file that is included in the SAPCryptolib package package to /usr/sap//DVEBMGS/DVEBMGS/sec . 3.Make sure the environment variable SECULIB is is set for both the user ADM and and on MS Windows R/3 for SARService to the above created path /usr/sap//DVEBMGSxx/sec. SARService to /usr/sap//DVEBMGSxx/sec. 4.To 4. To use the SAPCryptolib , set/create the following profile parameters (access profile via transaction RZ10): • • • •

ssf/name = SAPCRYPTOLIB sec/ sec/li libs bsap apse secu cu = $(DIR_CT_RUN)/libsapcrypto.so ssf/ ssf/ss ssfa fapi pi_l _lib ib = $(DIR_CT_RUN)/libsapcrypto.so Instead of $(DIR_CT_RUN) the path /usr/sap//SYS/exe/run can be used. /usr/sap//SYS/exe/run can


87

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). •

Enab Enable le SN SNC: C: snc/ snc/en enab able le = 1

•

Protec Protectio tion n level level used by defaul default: t: snc/dat snc/data_p a_prote rotecti ction/ on/use use = •

Used values: 1.Secure authentication only 2.Data integrity protection 3.Data privacy protection

• •

Minimu Minimum m protec protectio tion n level: level: snc/d snc/data ata_pr _protec otectio tion/m n/min in = 1 Maximu Maximum m protect protection ion leve level: l: snc/d snc/data ata_pro _protec tectio tion/m n/max ax = 3

•

SNC SN C name name on on the the appl applic icat atio ion n serv server, er, see see TA STRUST : snc/identity/as = p:CN=

•

Path Path to to the the SNC SNC lib lib for for the the gate gatewa way: y: snc/gssapi_lib = libsapcrypto.so>

For other parameters or a more detailed description, please refer to SNC User’s Guide. Licencing: Licencing: SAPCryptolib It It may be used to secure communications between SAP components, components, please make sure that your license covers the usage of SAPCryptolib with with SEEBURGER products.

5.1.2 SEEBURGER System Install the SAPCryptolib library library on the SEEBURGER system.

Installation 1.Copy the system-dependent library (libsapcrypto.so to the libsapcrypto.so or sapcrypto.dll ) and the binary sapgenpse to /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 package to the /conf/dt/sap/sec directory. 3.Make sure the environment variable SECUDIR is set to the above created path /conf/dt/ (BIS 6 runtime user and certificate sap/sec. This variable has to be set for all users using SAPCryptolib (BIS 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 /lib/native/sapgenpse . The value of SECUDIR will 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 describe d 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.


88

SAP IDoc Adapter

5.2 Configuration For SNC secured communication a so-called Personal Security Environment (PSE) for the SAP user user who is used for the inbound RFC communication has to be created and mapped to this user’s account in R/3. This identity will also be used by the RFC registration for SAP outbound 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 -noreq [-x ] •

• • •

You You wil willl be be pro promp mpte ted d for for the the Distinguished name of the PSE owner . The following properties may be used – please take care to keep the correct order. •

CN: common nam ame e.

•

OU: organiz organizati ationa onall unit unit (may (may be used used repea repeated tedly) ly)..

• •

O: org orga anization. C: country.

The comm comma a must must be used used as as separa separator tor char charact acter. er. Exam Example ple:: CN=bisuser, OU=Connectors, OU=Connectors, O=SEEBURGER AG, C=DE . It is recommen recommended ded to define define a file file name only (not (not a full path) to make sure sure that the the generated generated file file is being being created in the directory defined in the SECUDIR system 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 Windows: sapgenpse seclogin –p [-O \] Unix : sapgenpse seclogin –p [-O ]

Return message of program: Added SSO-credentials for O=SEEBURGER AG, C=DE

PSE

\bisuser.pse \bisuser.pse

CN=bisuser,

OU=Connectors, OU=Connectors,

Note: 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 , if the SEEBURGER IDoc Connector is run as a LocalService on on Windows. SYSTEM , 3.Determine the PSE distinguished name, needed later in BIS and R/3, therefore save this name somewhere: sapgenpse get_my_name –p 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 -o . The generated certificate has to be added to the list of trusted public keys that are allowed for SNC connections. connections.


89

SAP IDoc Adapter

5.Import the R/3 certificate file to your local PSE sapgenpse maintain_pk –a -p . 6.Check the correct import with a list command sapgenpse maintain_pk –l –p .

Result, showing the imported certificate of the sample SAP system: *** Object is of the type *** 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 that has been exported from BIS user’s PSE before. Make sure to select BASE64 encoding.


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 system’s PSE.

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


91

SAP IDoc Adapter

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


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: 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.


93

SAP IDoc Adapter

Figure 5-4: Transaction SU01

8.Now return to the transaction STRUST and export the system’s certificate to a local file. 9.Double-click the Own certificate field, now the contents of this certificate is shown is the text fields below. 10.Then click the Export button marked with a black arrow and export the system’s certificate to a local file on the SEEBURGER system.


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 -p . 12.Check the correct import with a list command: sapgenpse maintain_pk –l –p .

Result, showing the imported certificate of the sample SAP system: *** Object is of the type *** 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.


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.


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.

/lib/native


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

SEEBURGER EDI

Recommend Documents