SEEBURGER EDIINT AS2 Adapter for SAP Process Integration Configuration Guide

Contents
Terms and Definitions.............................................................................................................................. 4 Overview.................................................................................................................................................. 5 Message Types ................................................................................................................................ 5 Message Exchange.......................................................................................................................... 5 Purpose ............................................................................................................................................ 5 Integration ........................................................................................................................................ 5 Features ........................................................................................................................................... 6 Channel Configuration............................................................................................................................. 7 Use....................................................................................................................................................... 7 Requirements....................................................................................................................................... 7 Actions ................................................................................................................................................. 7 Partner Identification ........................................................................................................................ 7 Receiver Channel (Outbound Processing)....................................................................................... 7 Sender Message Channel (Inbound Processing) .......................................................................... 12 Sender Reports Channel (Inbound Processing) ............................................................................ 15 Dynamic Attributes ......................................................................................................................... 16 Sender Agreement ......................................................................................................................... 18 Receiver Agreement....................................................................................................................... 19 Listener Port and URL.................................................................................................................... 19 Security Settings ................................................................................................................................ 20 Message Splitting ........................................................................................................................... 20 Message Dumping ............................................................................................................................. 22 Troubleshooting..................................................................................................................................... 24 Appendix A: Sample Scenario............................................................................................................... 26 Outbound Processing ........................................................................................................................ 26 Case A: Sending the Order ............................................................................................................ 26 Case B: Receiving the Acknowledgment Report (Optional) .......................................................... 29 Inbound Processing (Messages) ....................................................................................................... 31 Appendix B: HTTP Exceptions .............................................................................................................. 33 Appendix C: SeeburgerMonitor Message Status Descriptions ............................................................. 36 Appendix D: MessageIdStore................................................................................................................ 37

Icons
Syntax

Caution

Component

Example

Function

Note

Recommendation

Terms and Definitions

Communication Channel MDN EDI AS2 Module Sequence TCP Refer to the SAP Exchange Infrastructure Documentation. Message Disposition Notification. Electronic Data Interchange. Applicability Statement 2. Refer to the SAP Exchange Infrastructure Documentation. (Transmission Control Protocol): Communications standard used in TCP/IP networks (e.g. the internet), which allows two computers to establish a connection and to exchange data. SAP Exchange Infrastructure message format, based on XML. Therefore, the present document refers to the messages processed by SAP Exchange Infrastructure as "XML document". EDI over INTernet. Internet Engineering Task Force.

XML document

EDIINT IETF

Overview
The EDIINT protocol enables the secure exchange of EDI data over the public Internet. It secures the transmission of arbitrary (but usually EDI) files. EDIINT AS2 uses HTTP (i.e. the WWW protocol) as its transport protocol. The purpose of the principle design is to define standard procedures for data confidentiality, authenticity and non-repudiation of receipt, which build on existing and established Internet technologies. The IETF hosts the development of the EDIINT standards. The resulting specifications are based on various other IETF specifications, e.g. MIME (RFC 2045) for data encapsulation, S/MIME (RFC 2633) for authenticity and confidentiality, and HTTP (RFC 2616) for transport.

Message Types
AS2 uses two different message types: the actual payload message and the Message Delivery Notification (MDN). The payload message encapsulates an EDI file, thus it can be transmitted via HTTP. Optionally, the payload message is compressed, encrypted, or digitally signed by the sender. The purpose of the MDN is to acknowledge the receipt of a payload message. An MDN contains machine-readable information on the delivery state of the payload message. E.g., it contains the message digest (MIC) of the payload message as calculated by the recipient. An MDN is optionally signed then the recipient can authenticate the sender of the MDN and check its integrity. A validly signed MDN combined with a valid MIC, reported by the MDN, can be used by the payload message sender to claim non-repudiation of receipt (NRR) of the payload message.

Message Exchange
In the simplest case of AS2 message exchange, a sender includes the EDI payload file that is to be sent in an AS2 message structure; and sends this AS2 message via HTTP to the receiving trading partner. Optionally, the sender compresses, signs or encrypts the AS2 message. In this case, the sender has no warranty for the state of the message on the recipients side. If the sender wants to be sure that the message has been transferred without modifications and that the recipient has been able to decompress, or decrypt the message, the sender must request an MDN from the recipient. In this case, the sender indicates the request for an MDN along with the transmission of the payload message. Basically, there are two different modes in which an MDN can be delivered: Synchronous: The MDN is delivered in combination with the HTTP response to the HTTP request that carried the payload message. Asynchronous MDN: The MDN is delivered after the payload message has been transmitted.

In the asynchronous case, the sender must indicate the MDN's destination address. The asynchronous MDN may be delivered by a separate HTTP request to the senders web server. In order to identify the sender of an AS2 message, the trading partners have to agree upon unique identifiers, the so-called "AS2-Ids". AS2-IDs are generally arbitrary character strings.

Purpose
The SEEBURGER EDIINT AS2 Adapter is responsible for transmitting files according to the AS2 protocol. This protocol is commonly used in Business-to-Business scenarios.

Integration
The EDIINT AS2 adapter can be configured in the configuration part of the Integration Builder. The adapter is based on the Adapter Framework and is executed by the SAP J2EE Adapter Engine as shown in the diagram.

Features
The EDIINT AS2 Adapter implements the following protocols: AS2 over HTTP AS2 over HTTP/s

The following EDIINT AS2 options are supported: Message encryption Message / MDN signing Compression Synchronous / asynchronous communication

The following Qualities of Services are supported: Outbound (AS2 sends a message to an external partner) Best Effort Exactly Once Exactly Once in Order

Inbound (AS2 adapter receives a message from external partner) Exactly Once

Channel Configuration
Use
The EDIINT AS2 adapter must be configured in order to exchange files with your business partners using the AS2 protocol.

Requirements
The EDIINT AS2 adapter and its metadata file must be installed.

Actions
To configure the adapter, select the adapter type "AS2" in the communication channel.

The user must select, whether the adapter will be used for sending, or for receiving, and which transport protocol is to be used: HTTP or HTTP/S.

Partner Identification
The unique AS2 ID must be entered as an Alternative Identifier in the Party configuration view.

The value of the Agency field must be Seeburger. The value of the Schema field must be AS2ID.

The AS2ID that is entered here will be used for identifying the sender and receiver of the document

Receiver Channel (Outbound Processing)

When the adapter is used in a receiver channel, it obtains a message from the Integration Engine and sends it to a business partner. In this case, the following steps are required: 1. Define the channel as a Receiver channel on the Parameters tab

2. The last step ensures the module sequence is complete: Make sure the module ModuleProcessorExitBean does exist in the module sequence: Type L Module Key Exit

Module Name localejbs/ModuleProcessorExitBean with the following module parameter: Parameter Name JNDIName

Module Key Exit

Parameter Value deployedAdapters/SeeXIAS2/shareable/SeeXIAS2

3. Set the channel parameters in the Parameters tab. The connection parameters are: HTTP Transport Protocol Parameter HTTP Server Port URL Path HTTP Timeout HTTP Keep Alive Computer with listening AS2 server. Port of the endpoint with listening AS2 server. Path to the endpoint with listening AS2 server. Timeout in seconds for waiting for server's response If enabled, the HTTP session is re-used. This optimizes the performance. See chapter KEEP Alive for advices. Entry

Basic Authentication User Password Realm Proxy Proxy Server Proxy Port Proxy User Proxy Password Proxy Realm Proxy Protocol AS2 Compress Sign Signing Algorithm Encrypt Encryption Algorithm MDN Mode Select this option if the payload is to be compressed. Select this if the payload is to be signed. Select an algorithm which is applied for signing the payload; we recommend "SHA-12. Select this, if the payload is to be encrypted Select an algorithm that is used for encrypting the payload; we recommend "RC2/128" or "3DES". Select one of the following: Receipt Delivery Address MDN Timeout SYNC to request a synchronous MDN, ASYNC to request an asynchronous MDN, NONE if no MDN is requested Your proxy server. The port of the proxy server. User for optional authentication. Password for optional authentication. Realm for optional authentication. Select either - HTTP 1.0 or- HTTP 1.1 User for basic authentication. Password for basic authentication. Realm for basic authentication.

Enter the URL of the asynchronous MDNs that are to be delivered (i.e. the URL of your own AS2 server). Enter a time period (in min.), after which an outstanding asynchronous MDN will be interpreted as an error. The value "0" means no timeout. Select this option, if the MDN is to be signed. This text is sent to the server within the optional HTTP header subject. The content type should be set. A random content type can be set, but we recommend one of the following: application/edifact for EDIFACT files application/edi-x12 for ANSI X.12 files application/xml for XML files text/plain for plain text files - application/octet-stream for arbitrary binary files

Sign MDN Message Subject Content Type

Deliver transmission report

A special transmission report is delivered to the report channel.

HTTPS Transport Protocol Parameter Server Certificate (Keystore) Entry Alias for SSL encryption certificate or alias for SSL encryption truststore. This truststore must contain all available server certificates. Alias for client SSL encryption certificate Validate common name against server name

Private Key for Cleint Authentication SSL Hostname Check

Those attributes are set using the following two namespaces (both!):

Caution: When changing SSL configuration settings like the server certificate, the adapter needs to be restarted, since it caches these settings.

Payload Handling
The payload type must be specified, depending on the settings in the module chain: It can be decided where to get the sending payload from: MainDocument, or Attachment.

The Attachment alias makes it possible to select a specific attachment to send via AS2.

MDN
Whenever a file is sent to a business partner (i.e. the adapter functions as receiver), in synchronous or asynchronous MDN mode, a Message Disposition Notification (MDN) will be received after the document has arrived at its destination. The handling of these acknowledgments can be configured over the Handle received MDN flag. If the MDNs are processed in the PI system, this flag must be set to Refer to XI System. The adapter will then create an acknowledgment report message containing some information on the acknowledged document. Important: In case Refer to XI System is selected, a sender channel with message protocol Reports and a sender agreement for the generated acknowledgment report messages (refer to

the paragraph Sender Message Channel (Inbound Processing)) have to be configured. In case of asynchronous MDN mode, an Report channel and Sender agreement always have to be configured also when Refer to XI system is disabled! The report is an XML document that looks similar to the following example:
<?xml version="1.0"?> <DtReport> <correlationId>28ed0ba0-a391-11da-8662-001143d58f14</correlationId> <category>DeliveryReport</category> <state>SUCCESS</state> <finalReport>true</finalReport> <specificData> <key>subject</key> <value>test</value> </specificData> <specificData> <key>from</key> <value>XI</value> </specificData> <specificData> <key>to</key> <value>Partner</value> </specificData> <specificData> <key>channel</key> <value>reports</value> </specificData> </DtReport>

If the parameter Handle received MDN is set to No action, no DeliveryReport message (MDN) will be sent to the PI system. In both cases, all MDN activities (MDN send and MDN received) are written to a MessageIDStore file. This file can be monitored via the following URLs: HTTP://<host>:<http-port>/SeeburgerMonitor/monitor or better HTTP://<host>:<httpport>/seeburger. For details read the manual SEEBURGER Message Monitor for SAP PI and SEEBURGER Resource Management for SAP PI.

<correlationId> contains the Message-ID generated from the PI System. Thus, references to the outbound (sending) process are created.

When using the QoS Best Effort, the result message of the transaction is a so-called transmission report:
<?xml version="1.0"?> <DtReport> <correlationId>28ed0ba0-a391-11da-8662-001143d58f14</correlationId> <category>TransmissionReport</category> <state>SUCCESS</state> <finalReport>true</finalReport> <specificData> <key>subject</key> <value>test</value> </specificData> <specificData> <key>from</key> <value>XI</value> </specificData> <specificData> <key>to</key> <value>Partner</value> </specificData> <specificData> <key>channel</key> <value>reports</value> </specificData> </DtReport>

Sender Message Channel (Inbound Processing)

When the adapter is used in a sender channel, it will receive messages from the business partner and will send them to the Integration Engine. In this mode, the AS2 adapter will wait for incoming messages and will forward them to the Integration Engine, as soon as they arrive. The AS2 adapter must be configured as follows: 1. Define the channel as a Sender channel in the Parameters tab Select the Message Protocol AS2. Make sure the module CallSapAdapter does exist in the module sequence: Type L Module Key Entry

Module Name
localejbs/CallSapAdapter

No module parameters are required

2. Set the connection parameters on the Parameters tab page.

Parameter AS2 Authentication Required Message Subject

Entry

If this flag is activated, this channel will only accept signed messages / MDNs. This subject will be compared with the subject in the received message. This is used to find the correct channel for the inbound message. Wildcards are allowed.

Asynchronous MDN Settings Use Proxy Proxy Server Proxy Port Proxy User Proxy Password Proxy Realm Proxy Protocol Used to enable/disable proxy usage. Your proxy server. The port of the proxy server. User for optional authentication. Password for optional authentication. Realm for optional authentication. Select one: - HTTP 1.0 - HTTP 1.1 Server Certificate (Keystore) Alias for SSL encryption certificate or alias for SSL encryption truststore. This truststore must include all server certificates. Alias for client SSL encryption certificate Validate common name with server name. Timeout in seconds for waiting for server response. If enabled, the HTTP session is re-used. This optimizes the performance. See chapter Keep Alive for advices. Interval between the attempts to send MDN. Number of attempts to send MDN. Used to enable/disable basic authentication. User for basic authentication. Password for basic authentication. Realm for basic authentication. This value is used only when canonicalizing payloads to validate incoming signatures. It is used when the incoming signed part has no header Content-Transfer-Encoding. Default value is 7Bit.

Private Key for Client Authentication SSL Hostname Check HTTP Timeout HTTP Keep Alive MDN Retry Interval MDN Retry Count Use Authentication User Password Realm SMIME Content-Transfer-Encoding

Caution: When changing SSL configuration settings like the server certificate, the adapter needs to be restarted, since it caches these settings.

Payload Handling
It is possible to specify how the message is delivered to the PI System: Either included in "MainDocument" or in "Attachment".

If "Attachment" as Payload Mode is selected, the "MainDocument" of the XI Message contains a transmission report.

In case of very large data, the incoming payload can be processed witht the adapter's internal splitting mechanism. For further details, refers to the chapter Message Splitting in this manual.

DefaultEncoding
The Sender Channel allows to set the default encoding on the incoming messages. No transformation is done during receiving by the adapter. If the message specifies a encoding, this one will be used, only in case the encoding is unknown/unclear, the default-encoding from sender channel is used. This information shall be added to the meta data for received message.

Inbound lookup order

There is a defined order in which the matching inbound channel is looked up. First the adapter looks for a sender channel with a message subject configured. If there is one channel with a matching subject configured, the channel is used for forwarding the received payload to the PI system. If there is no channel configured with an matching subject the received payload is rejected. If there is one channel configured with a matching subject and another channel with a wildcard both channels will match. In this case the received payload is forwarded to the channel without wildcard configured. If there is more than one channel configured with a matching subject, the payload is rejected. If the scenario from adapter version 1.5 is not updated to the subject using channels in adapter version 1.6, the matching channel is looked up - due to compatibility - described in the earlier documentation for adapter version 1.5.

Using outdated 1.5 or 1.6 channels is not supported anymore. Communication Channel definitions should be upgraded to latest Adapter Metadata.

Sender Reports Channel (Inbound Processing)

When the adapter is used in a sender channel selected the message protocol Reports, it will receive MDNs from the business partner and will send them to the Integration Engine. In this mode, the AS2 adapter will wait for incoming MDNs and will forward them to the Integration Engine, as soon as they arrive. The AS2 adapter must be configured as follows: 3. Define the channel as a Sender channel in the Parameters tab Select the Message Protocol Reports. Make sure the module CallSapAdapter does exist in the module sequence: Type L Module Key Entry

Module Name
localejbs/CallSapAdapter

No module parameters are required

4. Set the connection parameters on the Parameters tab page. Parameter Message Subject Entry This subject will be compared with the subject from the sent message a MDN was received. This is used to find the correct channel for the inbound MDN. Wildcards are allowed.

Dynamic Attributes
Dynamic attributes are part of the XI message. They provide options for dynamical configuration of the AS2 receiver channels (Outbound direction) using parameters that have been dynamically added or set by modules and mappings before AS2 adapter. These attributes can be set using the Attribute Mapper module for example. Besides, the AS2 adapter dynamically adds specific parameters to the XI message on Inbound case, which can be used by the modules and mappings after AS2 adapter.

Outbound Direction
Supported dynamic attributes are:

dtSubject if the subject parameter is set in the XI message and the AS2 receiver channel is configured to use all non-empty or subject attribute, it will be treated as the message subject by the AS2 adapter; dtAS2FileName the name of the payload. This is an attribute of the Content-Disposition header. With this AS2 is compatible with AS2 Filename Preservation draft. dtAS2ContentType for Example application/xml, depending on the payload type

These attributes are supposed to have one of the following namespaces: http://seeburger.com/xi/common http://seeburger.com/xi/AS2

Inbound Direction
The following attributes are appended to the XI message: dtSubject (remote file name) Common attributes dtSender (sender party) dtReceiver (receiver party) dtCorrelationId dtMsgType (MESSAGE or REPORT) dtAttachmentName dtCorrelationId DtAS2FileName AS2 specific attributes

Payload encoding

DefaultEncoding (Either the default encoding configured in the communication channel or the encoding transmitted. Encoding transmitted in message has a priority.) SequenceNumber (http://seeburger.com/xi/filesplitter) SequenceOffset (http://seeburger.com/xi/filesplitter) SequenceMaxCount (http://seeburger.com/xi/filesplitter) SequenceLastMsg (http://seeburger.com/xi/filesplitter) GroupID (http://seeburger.com/xi/filesplitter) FileType (http://seeburger.com/xi/filesplitter)

Dynamic attributes from adapter internal splitter

If not stated otherwise, those attributes are set using the following two namespaces (both!): http://seeburger.com/xi/common http://seeburger.com/xi/AS2

To enable the usage of dynamic attributes, there is an extra section in Receiver Channel. Dynamic attributes are used if the Use dynamic attributes setting is checked in the receiver channel. If the the

setting Use non-empty attributes is not selected, all known attributes are used for configuration if the attribute is present. The following example shows the dynamic attributes configuration panel of a receiver channel:

Dynamically set attributes override static channel attributes. Example: the subject attribute to be used in receiver channels overrides the channel attribute. Here is an example how to set them. Channel tab Module | Module Configuration:

Sender Agreement
Before an AS2 message can be received, a sender agreement must be created. The following information is required for creating a sender agreement
-

Sender: Party Receiver: Party The same sender and receiver party must not be used in more than one sender agreement. In the sender agreement, enter the certificate information required for encryption and signing.

Parameter AS2 Sender Configuration Authentication Certificate

Entry

Partner's public certificate. This is required for authenticating inbound AS2 messages and asynchronous received MDNs.

AS2 Receiver Configuration Decryption Key Signing Key Own private key. This key is required for the decryption of received AS2 messages. Own private key. This key is used for signing outbound MDNs.

Receiver Agreement
In the receiver agreement, enter the certificate information required for encryption and signing.

Parameter AS2 Sender Configuration Signing Key AS2 Receiver Configuration Encryption Certificate Authentication Certificate

Entry

Own private key. Used for signing outbound AS2 messages and outbound MDNs.

Partner's public certificate. Used for encryption of AS2 messages. Partner's public certificate. Used for authentication of synchronously received MDNs.

Listener Port and URL

Trading partners require the name, the port and the URL-Path of your PI server (or adapter engine), in order to send their AS2 messages and MDNs to the AS2 adapter.

Per default, the port is set to "50000". This setting can be modified over the SAP PI systems HTTP server configuration. For further information, refer to the corresponding SAP documentation. The URL-Path cannot be configured. It is: /SeeburgerAS2/AS2Server So in general the complete URL is: HTTP://<your-xi-server>:<http-port>/SeeburgerAS2/AS2Server

For SSL, the default SSL port is 50<sysnr>1. A connection to the AS2 server can be established via SSL by entering HTTPs://<your-xi-server>:50001/SeeburgerAS2/AS2Server

Security Settings
Some special security settings must be performed, in order to use encryption, signing or SSL. For further information, refer to the SAP PI Master Installation Guide manual, chapter SAP PI Keystore Configuration.

Message Splitting
The adapter has a built-in classifier and splitting facility. See the category called Splitter settings within your adapters sender channel. This feature allows to automatically detect the file type (EDIFACT, ANSI X12, Inhouse) and file encoding of the received file and to split the message using several splitting types. The supported splitting types are: File type EDIFACT ANSI X12 EDIFACT, ANSI X12, Inhouse Splitting type UNB ISA BLOCK Description Split messages by UNB segments Split messages by ISA segments Split messages into blocks of (X Kb)

To activate the internal splitting feature, mark the check box Use built-in splitting. Only if internal splitting is activated, the detection of filetype and encoding is possible. Since often the file type of the received file is unknown, the built-in classifier can be used to detect the filet ype. This way, splitting can be configured for the sender channel separately for each expected file type. If the file type is identical for each message which is initiated via this channel, it can be specified causing the same splitting mechanism being executed for each message. Activate check box detect filetype to enable automatic detection of the file type. Otherwise the file type has to be configured manually within splitter parameter table. Automatic encoding detection is a general problem. A reliable detection of all encodings (and thus a correct representation within an application) would require that either the encoded file contains some type of header that tells the interpreter which encoding is used or the text of the input file is known, to check how some special characters are encoded. Both is not always applicable. Therefore the classifier can only guess the correct encoding of the input file. If you know the input encoding, please specify it exactly in the parameters table or configure it for your channel in the encoding section for the payload handling if available, to avoid encoding problems. If no encoding detection is used and no specific encoding is configured, systems default encoding is used. Activate check box detect encoding to enable automatic detection of input file encoding. Not only the file encoding of the received file is important, but also the encoding that is used to initiate the split parts. If no automatic detection is used or no output encoding is explicitly configured in splitter parameter table, systems default encoding will be used for split messages to forward to the sender communication channel.

The parameters listed below are case-sensitive!: Key filetype Value Edifact, Inhouse, AnsiX12 Description Fixed value for the filetype (overwrites detect filetype!) This parameter can only occur one time in the table. It configures that all messages which are initiated via this channel are treated as this configured filetype. This can cause problems if a different filetype is initiated via this channel. Specifies the type of splitting for the given filetype. The special value nosplit can be used to specify that this filetype must not be split. Example: Key: EdifactSplit Value: UNB Key: InhouseSplit Value: BLOCK OutputBlockSize InputFileEncoding <size in KB> Name of a valid Java 1.4.2 encoding The size of the output parts for block splitting This encoding specifies how the Classifier and the Splitter should interpret the received file. If set to a wrong value, this can lead to problems with recognition of filetype or splitting mechanism. Do not set this parameter if you are not sure whether it is correct. This parameter overwrites the encoding, that is detected by encoding detection! This encoding specifies how the splitter should forward the split message parts to the sender channel for further processing. This parameter overwrites the encoding which is detected by automatic detection!

<filetype>Split

<type of split>

OutputFileEncoding

Name of a valid Java 1.4.2 encoding

Example:

Message Dumping
For debugging purposes, it is possible to dump the complete AS2 message or MDN to a directory on the SAP PI Server. The outbound and incoming AS2 messages are stored with complete HTTP headers. This also applies to the outbound and incoming MDNs. Message dumping can be enabled via the J2EE Admin. Go to the service ConnectorContainer and select the AS2 adapter. Go to the tab ManagedConnectionFactory and then to the sub-tab Properties. Now the property transmissionDataDump can be changed: When the save button is clicked, the adapter is restarted and dumping is activated/deactivated.

Be careful. Only use dumping for debugging purposes, since it reduces the performance of the AS2 Adapter.

The dump files are saved to the <your sap installation>/server0/seeburger/as2/dump directory. The name of the dump files includes the AS2 message ID, thus enabling easy localisation of the corresponding dump files, for received or sent AS2 messages. The following table shows the files and describes their content.

Filename AS2-OUTBOUND--#-.dmp

Content Contains the outbound composed AS2 message. This message can be compressed, encrypted and signed. It also contains the AS2 and HTTP headers. This file contains the real HTTP stream received from the partner. It can contain a MDN or an AS2 message. The stream is not decrypted or decompressed. It contains the AS2 and HTTP headers. This file contains the received MDN. The MDN is parsed, so the AS2 and HTTP headers are missing. This file contains the received AS2 message. The message is verified, decrypted and uncompressed. So it contains the AS2 payload in clear text. This file contains the composed MDN. It contains also the AS2 and HTTP headers. The HTTP request containing the HTTP headers and the AS2 message. This is the dump from the HTTP client on the transport level. The HTTP response containing the HTTP headers. This is the dump from the HTTP client on the transport level. This file contains the raw payload stream received from the AS2Controller. There are no HTTP headers in the file. The headers are located in the traces.

INBOUND--#-.dmp

MDN-INBOUND--#-.dmp AS2-INBOUND--#-.dmp

MDN-OUTBOUND--#-.dmp client_outgoing--$-.dump client_incoming--$-.dump Example: 14df741#109cf7bf229#-7f82

# is the placeholder for the as2 messageID $ is the placeholder for the xi messageID

HTTP Port Range

You can configure a port range for outbound HTTP ports. This is required when the AS2 adapter works behind a firewall that is blocking several outbound ports. You can configure the AS2 client to use every port in the whole port-range (0-0). However, it is also possible to configure the client to use only a small range of ports (example: 20002005).

These ports can be configured in the ManagedConnectionFactory Settings of the AS2 adapter: 1.) Open the NetWeaver Administrator | Application Resources 2.) Select the SeeXIAS2 resource and its resource type JCA Connection Factory 3.) Go to Configuration Properties in the lower tab 4.) Set the property localPortRange.

HTTP Keep-Alive and SSL Certificates

The AS2 adapter can be configured to use the HTTP keep-alive feature. If HTTP keep-alive is enabled, all requests to the same partner are sent within the same HTTP connection. If HTTP keepalive is disabled, for every new request a new HTTP connection is opened and closed again. Due to the better performance HTTP keep-alive should always be ENABLED.

If you want to use HTTP keep-alive with SSL, note: When you have changed your SSL certificates or SSL client certificates, restart the AS2 adapter! (Due to HTTP session caching). This also applies if you only have changed the certificate/truststore alias.

Troubleshooting
How can I test whether the AS2 server works? Open a web browser and connect to HTTP://<server>:50000/SeeburgerAS2/AS2Server If a page with status "405" is displayed, then the server is working properly.

My partner received HTTP Error 403 forbidden. What are the possible reasons? This error may have different reasons: a) You or your partner has entered an incorrect AS2 ID for one of the involved parties. b) A valid sender agreement is missing. c) There are more then one AS2 sender agreements with the same sender AND receiver party. d) The corresponding inbound channel is set to inactive.

My encryption and/or signing are not working. This error may have different reasons: a) Perhaps some of the jar files have not been authorised. Check all the views and the authorised jars. b) Are all the security settings in the sender and receiver agreement correct?

SSL communication is not working. Check whether the SSL provider is enabled.

The following message appears in the audit log when trying to send an AS2 message EDI message composing failed: cannot generate EDI message: javax.mail.internet.ParseException An incorrect content-type has been entered in the outbound channel.

Message encryption failed: java.lang.SecurityException: Unsupported key size, or algorithm parameters The java policy file for unrestricted access has not been installed. The correct policy file must be installed for the corresponding platform (SUN, IBM) to make the encryption and authentication work. After installing the policy files, restart the PI System.

The following message appears in the adapter monitor: java.lang.IllegalStateException: object not properly initialized: MessageFactory unavailable!ModuleProcessor unavailable! There was a problem when starting the adapter. Restart the AS2 adapter now. Then it will work.

Important configuration hint: There can be a problem, when using the Excatly Once mode with synchronous AS2 communication, in case that the MDNs are to be correlated in the PI system When a synchronous MDN has been received, and refer the MDN to the xi system has been selected, in some cases there can be an inconsistency between the SeeburgerMonitor and the

Runtime Workbench. This only occurs, if the received MDN cannot be put into the inbound communication channel, e.g., because of incorrect module configuration, or a missing inbound binding. In this case the Runtime Workbench shows the outbound AS2 message in the WAITING state for retry. However, the SeeburgerMonitor shows the message as delivered to the business party with SUCCESS. The PI systems next try to resend the AS2 message, will therefore end in a duplicate error.

Following error appears in Seeburger- and Adapter Monitor: com.seeburger.ksm.cryptoapi.exception.CryptoApiException: Failed to check repository existance. Perhaps you have forgotten to set the view_creator role of the keystore you are using to EVERYONE. See MasterInstallationGuide for details. After setting the view_creator role dont forget to restart the J2EE engine!

Appendix A: Sample Scenario

Outbound Processing
A file is passed to the PI Integration Engine using the File Adapter that creates an XI message that carries the file as payload. The Integration Engine routes the XI message to the AS2 adapter that runs in the PI Adapter Engine. The AS2 adapter sends the file to the external partner and receives an MDN indicating the (not) successful receipt. The MDN may (optionally) trigger the creation of an acknowledgment report message that is sent to the Integration Engine.

Case A: Sending the Order

reate a file channel for the sender.

reate an AS2 channel for the receiver.

nter the AS2ID for the first partner.

nter the AS2ID for the second partner.

reate a sender agreement.

reate a receiver agreement.

Case B: Receiving the Acknowledgment Report (Optional)

For this purpose, set the Handle received MDN flag of the AS2 channel to Refer MDN to XI System. Additionally, an inbound channel with message protocol Reports and the corresponding agreements for receiving the acknowledgments are required.

reate an AS2 channel for the sender using essage protocol Reports.

reate a file channel for the receiver.

reate a sender agreement.

reate a receiver agreement.

Inbound Processing (Messages)

An external partner sends a file to the AS2 Adapter running in the PI Adapter Engine. An XI message is created, which carries the received file as its payload. The XI message is forwarded to the Integration Engine for mapping and routing. The Integration Engine forwards the XI message to the File Adapter, which writes the file to a target directory in the file system. In this case, the AS2 adapter acts as a server. reate an AS2 channel for the sender with essage protocol AS2.

reate a file channel for the receiver.

reate a sender agreement.

reate a receiver agreement.

Appendix B: HTTP Exceptions

javax.net.ssl.SSLException: Name in certificate <CN of certificate> does not match host name <host name used in url> Cause: Name used in URL in order to access the partners AS2 server is not to the same as the common name in the certificate being used with the AS2 client. Solution: Check the URL. Often the name lacks the fully qualified domain name or the IP is used instead. (<host name> resp. IP instead of <hostname>.seeburger.de is used.)

401 Authorization Required Cause: The web server is using basic authentication. The given credentials (usually for basic authentication) are incorrect or missing. Solution: - Enable the AS2 adapter to use basic authentication - Check the basic authentication settings.

java.io.EOFException: Premature EOF encountered or: java.net.SocketTimeoutException: Read timed out Cause: The request has been completely received by the partners web server. However, it has not sent a response within the default connection timeout of 120 seconds. There are two possible reasons for the AS2 adapter timing out in this situation: The partner is sending no response at all (because of an internal server error), or the returned content-length value is bigger than the bytes that have actually been returned. The AS2 adapter is still waiting for the missing bytes and, as a result times out. Solution: This is a problem concerning the partners web server. java.net.ConnectException: Connection refused: connect Cause: 1) An incorrect HTTP port is used to connect to the partner. 2) A firewall is blocking the communication with the web server. 3) The web server is down. Solution: 1) Make sure that the correct port is being used for this connection. E.g. the default HTTP port of the SEEBURGER AS2 adapter for SAP PI is 50000. 2) Check if there is a firewall, and if the corresponding ports are open.

java.net.UnknownHostException: <used host name> Cause: The AS2 adapter is unable to resolve the used DNS name of the partners AS2 server. Solution: Quick check: Check if the system is able to resolve the name of the remote host using nslookup <host name> or ping a <IP address> (pings are often blocked by firewalls!). If the name is unknown to the used DNS server, an entry of this host in C:\WINNT\SYSTEM32\DRIVERS\ETC\hosts file can be added as a work-around. (On DMZ machines it is quite common that no DNS is available. So the hosts file is the only quick solution for this problem. Using the IP instead of the host name is not a good idea, because of the SSL host name check that is performed by the AS2 adapter. Otherwise the following error: javax.net.ssl.SSLException: Name in certificate <CN of certificate> does not match host name <host name used in url>) will appear. java.net.SocketException: Software caused connection abort: socket write error or: java.net.SocketException: Connection reset by peer: socket write error Cause: The socket is closed by the receiver during the transmission of the request data. Solution: There is a problem with the partners AS2 server. Sometimes there are problems with SSL client authentication. com.seeburger.HTTP.SSLConnException: Server returned status 502: reason 'Bad Gateway' Cause: A proxy is being used to connect to the partner. But the partners AS2 server is not reachable due to the following reasons: 1) An incorrect port is being used for the partners AS2 server. 2) A firewall is blocking the communication with the proxy and the partners AS2 server. 3) The partners AS2 server is down. Solution: 1) Make sure that the correct port is being used for this partners AS2 server. E.g. the default HTTP port of the SEEBURGER AS2 adapter for SAP PI is 50000. com.seeburger.HTTP.SSLConnException: Server returned status 407: reason 'Proxy Authentication Required' Cause: A proxy is used to connect to the partner. This proxy requires authentication. Solution: - Enable proxy authentication. - Check proxy authentication settings. javax.net.ssl.SSLPeerUnverifiedException: peer not authenticated Cause: Perhaps a connection to a HTTP port has been established, which does not support SSL. Solution: Check the HTTP Port. Network not reachable Cause: The network is configured to use a proxy server.

Solution: Enable the AS2 adapter to use a proxy server.

Appendix C: SeeburgerMonitor Message Status Descriptions

Outbound: MIC not verified # authentication-failed Cause: A trading partner only accepts signed messages (In a SEEBURGER component this option can be enabled/disabled with the Authentication required flag). Solution - Check the channel configuration and enable the signing flag. - Check the signing certificate.

Outbound: MIC not verified # authentication-failed, processing continued Cause: An incorrect signing certificate was used, but the trading partner continued with the processing, because it doesnt matter, if the message is authenticated, or not. Solution: Check the signing certificate configuration. Outbound: MIC not verified # decryption-failed Cause: Trading partner cannot decrypt messages. Solution: Check the encryption certificate settings. Inbound: Error while parsing AS2 message: AUTHENTICATION_ERROR Cause: An incoming AS2 message cannot be authenticated. Solution: - Check the authentication certificate settings. - Disable the authentication required flag, if messages without authentication are to be received. Inbound: Error while parsing AS2 message: DECRYPTION_ERROR Cause: An incoming AS2 message cannot be decrypted. Solution: Check the decryption certificate settings.

Appendix D: MessageIdStore
Follows a list of the values that the Status of a MessageIDStore entry can take on for the AS2 Adapter.

Status REPORTS_OK All requested reports are OK REPORTS_OK REPORTS_NOT_OK Not all requested reports are OK

Direction OUTBOUND (Client) INBOUND (Server) OUTBOUND (Client)

Description The message was successfully sent and a positive MDN was received Correlation is achieved. The AS2 message was successfully received and a positive MDN was sent to the partner. The AS2 message could not be sent to the partner. The message was sent and a negative MDN was received. Correlation is not achieved.

REPORTS_NOT_OK

INBOUND (Server)

a) An AS2 message was received and a negative MDN was sent to the partner, because, for example, the message could not be decrypted. b) A message was received and the MDN could not be sent to the partner.

RECEIVE_RETRY Error on receive, task might be sent again SEND_RETRY Error on send, task will be retried WAIT_FOR_REPORT Sent or received,delivery,receipt- or both reports expected TIMEOUT_REACHED Set by MessageIdStore if an entry times out

INBOUND (Server)

The asynchronous MDN could not be sent to the partner. A retry will be initiated.

OUTBOUND (Client)

The AS2 message could not be sent. The job was returned to the system in order to initiate a new attempt. The AS2 message was successfully sent. An asynchronous MDN is being awaited.

OUTBOUND (Client)

OUTBOUND (Client)

The AS2 was sent but the asynchronous MDN was not received in the specified time.