SAP As Adapter En
Short Description
Download SAP As Adapter En...
Description
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
Refer to the SAP Exchange Infrastructure Documentation.
MDN
Message Disposition Notification.
EDI
Electronic Data Interchange.
AS2
Applicability Statement 2.
Module Sequence
Refer to the SAP Exchange Infrastructure Documentation.
TCP
(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.
XML document
SAP Exchange Infrastructure message format, based on XML. Therefore, the present document refers to the messages processed by SAP Exchange Infrastructure as "XML document".
EDIINT
EDI over INTernet.
IETF
Internet Engineering Task Force.
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 recipient’s 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 sender’s 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:
Module Name
Type
Module Key
localejbs/ModuleProcessorExitBean
L
Exit
•
with the following module parameter:
Module Key
Parameter Name
Parameter Value
Exit
JNDIName
deployedAdapters/SeeXIAS2/shareable/SeeXIAS2
3. Set the channel parameters in the Parameters tab. The connection parameters are: HTTP Transport Protocol Parameter
Entry
HTTP Server
Computer with listening AS2 server.
Port
Port of the endpoint with listening AS2 server.
URL Path
Path to the endpoint with listening AS2 server.
HTTP Timeout
Timeout in seconds for waiting for server's response
HTTP Keep Alive
If enabled, the HTTP session is re-used. This optimizes the performance. See chapter “KEEP Alive” for advices.
Basic Authentication User
User for basic authentication.
Password
Password for basic authentication.
Realm
Realm for basic authentication.
Proxy Proxy Server
Your proxy server.
Proxy Port
The port of the proxy server.
Proxy User
User for optional authentication.
Proxy Password
Password for optional authentication.
Proxy Realm
Realm for optional authentication.
Proxy Protocol
Select either - HTTP 1.0 or- HTTP 1.1
AS2 Compress
Select this option if the payload is to be compressed.
Sign
Select this if the payload is to be signed.
Signing Algorithm
Select an algorithm which is applied for signing the payload; we recommend "SHA-12”.
Encrypt
Select this, if the payload is to be encrypted
Encryption Algorithm
Select an algorithm that is used for encrypting the payload; we recommend "RC2/128" or "3DES".
MDN Mode
Select one of the following: •
SYNC to request a synchronous MDN,
•
ASYNC to request an asynchronous MDN,
•
NONE if no MDN is requested
Receipt Delivery Address
Enter the URL of the asynchronous MDNs that are to be delivered (i.e. the URL of your own AS2 server).
MDN Timeout
Enter a time period (in min.), after which an outstanding asynchronous MDN will be interpreted as an error. The value "0" means no timeout.
Sign MDN
Select this option, if the MDN is to be signed.
Message Subject
This text is sent to the server within the optional HTTP header “subject”.
Content Type
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
Deliver transmission report
A special transmission report is delivered to the report channel.
HTTPS Transport Protocol Parameter
Entry
Server Certificate (Keystore)
Alias for SSL encryption certificate or alias for SSL encryption truststore. This truststore must contain all available server certificates.
Private Key for Cleint Authentication
Alias for client SSL encryption certificate
SSL Hostname Check
Validate common name against server name
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: 28ed0ba0-a391-11da-8662-001143d58f14 DeliveryReport SUCCESS true subject test from XI to Partner channel reports
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://:/SeeburgerMonitor/monitor or better HTTP://:/seeburger. For details read the manual “SEEBURGER Message Monitor for SAP PI” and “SEEBURGER Resource Management for SAP PI”.
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: 28ed0ba0-a391-11da-8662-001143d58f14 TransmissionReport SUCCESS true subject test from XI to Partner channel reports
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:
Module Name
Type
Module Key
localejbs/CallSapAdapter
L
Entry
•
No module parameters are required
2. Set the connection parameters on the Parameters tab page.
Parameter
Entry
AS2 Authentication Required
If this flag is activated, this channel will only accept signed messages / MDNs.
Message Subject
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
Used to enable/disable proxy usage.
Proxy Server
Your proxy server.
Proxy Port
The port of the proxy server.
Proxy User
User for optional authentication.
Proxy Password
Password for optional authentication.
Proxy Realm
Realm for optional authentication.
Proxy Protocol
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.
Private Key for Client Authentication
Alias for client SSL encryption certificate
SSL Hostname Check
Validate common name with server name.
HTTP Timeout
Timeout in seconds for waiting for server response.
HTTP Keep Alive
If enabled, the HTTP session is re-used. This optimizes the performance. See chapter “Keep Alive” for advices.
MDN Retry Interval
Interval between the attempts to send MDN.
MDN Retry Count
Number of attempts to send MDN.
Use Authentication
Used to enable/disable basic authentication.
User
User for basic authentication.
Password
Password for basic authentication.
Realm
Realm for basic authentication.
SMIME Content-Transfer-Encoding
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.
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:
Module Name
Type
Module Key
localejbs/CallSapAdapter
L
Entry
•
No module parameters are required
4. Set the connection parameters on the Parameters tab page. Parameter
Entry
Message Subject
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.)
Dynamic attributes from adapter internal splitter
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)
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
Entry
AS2 Sender Configuration Authentication Certificate
Partner's public certificate. This is required for authenticating inbound AS2 messages and asynchronous received MDNs.
AS2 Receiver Configuration Decryption Key
Own private key. This key is required for the decryption of received AS2 messages.
Signing Key
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
Entry
AS2 Sender Configuration Signing Key
Own private key. Used for signing outbound AS2 messages and outbound MDNs.
AS2 Receiver Configuration Encryption Certificate
Partner's public certificate. Used for encryption of AS2 messages.
Authentication Certificate
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 system’s 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://:/SeeburgerAS2/AS2Server
For SSL, the default SSL port is 501. A connection to the AS2 server can be established via SSL by entering HTTPs://: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 adapter’s 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
Splitting type
Description
EDIFACT
UNB
Split messages by UNB segments
ANSI X12
ISA
Split messages by ISA segments
EDIFACT, ANSI X12, Inhouse
BLOCK
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, system’s 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, system’s default encoding will be used for split messages to forward to the sender communication channel.
The parameters listed below are case-sensitive!: Key
Value
Description
filetype
Edifact, Inhouse, AnsiX12
Fixed value for the filetype (overwrites detect filetype!)
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.
Split
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.
Example: Key: EdifactSplit Value: UNB Key: InhouseSplit Value: BLOCK OutputBlockSize
The size of the output parts for block splitting
InputFileEncoding
Name of a valid Java 1.4.2 encoding
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!
OutputFileEncoding
Name of a valid Java 1.4.2 encoding
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!
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 /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
Content
AS2-OUTBOUND--#-.dmp
Contains the outbound composed AS2 message. This message can be compressed, encrypted and signed. It also contains the AS2 and HTTP headers.
INBOUND--#-.dmp
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.
MDN-INBOUND--#-.dmp
This file contains the received MDN. The MDN is parsed, so the AS2 and HTTP headers are missing.
AS2-INBOUND--#-.dmp
This file contains the received AS2 message. The message is verified, decrypted and uncompressed. So it contains the AS2 payload in ‘clear text’.
MDN-OUTBOUND--#-.dmp
This file contains the composed MDN. It contains also the AS2 and HTTP headers.
client_outgoing--$-.dump
The HTTP request containing the HTTP headers and the AS2 message. This is the dump from the HTTP client on the transport level.
client_incoming--$-.dump
The HTTP response containing the HTTP headers. This is the dump from the HTTP client on the transport level.
Example: 14df741#109cf7bf229#-7f82
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.
# 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://: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 system’s 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 don’t 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 does not match host name Cause: Name used in URL in order to access the partner’s 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. ( resp. IP instead of .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 partner’s 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 partner’s 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: Cause: The AS2 adapter is unable to resolve the used DNS name of the partner’s AS2 server. Solution: Quick check: Check if the system is able to resolve the name of the remote host using nslookup or ping –a (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 host’s 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 does not match host name ”) 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 partner’s 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 partner’s AS2 server is not reachable due to the following reasons: 1) An incorrect port is being used for the partner’s AS2 server. 2) A firewall is blocking the communication with the proxy and the partner’s AS2 server. 3) The partner’s AS2 server is down. Solution: 1) Make sure that the correct port is being used for this partner’s 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 doesn’t 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
Direction
Description
REPORTS_OK
OUTBOUND (Client)
The message was successfully sent and a positive MDN was received Correlation is achieved.
REPORTS_OK
INBOUND (Server)
The AS2 message was successfully received and a positive MDN was sent to the partner.
REPORTS_NOT_OK
OUTBOUND (Client)
The AS2 message could not be sent to the partner.
All requested reports are OK
Not all requested reports are OK
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.
OUTBOUND (Client)
The AS2 message was successfully sent. An asynchronous MDN is being awaited.
OUTBOUND (Client)
The AS2 was sent but the asynchronous MDN was not received in the specified time.
View more...
Comments
