SAP IDoc Connector
SAP IDoc Connector
The IDoc Connector supports sending and receiving IDoc files to and from a variety of SAP systems.
IDoc Connectors can connect to SAP using any of the following methods:
- NetWeaver RFC SDK
- Classic RFC SDK
- Classic RFC SDK with Unicode Support
- SOAP (send-only)
- Java Connector (JCO)
- SOAP (send-only)
IDoc Connectors can send and retrieve files formatted either as raw IDoc or as IDoc XML.
This section contains all of the configurable connector properties.
Settings related to establishing the connection to the SAP system.
- Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
- Connector Description An optional field to provide free-form description of the connector and its role in the flow.
- Connect Type The method with which to connect to SAP.
- SAP Host Hostname or IP address of the target SAP system.
- System Number The number by which the target SAP system is defined. Valid values are 0-99, and often this value should be 0.
Settings related to authenticating against the SAP system.
- Client The client that is authenticating to the SAP system.
- User The username credential for authentication.
- Password The password credential for authentication.
Settings related to receiving IDoc files.
- Enable IDoc Receiver Whether the connector should retrieve IDoc files from SAP.
- Program ID A unique name that identifies ArcESB to the SAP system.
- IDoc Format Whether to receive files as raw IDoc or IDoc XML.
Control Record Information Options
This section allows for overwriting the control headers for IDoc files before sending them to SAP. This is useful when receiving IDoc files from one SAP system and sending them to another SAP system: in this case the control record should be changed without changing the IDoc file data.
Settings related to the automatic processing of files by the connector.
- Send Whether files arriving at the connector will automatically be sent.
- Retry Interval The amount of time before a failed send is retried.
- Max Attempts The maximum number of times a failed send will be retried.
Settings that determine where files will be uploaded from and received to.
- Input Folder (Send) Files placed here will be uploaded by the connector. If Send Automation is enabled, the connector will automatically poll this location for files to process.
- Output Folder (Receive) Files that are received by the connector will be placed here. If the connector is connected to another connector in the flow, files will not remain here and will instead be passed along to the Input/Send folder for the connected connector.
- Processed Folder (Sent) The connector will place a copy of processed files here if Save to Sent Folder is enabled. This copy of the file will not be passed along to the next connector in the flow.
Settings related to the allocation of resources to the connector.
- Max Workers The maximum number of worker threads that will be consumed from the threadpool to process files on this connector. If set, overrides the default setting from the Profile tab.
- Max Files The maximum number of files that will be processed by the connector each time worker threads are assigned to the connector. If set, overrides the default setting from the Profile tab.
Settings related to communication language.
- Language The language value to be used when connecting to the SAP system. This should be set to the ISO 639-1 for the language the SAP system uses.
Settings related to communicating with SAP through a gateway.
- Gateway Host The hostname or IP address of the gateway through which to connect.
- Gateway Service The gateway service to use.
Logon Load Balancing
Settings related to logging in to the SAP system as a group to enable load balancing.
- Message Server The service name of the load balancer.
- System ID Identifies the SAP system.
- Logon Group The group to use when load balancing.
Secure Network Communications (SNC)
Settings related to using an external security product to enhance the SAP connection security.
- SNC Name The SNC name for the machine making the connection.
- SNC Partner Name The SNC name of the SAP system the connector is connecting to.
- SNC Quality of Protection Level The level of protection added by the SNC product.
- SNC Library The path to the external security product’s library.
Settings related to logs generated when receiving IDoc files.
- Server Log Folder The path on disk to write the log files.
- Log Level The verbosity of logs generated by the connector. When requesting support, it is recommended to set this value to Debug.
- Rotate log files The number of days a log file should be used before another log file is started.
- Delete log files The number of days a log file should be maintained before it is deleted.
Settings not included in the previous categories.
- Parent Connector The connector from which settings should be inherited, unless explicitly overwritten within the existing connector configuration. Must be set to a connector of the same type as the current connector.
- RefreshSchemaOnError When enabled, the connector will attempt to update the schema it uses for parsing when a parsing error occurs. The schema is updated by reaching out to the SAP system and querying for the appropriate schema.
- Log Messages Whether logs from processed files will include a copy of the file itself.
- Save to Sent Folder Whether files processed by the connector should be copied to the Sent folder for the connector.
Settings for specific use cases.
- Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like
setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.
Establishing a Connection
Using NetWeaver RFC SDK
The following libraries from the NetWeaver RFC SDK must be placed into the www\bin\x64 folder of ArcESB (www\bin\x86 on 32-bit operating systems):
Note that the .dll names may be different depending on the version of the SAP RFC SDK installed. The examples above are for version 3.0.
Also note that you will need to add the “sapgw00” service to your listed services for the NetWeaver SDK connection to work on your client machine. This can be added to the services file at the location “C:\Windows\System32\drivers\etc\services”.
Using Classic RFC SDK
The non-Unicode library does not require anything other than librfc32.dll. Place librfc32.dll into the www\bin\x64 folder of ArcESB (www\bin\x86 on 32-bit operating systems). Please note that these libraries are provided in both x86 and x64, so you must use the same platform that the process is using. If the application is running on on a 64-bit version of Windows, the process is 64-bit.
Using Classic RFC SDK with Unicode support
The following libraries from the SAP RFC SDK must be placed into the www\bin\x64 folder of ArcESB (www\bin\x86 on 32-bit operating systems):
Note that the .dll names may be different depending on the version of the SAP RFC SDK installed. The examples above are for version 3.0. Please note that these libraries are provided in both x86 and x64, so you must use the same platform that the process is using. If the application is running on on a 64-bit version of Windows, the process is 64-bit.
Using the Java Connector
In order to use the Java Connector, the sapjco3.jar must be added to the lib folder of your Java servlet container.
SOAP can only be used for sending IDocs to SAP. In order to receive IDocs from SAP, a different connection type must be used.
Note that this requires enabling SOAP connections on the SAP system.
In addition to the dependencies above, the following services must be added to %WINDIR%\system32\drivers\etc\services, or /etc/services if your system is running Linux or Mac OS X. If SAP NetWeaver is already installed on the machine, then no further action is required.
|Service Name||Connector Number/Protocol|
Logging on to SAP
The following settings are required for connecting with your SAP system.
- SAP Host Host name of the target system. Host names can be regular host names defined in a “hosts” file, an IP address like “126.96.36.199”, or an SAProuter address such as “/H/hostname/S/connector/H/host/S/connector/…”
- System Number The number by which the target system is defined. The valid range is 0 to 99, but in general, this is 0.
- Client The client authenticating to the SAP system.
- User The user that is authenticating to the SAP system.
- Password The password used to authenticate to the SAP system.
When connecting to your SAP via a Gateway, use the options available in the Gateway section found in the Advanced tab of this connector’s settings.
To log on via Load Balancing, set the properties in the Advanced->Load Balancing section.
Secure Network Communications (SNC)
You can enable Secure Network Communications (SNC) on the Advanced tab. Set the SNC Library setting to the .dll of the SNC library you wish to use to connect with SAP.
Sending IDocs to SAP
Once you have configured the IDoc Connector to connect to your SAP system, you can begin sending IDoc files to SAP. The IDoc Connector can send files formatted in raw IDoc or XML IDoc.
You can configure the connector to automatically insert control record information into the IDoc being sent to SAP such as the DOCREL, SNDPOR, SNDPRT, etc. This makes it easier to process outgoing IDocs to the configured system. These settings can be configured in the section Control Record Information of the Connector Settings page.
Before sending an IDoc to your SAP system, you need to make sure that you have properly configured a correct partner profile in SAP. If no partner profile in SAP matches the control record information in the IDoc you are sending, the data will not be processed by your SAP system. You can read more information about setting up a partner profile in the testing section below.
You can use transaction code WE60 to search for segment documentation for different IDoc types.
Test Sending an IDoc to SAP
To test sending an IDoc to SAP, you first need to configure your SAP system to have a partner profile for ArcESB. The following steps will show you how to do this with an ORDERS IDoc.
Create a partner: Go to transaction code WE20 and define a partner profile. You’ll need to set the partner type to KU for “Customer” and the partner number to a valid customer number.
You then need to add an inbound parameter for the ORDERS document. The message type for this document is ORDERS and on the Inbound Options tab, you will need to set the process code as ORDE to tell SAP how to create a sales order when the purchase order ORDERS document is received by the SAP system.
Assign the customer to a sales division: The customer configured in step one must be assigned to a sales organization, distribution channel, and division. Go to transaction VOE2 to configure these settings in the EDSDC table.
Receiving IDocs from SAP
Once you have configured the IDoc Connector to connect to your SAP system, you can begin receiving IDoc files from SAP. The IDoc Connector can receive files formatted in raw IDoc or XML IDoc.
To receive files from SAP, create an RFC destination for ArcESB. You can then select the Enable IDoc Receiver option on the Settings page for your connector and enter the program Id that you registered in your SAP system for ArcESB.
Test Receiving an IDoc from SAP
This example will describe the steps to configure your SAP system to send a MATMAS IDoc to ArcESB.
- Define a logical system: First, go to transaction SALE. Next go to Basic Settings -> Logical Systems -> Define Logical System. Create a new entry with a valid name (e.g., ArcESB) and description.
Create an RFC destination: Open transaction code SM59. Click the create button and fill in the fields for the RFC destination described below.
- RFC Destination A unique name for the new destination (for example, ArcESB_DEST).
- Connection Type ‘T’ for TCP/IP.
- Description A description for the destination.
- Program Id A unique name that will be set in ArcESB to identify the destination.
- Activation Type Select Registered Server Program.
Once you’ve saved the settings, you can test the connection to see if you can successfully connect to ArcESB.
Create a processing connector: Go to transaction code WE21. Create a new Transactional RFC connector with a unique name and the same destination you created in step 2.
Create a partner profile: Open transaction WE20. Create a partner profile for the logical system that was added in step 1. Next add an outbound parameter for the MATMAS document. The message type should be MATMAS. In the Outbound Options section, the receiver connector should be the same as the connector configured in step 3, the output mode should be set to “Transfer IDoc Immed.”, and the IDoc basic type should be set to MATMAS05.
- Send a test IDoc: Use transaction BD10 to send a test IDoc to ArcESB for a specified material number. You will need to configure the Message Type and Logical System before sending the message. You can use transaction BD87 to monitor outgoing messages and process them again if necessary.