Documentos de Académico
Documentos de Profesional
Documentos de Cultura
Version: v6.3.5.Q4
Table of Contents
1 2 3
3 3 3 3 4 4 4 4
4 Overview
4.1 Features and Restrictions 4.2 System Requirements 4.3 Integration 4.4 Logical Systems
5
5 6 7 7
5 Installation
5.1 SAP Java Connector (JCo) Installation 5.1.1 Applicable JCo Versions 5.1.2 Obtaining the Correct JCo Libraries from the SAP Service Marketplace 5.1.3 Installation 5.1.4 Troubleshooting
9
9 9 9 10 10
11
6 Usage
6.1 Adapter Control over the Control Center 6.2 Operations 6.3 Monitoring
13
13 14 15
16
16 16 16 16 17 19 19 21 21 22
8 Process Configuration
8.1 Sending IDocs (SAP Inbound) 8.1.1 SendIDocMD 8.1.2 SendIDoc 8.2 Sending Status IDocs 8.2.1 SendSAPStatusReport 8.2.2 SendSAPStatusReportSync 8.2.3 SendStatus 8.2.4 SendStatusMD 8.3 Receiving IDocs (SAP Outbound) 8.3.1 ReceivedIDocEvent 8.4 Fault Messages 8.4.1 DtFault 8.5 Adapter Invocation Mode 8.6 Direct Invocation 8.7 Synchronous Adapter Invocation
23
23 23 24 26 27 27 28 29 30 30 30 30 31 31 32
32
9 Extended Features
9.1 Status IDoc Handling 9.1.1 Using the Generated Status IDoc Template 9.1.2 Queue for Status IDocs 9.1.3 Generation of Status IDocs in a Process 9.2 Customizable RFC Trigger Function for Fileport Communication 9.3 Connection Pool
34
34 34 34 34 35 36
10 Adapter Configuration
10.1 Dumping 10.2 Logging 10.2.1 JCo Logging 10.2.2 RFC Tracing 10.3 Extended Configuration Flags 10.4 Unicode and Code Page Settings 10.4.1 Unicode Code Pages 10.4.2 Unicode Settings in SAP 10.5 Memory Requirements 10.5.1 IDoc Connector Client Memory Management 10.6 Configuration within R/3 10.6.1 Creating a Minimum Authorization Profile for an RFC User 10.6.2 RFC Destination 10.6.3 Status Processing 10.7 Batching IDocs in R3 10.7.1 Scenario Description 10.7.2 Configuration in R3 10.7.3 Testing
38
38 39 39 39 39 42 42 44 44 45 46 46 51 52 52 52 53 53
11 Monitoring
11.1 Adapter Monitor 11.2 Filter 11.3 R/3 System
54
54 54 54
56 58
58 58
60 61
62 62 65 67 74
79
79 80 81
83 85
85 86
87
87 87 88 89 89 90 97
Copyright (c) 2013 SEEBURGER AG (http://www.seeburger.de). All rights reserved. If (registered or pending) trademarks are named in this document, the rights of the respective proprietors apply. Note: False configuration and/or improper use of communication components may result in significant charges from your telecommunication provider. Also consider configuration changes initiated by your telecommunication provider. SEEBURGER is not liable for related additional costs. Note: Please refer to the Knowledgebase article 13379 for an important notice concerning possible incurred charges from your telecommunication provider. Note: The information in this document is proprietary to SEEBURGER. No part of this document may be reproduced, copied, or transmitted in any form or purpose without the express prior written permission of SEEBURGER AG. Note: We expressly declare that the document "SEEBURGER Legal Information" (delivered also with your BIS installation media) is part of this documentation.
Figures
4-1 A-1 A-2 A-3 A-4 A-5 A-6 A-7 A-8 A-9 A-10 A-11 A-12 A-13 A-14 A-15 B-1 B-2 B-3 B-4 5-1 5-2 5-3 5-4 5-5 5-6 5-7 5-8
BIS Architecture 7 Master Data Configuration 63 Status Confirmation 64 Settings 65 RFC Destination 68 Special Options 69 Ports in Id processing 70 Ports in IDoc processing 70 Outbound Parameters 72 Inbound Parameters 73 Partner Profiles 74 Test Tool for Idoc processing 75 Edit control record fields 75 Information 76 Outbound Processing 76 IDoc List 77 Ports in IDoc processing 80 Send-site (SAP Inbound) 81 Test Tool for IDoc processing 82 Edit control record fields 82 Transaction STRUST 91 Transaction STRUST - Add to certificate list Transaction STRUST - Imported certificate Transaction SU01 94 Transaction STRUST 95 RFC Destination - Transaction SM59 96 RFC Destination - Activating SNC 97 SAP Connections 98
92 93
Definition Intermediate Document Application Link Enabling Transactional Remote Function Call SAP Java Connector
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.
3 Basics
This topic gives an overview of the SEEBURGER IDoc Connector and its underlying technology.
Besides the general structure, IDocs also have an application-specific structure that is determined by it's IDoc type. An application-specific structure is defined for each business case. The IDoc Connector supports all types of IDocs, as it exclusively works on the basis of the general IDoc structure. In addition to business data, IDocs also contain administrative information, including information on the sender, the receiver and the processing status of an IDoc. The IDoc Connector utilizes this administrative information to send IDocs to their destination. Usually, an IDoc is represented as a file with a fixed record size (INHOUSE format). An IDoc file may contain multiple IDocs, where each IDoc is simply appended to another. While an IDoc file may contain IDocs of different IDoc types, all IDocs contained in one IDoc file must be of the same version. The IDoc Connector rejects IDoc files that contain IDocs of different IDoc versions.
4 Overview
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.
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.
4.3 Integration
The figure below illustrates the BIS 6 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.
In particular, master data and runtime data belong exclusively to one Logical System. The adapter is able to process data and processes according to their Logical System, and therefore one instance of the adapter may be shared across all Logical Systems.
Listeners Configuration
In order to assign the Listeners to one Logical System exclusively, some unique constraints are added to the D B tables. Every Registration must be identified by its program ID and its connection reference. Every File Port Listener is identified by its local path. For security reasons, besides the unique constraints, a check for duplicate listeners is performed on adapter start-up. Each RFC/IDoc Listener is identified by: gateway host, gateway service program ID. If a Listener is marked to be a duplicate, it is not started at all, and an error message is logged in the Adapter Error Monitor. The message contains the Logical System for which it is configured, and the reason why this Listener is not started. Each file port Listener is identified by its local path. Nonetheless the more unique criterion in this case is the SAP side path. Thats why the file port listener's duplicate check is performed on the SAP side paths.
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.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
the shared libraries (depending on the operating system), the hardware architecture on which the Java Virtual Machine is running.
5.1.3 Installation
5.1.3.1 BIS Setup
The recommended way of installing the SAP JCo Java and native libraries is copying them to the correct locations during the setup of the central instance, because the setup will ease the correct installation of the SAP JCo libraries and helps to avoid manual interactions. A specific dialog will be shown, if an article is selected for installation that needs the SAP JCo to work properly. Copying the libraries during the setup has the advantage that the setup for distributed nodes will already include the libraries, and the dialog will check, if the user has copied the libraries to the correct places. The files have to be copied to the following locations (file name of native libs used exemplary here are for Microsoft Windows/Linux platform):
<BIS6_HOME>/lib/ext/sapjco3.jar
<BIS6_HOME>/lib/native/[sapjco3.dll | libsapjco3.so]
Note: If SAP JCo libs have not been installed during the initial setup of BIS, but are deployed manually according to the above documentation, the register script has to be executed. Note: The file names of the native libraries depend on the OS and architecture of the target system the BIS is installed to. Please refer to the topic Available Versions of JCo for Different Architectures (page 11) for the list of the library names on the different architectures. The BIS Setup copies the libs using the correct user that is used to run BIS 6 (not the root user). AIX: For installation/update on AIX, please refer to the topic Appendix C: FAQ (page 83). For further details on the installation of the SAP Java Connector, refer to the two files \javadoc\installation.htm l and \javadoc\useful.html, contained in the archive file of the SAP Java Connector.
5.1.4 Troubleshooting
If there are any difficulties in starting up SAP JCo based communication adapters, it is recommended to turn off the Autostart feature of both adapters. Due to the usage of native libraries in SAP JCo only the first adapter start-up attempt after a BIS (re)start will show potential problems related to these native SAP libraries, or libraries they depend on. All subsequent start-up attempts will simply show an error indicating the file sapjco3.jar not being available, which may be misleading in that case. Examples for problems related to the native libraries: Dependent libraries may be missing. Note: For a Linux/Unix system it may be required to install an older version of C++ libraries. The error message during adapter start-up tells which one is needed exactly. It is recommended to copy these libraries to the BIS6_HOME/lib/native/ directory too. Note: For Windows systems: Since SAP JCo 3 is part of the SAP 7.20 kernel family, SAP JCo 3 needs the most recent version of Microsoft Visual C++ 2005 Service Pack 1 Redistributable Package SAP IDoc Adapter - v6.3.5.Q4 10
(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 .
Microsoft Windows
OS Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008 Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008 Architecture x86 32bit Sun JVM Vendor Archive File sapjco3-NTintel-3.0.8.zip
x86_64 64bit
Sun
sapjco3-NTAMD64-3.0.8 .zip
Linux
OS SuSE SLES10, RedHat EL5 SuSE SLES10, RedHat EL5 Architecture x86 32bit x86_64 64bit Sun Sun JVM Version Archive File sapjco3-linuxintel-3.0.8.t gz sapjco3-linuxx86_64-3.0. 8.tgz
11
Solaris
OS Solaris 10 Solaris 10 Architecture SPARC 64bit x86_64 64bit Sun Sun JVM Version Archive File sapjco3-sun_64-3.0.8.tgz sapjco3-sunx86_64-3.0.8 .tgz
AIX
OS AIX 5.3, AIX 6.1 Architecture Power PC 64bit IBM JVM Version Archive File sapjco3-rs6000_64-3.0.8 .tgz
Native library name: libsapjco3.so Please refer also to the topic: First Q/A of chapter FAQ (page 83) for installation on AIX.
HP-UX
OS HP-UX B11.23, B11.31 Architecture Itanium 64bit HP JVM Version Archive File sapjco3-hpia64-3.0.8.tgz
Native library names: libsapjco3.so Combinations that are not mentioned as supported above may run properly, but it is strongly recommended to follow these recommendations.
12
6 Usage
13
6.2 Operations
IDoc Connector Client
Parameter SendIDoc_v2 SendIDocMD_v2 SendStatus_v2 SendStatusMD_v2 SendSAPStatusReport Definition This operation sends an IDoc to a R/3 system (SAP Inbound). This operation sends an IDoc to a R/3 system (SAP Inbound) and sets all necessary master data in the operation. This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound) and sets all necessary master data in the operation. This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound) (uses the SendSAPStatusReport operation instead). This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound). This operation relies on a template that is created by the IDoc Connector Server when receiving an IDoc. The response of the sending of the status confirmation is NOT returned to the process. This operation is equivalent to SendSAPStatusReport with the difference that it contains the request and the response messages. The response of the sending of the status confirmation is returned to the process. Attention: This operation is an older version and we do not recommend it for use. SendIDoc_v2 has an extended response and should be used instead. This operation sends an IDoc to an R/3 system (SAP Inbound). SendIDocMD Attention: This operation is an older version and we do not recommend it for use. SendIDoc_v2 has an extended response and should be used instead. This operation sends an IDoc to an R/3 system (SAP Inbound) and sets all necessary master data in the operation. SendStatus Attention: This operation is an older version and we do not recommend it for use. SendIDoc_v2 has an extended response and should be used instead. This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound) and sets all necessary master data in the operation. SendStatusMD Attention: This operation is an older version and we do not recommend it for use. SendIDoc_v2 has an extended response and should be used instead. This operation sends a status confirmation IDoc to an R/3 system (SAP Inbound) (uses the SendSAPStatusReport operation instead).
SendSAPStatusReportSync
SendIDoc
14
6.3 Monitoring
The Adapter is connected to different monitors. The specific function of each monitoring tool is described in the Master Adapter Configuration Guide. Monitor Adapter Monitor Recovery Monitor Transaction Monitor Description Provides runtime information. If individual orders require recovery, they are listed in the Recovery Monitor. Provides information on the state of transactions of the adapter. The exact definition of a transaction depends on the respective adapter, but usually a transaction describes the reception or the sending of a message.
15
Gateway service
16
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.*
This is the SAP log-on password. This parameter specifies the way a connection is established for SAP INBOUND files sent to an R/3 system: Explicit Application Server The default gateway is used; the fields gateway host and gateway service are only used for receiving RFM. Explicit Application Server and gateway Both will be determined individually, unlike the option above (where the default gateway is automatically used). Load balancing The message server port of the SAP system has to be added manually to the services file, defining the registered TCP services of the operating system. On windows machines this file is located in <windows_home>/system3 2/drivers/etc. This entry in this file may look similar to this:
sapms<SID> 36<systemNo>/tcp
1. Replace <SID> with the System ID of the R/3 system. 2. Replace <systemNo> with the System Number of the R/3 system. Application server The host name or the IP address of the SAP application server. The application server may also be specified as a complete SAP router string. This field is not visible in Load Balancing mode. The SAP system number (the instance number of the R/3 system). This number can be located e.g. in the SAP menu under Tools | Administr ation | Monitor | System Monitoring |Servers. The system number can be determined by referring to the last two characters at the end of the indicated Gateway service. The host name or the IP address of the SAP message server. This field is only visible in Load Balancing mode. The name of the group of SAP Application Servers. The group is usually called PUBLIC, but this may not always apply. Note that the field System ID of the addresses determines the R/3 name for load balanced connections. This field is only visible in Load Balancing mode.
System number
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
Parameter/Option Language
Description The log-on language. This setting only affects the language of error messages deriving from an R/3 system. Note that it is recommended to use the default value (English). The component recognizes a few confusing error messages of the R/3 system, and replaces them with more meaningful ones. This feature does not work with non-English error messages. If the RFC trace is enabled, low level log files containing information on the communication (RFC) with a R/3 system, are stored in the BISAS_HOME \log\run\CENTRAL directory. These log files can be used to help analyze communication problems with an R/3 system. Attention: Enable this option only for fixing communication problems.
Enable SNC
If enabled, the Secure Network Communications (SNC) layer is used for the communication with R/3 systems. For information on the SNC settings, please refer to the SAP guide Secure Network Communications - SNC User's Guide or Secure Network Communication (SNC) . The following security levels can be configured for SNC: Authentication Integrity protection Encryption Default setting of destination Max. available
Security level
It is recommended to select the Default setting defined in the SAP Instance profile. Own SNC name Partner's SNC name The name returned by the sapgenpse get_my_name command has to be entered here. The name of the R/3 application server. The value is returned by the command sapgenpse maintain_pk l.
* 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
Settings
Parameter Description
Connection to the SAP system Determines the connection for sending IDoc-type messages (both payload and status messages) to the specified address. System ID R/3 system name, aka. SID. It can be found in the SAP GUI's main menu under System | Status | Database data | Name. Note that this setting is only required for sending IDoc messages in Load B alancing mode. R/3 system client. This setting is used when the IDoc Connector logs on in order to send IDoc messages. The SAP client also determines the address for receiving status confirmation messages if the following two conditions are satisfied: The SAP client matches the client for the received IDocs. The connection matches the connection which originally has received the IDoc messages. Note: The combination of SAP client and connection must be unique. Otherwise, the data set is rejected by the BIS 6 Front-end. Default encoding This setting defines the code page which should be used for IDoc attachments with no encoding set at process level. The IDoc Connector Client is not able to process binary attachments. This setting is only used for sending IDocs to SAP. It is ignored for receiving IDocs. For solving problems with encoding and Unicode code pages in general, please refer to the topic Unicode and Code Page Settings. (page 42)
SAP client
19
Parameter/Option Name
Description This is a short, but unique name that describes the registration. This name is used in log files to associate log entries with the corresponding registration. This is a demarcation for the created registration - if it will be used for IDoc Controller (IDOC), or for RFC Controller (RFC), but not for both simultaneously. For using this registration with the IDoc Controller, the only allowed value for this property is IDOC. The registration will be ignored, if the wrong type RFC is chosen. Default value: IDOC
Server type
If this option is disabled, this record is ignored at the IDoc Connector server's start-up. This is the default value for the Listener group (DefaultGroup). A Listener that is part of the DefaultGroup will be started up on all nodes. Use the instance ID that has been configured during the BIS 6 installation for grouping the Listeners.
20
Program ID
Number of connections
Listener group
21
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.
22
8 Process Configuration
8.1.1 SendIDocMD
Note: SendIDocMD_v2 operation is corresponding to SendIDocMD, which is an older version and we do not recommend it for use. SendIDocMD_v2 has an extended response and should be used instead. The SendIDocMD_v2 operation sends an IDoc file to an R/3 system. It corresponds to the SendIDoc _v2 operation, with the exception that the configuration settings of SendIDocMD _v2 are included in the master data (MD), i. e. in the BIS 6 database. An IDoc file may contain a random number of IDocs of any message type. All IDocs of an IDoc file must be of the same IDoc version (either IDoc version 2, or IDoc version 3). The fields of the IDocs must be set correctly. The following fields are excluded from this: Control Record Parameter SAP client (MANDT) IDoc number (DOCNUM) Direction (DIRECT) Description Can be left empty. If the field is not empty, it is compared with the actual S AP client. In case of a mismatch, a warning is sent to the log file. Completely ignored by the IDoc Connector Client, since the IDoc number is generated by the R/3 system when it receives the IDoc. If the setting for the direction is set to 1 (outbound), the IDoc Connector swaps the fields that identify the sender and receiver of the IDoc. This feature simplifies the steps that are necessary to receive and send an IDoc back to the R/3 system. This field can be left empty. If the field is not empty, its value is compared with the actual system ID (Note that the system ID is requested from the R/3 system, it is not determined from the master data or properties of the operation). In case of a mismatch, a warning is sent to the log file.
If the setting for the direction is not set to 1 (outbound), direction 2 (inbound) is assumed.
23
Note: Swapping of sender and receiver: If the direction flag of the IDoc to be sent is set to 1 (outbound), sender and receiver are swapped. The flag remains unchanged in the physically transmitted IDoc, since R/3 automatically corrects this during reception process. (The direction flag is located at offset: 35, length: 1 in a version 3 EDI_DC40 control set). Data Record Parameter SAP client (MANDT) IDoc number (DOCNUM) Segment number (SEGNUM) Settings for the operation: Operation parameter ClientId DestinationAddressId Attachments Description BIS logical system client ID of the address data set that is the destination for the IDocs. IDoc file that is to be sent. Note that exactly one IDoc file must be specified. Attention: The character encoding of the attachment must be set to a valid encoding. If the character encoding is not set, or is set to binary, the operation will be rejected. TransactionId Attention: This field is used internally. Never change this property! This field stores the transaction ID of incomplete tRFC calls. The value of this field is deleted, when a tRFC call is completed. Description Ignored by the IDoc Connector Client. Ignored by the IDoc Connector Client, since the IDoc number is generated by the R/3 system when it receives IDocs. Ignored by the IDoc Connector Client. The segment numbers are generated by the IDoc Connector.
8.1.2 SendIDoc
Note: SendIDoc_v2 operation is corresponding to SendIDoc, which is an older version, and we do not recommend for use. SendIDoc_v2 operation has an extended response and should be used instead. The SendIDoc _v2 operation sends an IDoc file to an R/3 system. All configuration settings for the operation are stored as operation properties. Therefore the master data is not used.
24
Description BIS/Logical System IDoc file which is to be sent. Note that exactly one file has to be specified. Attention: The character encoding of the attachment must be set to a valid encoding. If the character encoding is not set, or is set to binary, the operation will be rejected.
SapClient TransactionId
SAP client. Attention: This field is internally used. Never change this property! Transaction ID of incomplete tRFC calls. The value of this field will be deleted after termination of the tRFC call.
queue
Connection
Parameter User Password Ashost Sysnr Gwhost Gwserv Mshost Group R3name Lang Description User. Password. SAP application server, this field must be left empty in Load Balancing mode. SAP system number, this field must be left empty in Load Balancing mode. SAP gateway host, this field is optional, but must be left empty in Load Bal ancing mode. SAP gateway service, this field is optional, but must be left empty in Load Balancing mode. SAP message server, this field must be set for using the Load Balancing mode. It must be left empty, if Load Balancing is not applied. SAP message server, this field must be set for using the Load Balancing mode. It must be left empty, if Load Balancing is not applied. System ID of the R/3 system, this field must be set for using Load Balancin g mode. It must be left empty, if Load Balancing is not applied. This is the log-on language, this field is optional. Note: We recommend using the default value (English). The IDoc Connector recognizes a few confusing error messages of the R/3 system, and replaces them with better ones. This feature does not work for non-English error messages. RfcTrace This field enables low-level RFC logging. The RFC trace is disabled by default. Note: If you change this value in the process, you have to execute Reload Configuration of IDoc Client after deploying the changes. snc_mode Secure network connection (SNC) mode. Applicable values: SAP IDoc Adapter - v6.3.5.Q4 0 25
Parameter
Description Disabled (default) 1 Enabled. SNC security level. Range:1 ... 9. This field is used only if SNC mode is enabled.
snc_qop
snc_lib
Attention: Do not use this field because it is deprecated. Changing the SNC library path must be done via the User-Config file. SNC name. It overrides the default SNC partner. This field is only used if the SNC mode is enabled. SNC partner, e.g. p:CN=R3, O=XYZ-INC, C=EN. This field is only used if the SNC mode is enabled.
snc_myname snc_partner
Configuring SendIDoc_v2
Connection Type Explicit application server Required Parameters in Connection user password lang ashost sysnr user password lang ashost sysnr gwhost gwserv user password lang mshost r3name group
Load balancing
These properties are filled by the IDoc Connector. The values for ROUTID, STATXT, and STATYP depend on the Status value from the operations described below. Status 05 06 10 11 12 14 15 Forwarding Forwarding Acknowledgement Acknowledgement ROUTID Conversion Conversion STATXT Conversion failed. Conversion successful. Processing rule found. Forwarding of message failed. Forwarding of message successful. Report received. No report received. STATYP E S S E S S E
8.2.1 SendSAPStatusReport
This is the preferred and recommended operation for sending Status IDoc messages back to R/3. Requirements: Sending Status IDoc files by using the SendSAPStatusReport operation requires a special IDoc Controller report queue. Parameter PreparedReportPart Description This part must contain a so-called prepared. This part can be found as attachment of the initial ReceivedIDocEvent that is generated by the IDoc Controller (xpath to this element: //ReceivedIDoc Event/initiationReportHandling/preparedReports/reportMessage). Docnumbers List of IDoc numbers, for which a status is to be sent. At least one IDoc number must be specified. Usually this list is generated by the Splitter. A reference to all received IDoc numbers can also be found in the ReceivedIDocEvent. Status REFINT REFGRP REFMES SNDPOR RCVPOR ARCKEY StatusDateTime Status that is sent for the list of IDocs. Values range: 01 ...49. (Optional) EDI Interchange name (reference to a file). (Optional) EDI-Message Group (reference to group). (Optional) EDI-Message (reference to message). (Optional) Sender port (Optional) Receiver port (Optional) Key of the external message archive (document ID in external system). Date and time of the status change. The current system time and data is used by default.
8.2.2 SendSAPStatusReportSync
This operation SendSAPStatusReportSync provides in contrary to SendSAPStatusReport the feature that the process will wait for the response of the sending of the status IDoc sending. The status IDoc sending by Sen dSAPStatusReport does only prepare the sending and does not care and wait for the result of it.
27
If the result of the status sending is relevant and needed in the process, this operation SendSAPStatusRep ortSync should be used. The parameters of the request message are identical to the SendSAPStatusReport, the response message is a plain DtResponse message with no IDoc specific information. This is the preferred and recommended operation for sending Status IDoc messages back to R/3. Requirements: Sending Status IDoc files by using the SendSAPStatusReportSync operation requires a special IDoc Controller report queue. Parameter PreparedReportPart Description This part must contain a so-called prepared. This part can be found as attachment of the initial ReceivedIDocEvent that is generated by the IDoc Controller (xpath to this element: //ReceivedIDoc Event/initiationReportHandling/preparedReports/reportMessage). Docnumbers List of IDoc numbers, for which a status is to be sent. At least one IDoc number must be specified. Usually this list is generated by the Splitter. A reference to all received IDoc numbers can also be found in the ReceivedIDocEvent. Status REFINT REFGRP REFMES ARCKEY StatusDateTime Status that is sent for the list of IDocs. Values range: 01 ...49. (Optional) EDI Interchange name (reference to a file). (Optional) EDI-Message Group (reference to group). (Optional) EDI-Message (reference to message). (Optional) Key of the external message archive (document ID in external system). Date and time of the status change. The current system time and data is used by default. The value provided for the StatusDateTime has to be in valid xsd:dateTime format as defined in the XML Schema specification and ISO 8601 conventions
8.2.3 SendStatus
Note: SendStatus_v2 operation corresponds to SendStatus, which is an older version and we do not recommend it for use. SendStatus_v2 has an extended response and should be used instead. The SendStatus _v2 operation sends a status confirmation for a list of (received) IDocs to an R/3 system. All configuration settings for the operation are contained in the operation properties; therefore the master data is not used. Parameter Docnum SapClient Status Sndpr Description List of IDoc numbers, specifying the messages for which a status is to be sent. At least one IDoc number must be specified. SAP client name. Sent status for the list of IDocs. Applicable values range: 01 ...49. Profile of the R/3 partner who processes status IDocs. The value of the field Partner Number of the IDoc messages sender (SNDPRN) are created in order to send status codes to R/3.
28
Parameter Sndprt
Description Profile of the R/3 partner who processes status IDocs.The value of the field Partner Type of the IDoc messages sender (SNDPRT) are created in order to send status codes to R/3. Profile of the R/3 partner who processes status IDocs.The value of the field Partner Role of the IDoc messages sender (SNDPFC) are created in order to send status codes to R/3. The Partner Role is left empty by default. Date and time of the status change. The current system time and data is used by default. Attention: This field is used internally. Never change this property! The field stores the transaction ID of incomplete tRFC calls. The value of this field is deleted, when a tRFC call is completed.
Sndpfc
StatusDateTime TransactionId
Connection
Connection setting properties; corresponding to the properties for the Send IDoc operation.
8.2.4 SendStatusMD
Note: SendStatusMD_v2 operation corresponds to SendStatusMD, which is an older version and we do not recommend it for use. SendStatusMD_v2 has an extended response and should be used instead. The SendStatusMD _v2 operation sends a status confirmation to an R/3 system for a list of (received) IDocs. It widely corresponds to the SendStatus _v2 operation, but the configuration settings are specified in the master data. Parameter ConnectionId Description ID of the connection that received the IDocs, for which the status is to be sent. The combination of the connectionId and SAP client determines the address which is used to send the status. List of IDoc numbers, specifying the messages for which a status is to be sent. At least one IDoc number must be specified. SAP client name. Sent status for the list of IDocs. Applicable values range: 01 ...49. Date and time of the status change. The current system time and data is used by default. The value provided for the StatusDateTime has to be in valid xsd:dateTime as defined in the XML Schema specification and ISO 8601 conventions Attention: This field is internally used. Never change this property! The field stores the transaction ID of incomplete tRFC calls. The content will be deleted after completion of the tRFC call.
TransactionId
29
SapClient
30
Description This field is not supported. Therefore it is always set to none. This is a short non-technical description of the error. This field contains the technical description of the error. Usually this description also contains the context of the error. This field is not always available. This field contains the program context where the error occurred. This information helps the SEEBURGER technical staff to quickly provide solutions, if there are unexpected problems with the IDoc Connector. This field contains the time when the error occurred. This field is either set to COMPONENT_ERROR, if it is unlikely that the error derives from a configuration error. Or TASK_ERROR/CONFIGURA TION_ERROR, if the operations configuration is likely to be wrong. The operation will not succeed, unless the configuration is changed by the user. This field is set to true, if the operation may succeed when it is retried. The field is set to false, if the error is likely to be of a permanent nature. This field is not supported. Therefore it is always set to false. This field is either set to MAYBE_TRANSMITTED, if the IDoc file, or status IDocs may have been received by a R/3 system. In this case, the operation must be retried to guarantee that the IDocs are received exactly once. Or NOT_TRANSMITTED, if the IDoc file, or status IDocs have definitely not been received by a R/3 system.
FaultStackTrace
FaultTime FaultCategory
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
When defining a process, you have to specify a particular queue/destination name to be used. Use async: for the queue/destination part in the request (note the colon). After the colon, enter the corresponding JMS queue's JNDI name (e.g. async:queue/ftpTestQueue). If only async: is entered, the default queue to <PortType> is used (e.g. toDtFTPComponent). This is the recommended usage for simple architectures, since this method does not require adapter configuration and queue definition. Limitation: Orders relying on hardware resources like ISDN, X.31, or X.25 cannot be used with the direct invocation since no resource management is available. Use the WorklistHandler integration instead. Note: Up to version 6.3.3 direct: was used instead of async: to specify the queue/destination. You can still use the direct: parameter. Note: An error of the type Line-Busy does not increase the retry count of the order.
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.
In contrast to the Direct Adapter Invocation the queue configuration and the order dispatching can be configured to a more complex scenario. It supports for example polling of orders, dynamic retry handling, and resource handling. To configure the process to use a WLH queue, just enter the name of the queue in the queue part of the outbound operation. For details about this invocation mode please refer to the topic 'Adapter Invocation' in the 'Master Adapter Configuration Guide'.
33
9 Extended Features
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.
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.
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.
indexOfPathnameParameter
35
Configuring /SendIDocMDReq/fileportTrigger/functionParameter[n]
Parameter parameterName parameterValue maxParameterLength Description (Mandatory) Name of the function parameter. Value of the specified parameter. Maximum allowed length for this parameter. If no value is specified, the default value (255 characters) will be used.
The value of the function parameter carrying the remote SAP side path, can be entered in two ways: <REMOTE_DIRECTORY_PATH>/* for the files without extension. <REMOTE_DIRECTORY_P ATH>/*.<ext> for the files with extension.
To avoid performance problems, the IDoc Client has a special function repository for custom triggers. After the first call, the function is loaded in the repository and then re-used. If the dynamic list of parameters for a loaded function is changed during runtime, the new process (the one with the changed parameters) will finish with a LI NE_BUSY error, until the old function is no longer used. Then the new one is loaded, and the returned process instances (LINE_BUSY error) finish their execution with success.
The size of the connection pool can be configured via the Control Center | IDoc Client Configuration tab. The default value is 20. I.e. 20 connections can run in parallel for one connection pool. Attention: Be careful not to create a performance bottleneck by making the maximum number of connections too small, and thus creating waiting situations for your processes. Increase the pool size with caution, since it might lead to a heavy load peak in R/3. Attention: If you use the DIRECT mode for sending an IDoc, keep in mind that the default maximum load of parallel jobs is 20. It is recommended to decrease this setting, instead of increasing the JCo pool size in this use case. Note: If a LINE_BUSY error is returned with the message stating that the pool is exhausted, you can either decrease the parallel number of jobs, or increase the increase the pool size. Keep in mind the warning concerning the DIRECT mode above. SAP IDoc Adapter - v6.3.5.Q4 36
A JCo connection pool is identified by its name and is global within the Java Virtual Machine (JVM). All connections in a pool use the same system/userid/client information. The IDoc Client uses the following naming conventions: Connection Type Pool Name Form
Explicit Application Server ashost_user_client Explicit Application Server and Gateway Load Balancing r3name_user_client
The connection pool also provides some features for dynamic monitoring. The JCo transfer time and the JCo sent bytes per connection can be viewed in the process response.
37
10 Adapter Configuration
10.1 Dumping
The dumping feature is for debugging purposes only. It dumps the complete IDocs, both sent and received ones, to a file. The IDocs are dumped as close as possible to the JCo implementation. That means, the IDocs are dumped as they are passed to JCo (SAP inbound communication), or received from JCo (SAP outbound communication). No further processing/parsing is done between dumping the file, and passing it to JCo. The files are named as follows:
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
Description This property is used to switch the dumping on/off. This is the directory where the files are dumped to. This is the code page used to write IDocs to a file, platform encoding is used as a default.
Attention: The dumping decreases the adapter throughput. Deactivate the dumping as soon as possible.
10.2 Logging
Further information concerning the common logging configuration please refer to the topic Logging/Tracing/ Dumping of the Master Adapter Configuration Guide.
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.
Property ExtendedJcoLogging
Explanation This flag activates the JCo logging. The JCo logging is written in the log file of the IDoc Connector. Note: To get JCo logs, you have to run the general logging of the adapter at least on the DEBUG level.
JcoLogLevel
This property defines the log level for the JCO logging. Note: JCo Log level is a static property for the running VM. The last value is used for all components using JCo traces. Note: Starting with level 6 the memory usage increases rapidly and there are also big performance hits caused by the dumping of the IDoc content. It is not recommended to run levels >= 6 in a productive environment for a longer time.
0 (no log) to 8 (max log); default: 5 1 - ERROR_WARNING 2 - PATH_API 3 - FULL_PATH 4 - INFO_PATH_API - JCo connection pool activity can be seen at this level; destination and server data events; 6 - INFO_PATH - the content of the transferred IDoc tables is dumped; 7 - SHORT_DEBUG 8 - FULL_DEBUG dispatchers' logs;
Client/ Server
SncLibPath
This is the full path to the [string]; default: Client/ Server SNC library. %bisas.home%/lib/native Note: Changing this value needs an adapter restart for the native libraries to reinitialize. If the path is not existing or accessible, this is a configuration error and will be reported as this.
40
Property ConnectionPoolSize
Explanation
Values
This property defines the default: 20 connection pool size. For more information refer to the topic Connection pool (page 36) . This property defines the connection timeout. This property logs the connection password in clear text. [minutes]; default: 5min True/false; default: false
ConnectionPoolTimeout ShowPass
Client Client
UseSAPNativeUTF16Co depage
This property should be True/false, default: false used only, if there are problems with the default UTF-16 code page of received IDocs files. This code page uses a byte order mark, which may cause problems with some mappings. Setting this property to true will force the IDoc Controller to use code page without a byte order mark. The code page will be equal to the application server code page number of the respective SAP system. Code page number 4102 at SAP system will create UTF-16BE IDocs in BIS; 4103 will create UTF-16LE respectively. See chapter Unicode and Code Page Settings (page 42) for details. If this feature is enabled and therefore the SAP Application Server Code Page is used for received IDocs, changing the code page at SAP system (e.g. due to an upgrade or reinstallation) will also change the code page of the received IDocs in BIS 6.
Server
41
For such a case the IDoc Controller is able to remove the BOM. This is achieved by switching from the default code page UTF-16 (with a BOM) to a non-BOM code page UTF-16BE/UTF-16LE. Which of the two non-BOM code pages is effectively used, depends on the code page that is installed at the connected SAP system. The SAP code page number 4102 is mapped to UTF-16BE, 4103 is mapped to UTF-16LE in BIS 6). See chapter Extended Configuration (page 39) on how to enable this feature. The specifics of handling unicode-encoded files for both IDoc Connector Client and IDoc Connector Controller are described in this table: Code page UTF-16 (default code page) IDoc Connector Client The IDoc message must be prepared with the appropriate BOM for sending. Otherwise, no parsing is possible. IDoc Connector Server UTF-16 is the default code page IDoc Connector uses for received Unicode IDocs. The post-processing steps (e.g. mapping) must be BOM-aware. These code pages are used for received IDocs when the extended setting UseSAPNativeUnicodeCo depage is enabled (page 39). The endianness depends on the installed code page at SAP (TA SNL1). Remarks Do not use hard-coded source encoding settings in mappings.
UTF-16LE/ UTF-16BE
The endianness is implicitly determined by the very name of the code page; therefore files in this encoding must not have a BOM at the beginning.
These code pages always need to provide the used endianness externally, as there is no BOM that may be used for implicit determination.
8-bit characters must be This code page is encoded with two or more not used for RFC bytes. transmission. No BOM at the beginning. Unicode IDoc messages received via file port are mostly UTF-8 encoded. SAP is able to create files with a BOM. The IDoc Connector server cannot skip the BOM, therefore it is also recommended to remove the BOM before sending those files to BIS 6. The UTF-8 BOM comprise the following characters: 0xEF 0xBB 0xBF (looks like this in ASCII: " ").
The BOM cannot be skipped by the IDoc Connector client. Therefore, the parsing (and sending) corresponding IDoc messages fails. (Error message: IDoc contains a data record where a control record is required. Near line 1 (IDoc number x)). Remove the BOM before sending UTF-8 files.
43
No. Records of the Overall Java Heap Memory in [MB] transferred file 1.000 5.000 10.000 20.000 30.000 40.000 50.000 60.000 80.000 100.000 120.000 150.000 n IDoc Unicode 20 71 107 194 276 358 463 522 686 875 1014 1309 0.0082n + 29.801 Non-Unicode 20 58 72 136 188 240 313 344 448 578 656 804 0.0052n + 31.447 Unicode 31 79 129 242 371 464 531 627 836 1011 1231 1491 0.0096n + 51.265 Non-Unicode 28 65 104 179 243 326 395 474 614 770 913 1135 0.0074n + 24.66
SecurityBuffer
When the memory management is activated, a virtual memory pool is created. The pool size is determined as follows: Virtual memory pool = the Xmx parameter basic load value. The determination if an IDoc can be sent with activated memory check is based on two constraints: SAP IDoc Adapter - v6.3.5.Q4 45
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.
46
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
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
7. Expand the tree. 8. Edit the S_RFC object: Set Activity (ACTVT) to Execute (16). Set Type of the RFC object to be protected (RFC_TYPE) to Function Group (FUGR). Set Name of the RFC to be protected (RFC_NAME) to: SYST SYSU ARFC ERFC EDIN <maybe additional name of the RFC function module configured for processing in the partner profile (TA WE20)>
Note: If the function module name behind the process code in WE20 partner profile uses further modules than EDIN, simply send a test IDoc using a user assigned to this newly created role and check for the error message in SEEBURGER BIS (or in SAP system trace TA ST01). The error message could look like this:
RFC_ERROR_SYSTEM_FAILURE: User <RFCUserName> has no RFC authorization for function group <your group> .
9. Edit the BC_ALE_RECV object. Here the allowed message types to be received can be defined. If you do not want to define a restriction, simply choose *, otherwise e.g. add SYSTAT for receiving status IDocs. 10.Save the profile.
49
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
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.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
11 Monitoring
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
54
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.
55
12 Adapter Interactions
Common Information
Interactions can be used to test the adapter, the configured master data, and the partner communication, without creating a special business process. For example you can send a test file to the partner, or poll its mailbox to see if the connection works. The interactions do not support any queuing (WLH) or resources. The state of the interaction can be monitored as a result in the interactions form and not in the BIS Inspector. Description of the common form attributes: Attribute Number of executions Number of parallel executions Description Configures how often an interaction is executed after the button Executed is clicked. Default is 1. Configures how many interactions are executed parallel. This can be used for testing parallel transmission of files for example. The default value is 1. The maximum parallel execution is 30. If this flag is enabled, all information about the request and the response will be available for monitoring. Also the request and response attachments will be available to show. If the flag is disabled, no information is available after the interaction is finished. Only the protocol is shown, which states which interaction was finished successfully and which not. Shows the number of the interaction for which the Request/Response tab is shown. Creates a new interaction. Starts the execution of the interaction. Click this button to cancel all scheduled interactions. The running interaction will run until it is finished, but no new one will be started. Shows the request which is forwarded to the adapter. Shows the response the interaction got from the adapter Shows which interaction was finished successfully, and which was finished with an error. Using the context menu the Request/Response details can be shown.
Persist details
Displayed details for interaction number New button Execute button Stop button Request tab Response tab Protocol tab
Supported interactions: Interaction Send IDoc Send IDoc status SAP IDoc Adapter - v6.3.5.Q4 Description Transmit an arbitrary IDoc file to SAP. Generate a status IDoc for a given IDoc number. 56
Description of the form fields: Attribute IDoc address Encoding of IDoc file Path to file IDoc connection SAP client IDoc number IDoc status code Description Destination address to which the IDoc is sent (Send IDoc only). Encoding of the IDoc which is transferred (Send IDoc only). Path to IDoc file (Send IDoc only). Connection to which the status IDoc is sent to (Send IDoc status only). The SAP client (MANDT) of the receiving SAP system (Send IDoc status only). The IDoc number for which the status IDoc is generated (Send IDoc status only). Two digit status code which is to be generated for the given IDoc number (Send IDoc status only).
57
13 Troubleshooting
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).
Step 2: Find out whether the IDoc Connector server has received IDoc files.
58
Symptom
Solution 1. In the corresponding monitor, check for waiting messages.(Perhaps no process has been deployed). 2. In the Recovery Monitor, check the open incoming transactions. They must have also an entry in R/3 transaction SM58. Common sources of error: Processes are not triggered, since the settings for the initiator rules and initiator ports are missing or incorrect. The IDoc Connector servers master data does not match the R/3 systems configuration. Network problems.
Step 3: Fix the problem. 1. If the transaction SM58 (Transactional RFC) indicates that there are problems with the RFC server, consult the IDoc Connector servers log files to see what the IDoc Connector server is doing and whether any errors occurred. 2. The IDoc Connector server accepts IDoc messages from the R/3 system even if BIS 6 cannot send the received messages to the central instance. Therefore, the transaction SM58 can only be used to recognize problems which have directly been caused by the IDoc Connector server, the R/3 system or the network. 3. If network problems between the IDoc Connector server and the R/3 system are suspected, go to the transaction SM59, select the appropriate RFC destination from the TCP/IP connections, finally click Test connection (F8) to test the RFC connectivity.
59
14 Known Restrictions
The amount of data that can be sent or received in one transaction is limited by the amount of available memory. Therefore, transferring very large IDocs (e.g., CAD IDocs, or files containing many IDocs) will affect the systems performance substantially, if the operation is executable at all. This particularly applies for 32bit operating systems, e.g. 32bit operating systems with a virtual address space limit of 2-GB, the IDoc files should not consist of more than 150.000 records. Hence, where transactions involving very large files may not work, both sending and receiving are subject to this. XML IDocs are not supported. They must be converted into standard IDocs first. IDocs must not contain End-of-File (EOF) characters. (some MS-DOS applications use EOF characters). The characters in Unicode IDocs must consist of characters as used in the Basic Multilingual Plane (BMP).
60
The quick start example assists in getting the IDoc Connector quickly up and running. After all steps of this quick start example have been completed, the R/3 system and BIS 6 have been configured to perform the following actions: Create IDocs in the R/3 system. Receive created IDoc messages from the R/3 system. Send received IDoc messages back to the R/3 system. Send status confirmations for received IDoc messages to the R/3 system.
Note: The screenshots presented for this example refer to the SAP Release 701. Other releases may slightly differ. The steps that are described in the quick start example refer to an environment that is described in the tables below.
BIS Properties
Property Windows (32Bit) d:\bis6_home 000 Description Operating system that hosts the IDoc Connector BIS 6 directory BIS 6 client
IDoc Properties
Property TXTRAW01 SEEPORT SEEDEMO KU partner role Description Basic type of the IDoc Partner port Partner number Partner type [empty]
61
Connection Properties
Property gatewayhost sapgw00 apphost 00 SEERFCUSER 100 Description Gateway host Gateway service Application server host System instance number User SAP client
SAP Properties
Property SID sapconnector SEEBURGER DEMO Description R/3 system ID Program ID RFC destination
A.1 Installation
After installing the IDoc Connector with the BIS 6 setup procedure, perform the following steps to complete installation: 1. Download the file sapjco3-NTintel-3.0.8.zip (or the proper one for your system) from http://service.sap.co m/connectors. 2. Extract the file sapjco3.jar to d:\bis6_home\lib\ext. 3. Extract the file sapjco3.dll to d:\bis6_home\lib\native. Please refer to the topic SAP Java Connector (JCo) Installation (page 9) for important notes about common installation problems.
62
7. Enter the settings for the status confirmations. 8. Save the data set.
63
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
To create and configure this process carry out the following steps: 1. Make sure the sapclient.wsdl and the sapserver.wsdl are both imported in the Process Designer. 2. Add the ReceivedIDocEvent operation (from SAPConnectorServer tasks) to the process. 3. Insert the sendSAPStatusReport operation (from SAPConnectorClient tasks) after the ReceivedIDocEven t operation. 4. Insert the SendIDocMD_v2 operation (from SAPConnectorClient tasks) after the sendSAPStatusReport operation. SAP IDoc Adapter - v6.3.5.Q4 65
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
The queue will be generated automatically when the process is activated, but do not forget to connect it to the IDoc Connector client. 3. Assign the properties of the second sendSAPStatusReport component of the process that are necessary to send Status IDocs with status 38 back to the R/3 system: Assign the prepared report template of the ReceivedIDocEvent (path: /ReceivedIDocEvent/initiatio nReportHandling/preparedReports/reportMessage) to the preparedReportPart of the sendSAPStat usReport (path: /sendSAPStatusReport/preparedReportPart/AttachmentRef). Assign all the docnumbers of the received IDocs (path: /ReceivedIDocEvent/docnum to the sendS APStatusReport (path: /sendSAPStatusReport/docnumberPart/docnumbers). Assign the status 38 to /sendSAPStatusReport/statusPart. Save and activate the process.
An appropriate Initiator port is created and installed during the activation of the process by default. But you will have to create an Initiator rule to start the processing when an IDoc is received by the IDoc Connector server: 1. Create a rule for port type SAPConnectorServer/ReceivedIDocEventPT. 2. Set an expression like 1=1. 3. Rooting type: process. 4. TargetPort: {http://seeburger.com/}<nameOfYourProcess>
67
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
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.
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
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
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
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
When this step is completed, the Partner Profile should look similar to the screenshot below.
73
74
4. Click on the control record to define the receiver, and sender of the IDoc. Complete the form as shown below.
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
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.
On some R/3 releases a message box with the message IDoc sent to R/3 System or external program will pop up. Attention: The IDoc(s) will not be sent to the IDoc Connector server until the message box is closed. Wait several seconds, then check whether the IDocs have been successfully processed by the IDoc Connector. If you have precisely followed the steps of this quick start example, then the following statements should be true. The IDoc Connector server processed two transactions (each delivers 5 IDocs). Therefore the console of the IDoc Connector server and its log contains two entries that claim Task succeeded: Received IDocs were delivered to the integration system. You may also check with the DT-Monitor that the number of finished processes has been increased by two. The process that has been created in the topic Receiving Treatment (page 65) ran two times. Therefore the Monitoring pane of the BIS 6 Front-end should list the two instances of said process as Today's Processes. The IDoc Connector client sent two IDoc files (each containing 5 IDocs), and sent two status confirmations. Therefore the console of the IDoc Connector client and its log contains two entries that claim Task succeeded: IDoc was sent to R/3, and two entries that claim Task succeeded: Status was sent to R/3. You may also check with the DT-Monitor that the number of finished processes has been increased by four. 1. Check whether the IDocs and their status confirmations have been successfully processed by the R/3 system. 2. Go to the transaction WE02 to display the IDocs that have been processed. SAP IDoc Adapter - v6.3.5.Q4 76
3. Set a filter for the Partner Number to limit the amount of shown IDocs.
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
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
Before running this sample scenario, please run the one that uses tRFC. The configurations are the same. Here will be explained only the differences.
79
80
3. Save the data set. 4. Create a new file port Listener. 5. Set Connection for Status IDocs to SID system. 6. Set Local path to Z:\. 7. Save the data set.
Note: Leave the Code page to <platform>, because the file port SEEFILE is not Unicode-enabled.
81
4. Click on the control record to define the receiver, and sender of the IDoc. Complete the form as shown below.
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
C FAQ
Q: Updating SAP Jco on an AIX server causes problems, JCo claims to be operated with the old version of l ibsapjco3.so, or returns a similar message. What has to be done in order to update the shared libraries used by SAP JCo on AIX? A: Updating the shared libraries of SAP JCo that are used by the BIS 6 IDoc Connector requires a special procedure (described below:) Background If AIX loads a shared library into the memory, the image of that library is kept in the memory, even if no process is using the library. If the on-disk copy of the library is altered, then applications using that library still use the in-memory copy, and not the updated disk copy. This represents the expected standard behavior with AIX. In the case of applying a new version of SAP JCo shared libraries, shutting down all BIS 6-JBoss still leaves shared libraries in the memory (e.g. librfccm.so stays in memory). Copying the version of the libraries updates the disk copy, but a subsequent startup of an IDOC Connector instance uses the inmemory library images (if they are still present). Solution Running slibclean before starting the update flushes libraries that are not currently in use from memory. So these are the recommended steps before applying any update of SAP JCo on AIX: 1. Shutdown BIS 6 JBoss and all external nodes (i.e. Tomcat instances) which include an IDoc Connector installation. 2. Run the AIX command /usr/sbin/slibclean as root to clean all non-referenced libraries of SAP JCo from memory. 3. Update all SAP JCo native library. 4. Restart JBoss and the external nodes. These instructions are adapted from SAPNote 608726, which includes more general descriptions on the shared library update on SAP systems with AIX. Q: The IDoc Connector Client cannot establish a connection to the R/3 system. The error message reads partner <IP of R/3 system> not reached. The R/3 system is located behind a firewall and its "real" IP address cannot be accessed directly because of the network address translation (NAT) of the firewall. A: The SAP gateway instance profile has to be extended by the alternative IP of the R/3 system. Please see SAPNote 148832 for further details.
83
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
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.
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
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
SNC is a software layer in the SAP system architecture that provides an interface to an external security product. SAP Systems include basic security measures, which include the SAP authorization concept and user authentication based on passwords. With SNC, you can extend the SAP system security beyond these basic measures to include the protection offered by an external security product. Advantages of using SNC: SNC provides application-level end-to-end security. SNC secures all communications between two SNCprotected components. You receive an individual approach. You use the security product of your choice, choosing the algorithms you want to use. You can change the security product at any time without affecting SAP system business applications.
5.1 Prerequisite
There are several 3 party provider which offer libraries that can be used to implement SNC. SAP offers a product for SNC too. It is named SAPCryptolib. Get SAPCryptolib from http://service.sap.com/swdc. Download the SAP Cryptographic Software. For extracting the files use the tool SAPCAR according to the SAP note 212876.
rd
5.1.1 R/3
A SNC library has been installed properly on the R/3. 1. Copy the system dependent library (libsapcrypto.so or sapcrypto.dll) and the binary sapgenpse(.exe) to /usr/sap/<SID>/SYS/exe/run. (If the library SAPSeculib is used by R/3, it should be replaced by SAPCry ptolib to avoid any conflicts. Furthermore SAPSeculib only supports very short key lengths and the DSA algorithm only. See SAP note 578377 for details). 2. Copy the ticket file that is included in the SAPCryptolib package to /usr/sap/<SID>/DVEBMGS<system no.>/sec. 3. Make sure the environment variable SECULIB is set for both the user <SID>ADM and on MS Windows R/3 for SARService<SID> to the above created path /usr/sap/<SID>/DVEBMGSxx/sec. 4. To use the SAPCryptolib, set/create the following profile parameters (access profile via transaction RZ10): ssf/name = SAPCRYPTOLIB sec/libsapsecu = $(DIR_CT_RUN)/libsapcrypto.so ssf/ssfapi_lib = $(DIR_CT_RUN)/libsapcrypto.so Instead of $(DIR_CT_RUN) the path /usr/sap/<SID>/SYS/exe/run can be used. 87
5. To enable SNC on the application server, set/create/check the following profile parameters (TA RZ10; according SNC User's Guide. Download it at http://service.sap.com/security - Security in detail Infrastructure Security - SNC User's Guide). Enable SNC: snc/enable = 1 Protection level used by default: snc/data_protection/use = <x> Used values: 1. Secure authentication only 2. Data integrity protection 3. Data privacy protection Minimum protection level: snc/data_protection/min = 1 Maximum protection level: snc/data_protection/max = 3 SNC name on the application server, see TA STRUST: snc/identity/as = p:CN=<instance id> Path to the SNC lib for the gateway: snc/gssapi_lib = <path to libsapcrypto.so>
For other parameters or a more detailed description, please refer to SNC Users Guide. Licencing: SAPCryptolib It may be used to secure communications between SAP components, please make sure that your license covers the usage of SAPCryptolib with SEEBURGER products.
Installation
1. Copy the system-dependent library (libsapcrypto.so or sapcrypto.dll) and the binary sapgenpse to the <BIS6_home>/lib/native directory. The binary needs to be located in the same directory as the lib. 2. Copy the ticket file that is included in the SAPCryptolib package to the <BIS6_home>/conf/dt/sap/sec directory. 3. Make sure the environment variable SECUDIR is set to the above created path <BIS6_home>/conf/dt/ sap/sec. This variable has to be set for all users using SAPCryptolib (BIS 6 runtime user and certificate administrator). It is recommended to set this variable in the set-dir script of BIS 6 and in the environment of the SNC certificate administrator. 4. To check the correct setting of the variable SECUDIR, run <BIS_home>/lib/native/sapgenpse. The value of SECUDIR will be printed out. If not set, a warning will be shown.
Cluster Installations
If SNC communication is to be used in a BIS cluster installation, the steps described above need to be repeated on each cluster node, or make the files available as a cluster resource. The same is true for the configuration files mentioned in the topic Configuration. If the SEEBURGER IDoc Connector is run by another user than the one being used for the SNC configuration (this is usually the case in cluster environments), please make sure to set this user name when generating the configuration files.
88
5.2 Configuration
For SNC secured communication a so-called Personal Security Environment (PSE) for the SAP user who is used for the inbound RFC communication has to be created and mapped to this users account in R/3. This identity will also be used by the RFC registration for SAP outbound connections. The following instructions describe the local generation of such a PSE on the SEEBURGER system and its export to R/3 including the user mapping and assignment to RFC registration afterwards. In a cluster environment it is recommended to have the SNC files being stored in the same path on all cluster nodes, or being made accessible through a shared volume. So all files can be reused in the whole cluster environment without any change. If this is not possible, please generate a single PSE on a node and copy it to all other nodes. Then do the configuration steps omitting Generation of PSE file.
PSE
<SECUDIR>\bisuser.pse
CN=bisuser,
OU=Connectors,
Note: The option O is needed if the SEEBURGER IDoc Connector is run by another user than the one being used for generating this PSE and credential files. This is usually the case in a cluster environment. Use the Windows user, or the Unix UID for the O parameter. Use the domain SYSTEM , if the SEEBURGER IDoc Connector is run as a LocalService on Windows. 3. Determine the PSE distinguished name, needed later in BIS and R/3, therefore save this name somewhere: sapgenpse get_my_name p <filename> Return message: CN=bisuser, OU=Connectors, O=SEEBURGER AG, C=DE 4. Export of the generated certificate for import in R/3: sapgenpse export_own_cert p <filename> -o <cert_filename>. The generated certificate has to be added to the list of trusted public keys that are allowed for SNC connections.
89
5. Import the R/3 certificate file to your local PSE sapgenpse maintain_pk a <R/3_certificate_file> -p <pse_file>. 6. Check the correct import with a list command sapgenpse maintain_pk l p <pse_file>. Result, showing the imported certificate of the sample SAP system: *** Object <PKList> is of the type <PKList_OID> *** 1. ------------------------------------------------------------Version: 0 (X.509v1-1988) SubjectName: CN=SEP, O=SEEBURGER IssuerName: CN=SEP, O=SEEBURGER SerialNumber: 00 Validity - NotBefore: Sun May 20 12:06:53 2007 (070520100653Z) NotAfter: Fri Jan 01 01:00:01 2038 (380101000001Z) Public Key Fingerprint: BA61 1C98 3A4B 75AC 3385 8B1E B037 F434 SubjectKey: Algorithm RSA (OID 1.2.840.113549.1.1.1), NULL
90
5. Now the certificate is displayed in SAP Gui. Click the Add to Certificate List button in order to import it as a trusted certificate for your systems PSE.
Note: After the import do not forget to click the Save button (the disc icon) in the menu bar.
91
92
6. Link this certificate of the RFC user to the account. 7. Start transaction SU01, open the SNC tab. There are different naming conventions for the SNC name. The SAPCryptolib uses the syntax: p:<distinguis hed_name> Example: p:CN=bisuser, OU=Connectors, O=SEEBURGER AG, C=DE It is important that the name is determined as canonical (see the dialog), this message should be shown after having saved the dataset.
93
8. Now return to the transaction STRUST and export the systems certificate to a local file. 9. Double-click the Own certificate field, now the contents of this certificate is shown is the text fields below. 10.Then click the Export button marked with a black arrow and export the systems certificate to a local file on the SEEBURGER system.
94
11.On the BIS system, import the locally stored file to the PSE sapgenpse maintain_pk a <R/3_certificate_file> -p <pse_file>. 12.Check the correct import with a list command: sapgenpse maintain_pk l p <pse_file>. Result, showing the imported certificate of the sample SAP system: *** Object <PKList> is of the type <PKList_OID> *** 1. ------------------------------------------------------------Version: 0 (X.509v1-1988) SubjectName: CN=SEP, O=SEEBURGER IssuerName: CN=SEP, O=SEEBURGER SerialNumber: 00 Validity - NotBefore: Sun May 20 12:06:53 2007 (070520100653Z) NotAfter: Fri Jan 01 01:00:01 2038 (380101000001Z) Public Key Fingerprint: BA61 1C98 3A4B 75AC 3385 8B1E B037 F434 SubjectKey: Algorithm RSA (OID 1.2.840.113549.1.1.1), NULL 13.Enable SNC for the registration. 14.Start the transaction SM59 and open the registration to be secured. 15.Select the tab Logon/Security and then click the SNC button in order to enter the SNC configuration. 16.Enter the distinguished name of the PSE imported from the SEEBURGER system, usually it is the same distinguished name as the one mapped to the RFC user account before.
95
17.After saving these setting, select the Activate SNC button on the Logon/Security tab.
96
97
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
No double quotes are needed, if the SNC name contains spaces, which it will in most cases. If they are used anyway, this error might occur: SNCERR_BAD_NT_PREFIX.
99