AS2Receiver Component [IP*Works! EDI V8]
Properties
Methods
Events
Configuration Settings
The AS2Receiver component is used to process EDI messages and generate receipts.
NOTE: What follows is a very short description of the component interfaces.
For more information, please consult the help files that come with the respective package.
Remarks
The AS2Receiver implements server-side processing of EDI messages, as specified in [AS2] and RFC 3335. It can be used to decrypt and verify incoming messages and to generate receipts including Message Disposition Notifications (MDNs). The component is designed to be easily incorporated into an HTTP server, and features custom functionality for server environments such as ASP.NET.
BASIC OPERATION
When an AS2 request comes in, you should first invoke ReadRequest. This will populate AS2From and AS2To, and based on this information, you may then set the appropriate certificates. You may specify your certificate with the Certificate property, and your trading partner's (signing) certificate with the SignerCert property.
Then, invoke ProcessRequest to process the request and generate the MDN receipt as specified in [AS2] and RFC 3335. If the request was processed successfully, EDIData will contain the transmitted EDI data. If a problem occurred, EDIData will not be populated and an exception will be thrown. In either case MDNReceipt will contain the RFC-compliant receipt, which should be returned to the client.
The MDNReceipt may be returned by invoking SendResponse. The receipt will be returned either synchronously in the HTTP reply, or asynchronously over a separate HTTP, HTTPS, or SMTP connection, as requested by the client.
To create log files, set LogDirectory prior to invoking ProcessRequest. This will log all incoming and outgoing data.
The following example illustrates how to use the component from an ASP.NET page. Note that in Java it will be necessary to provide an HTTPServletRequest as an argument to ReadRequest before processing the request.
EXAMPLE
AS2Receiver1.ReadRequest();
// At this point, you should check the values of AS2From and AS2To.
AS2Receiver1.Certificate = new Certificate(CertStoreTypes.cstPFXFile, "c:\\my_server_directory\\my_pfx_file.pfx", "my password", "CN=Me");
AS2Receiver1.SignerCert = new Certificate("c:\\my_server_directory\\my_partner_cer_file.cer");
AS2Receiver1.LogDirectory = "c:\\my_server_directory\\my_log_directory";
AS2Receiver1.ProcessRequest();
AS2Receiver1.SendResponse();
Additional functionality allows the user to examine details of the client's request, to permit certain types of errors, or to customize the outgoing MDN.
ADVANCED FUNCTIONALITY
Advanced functionality is provided to allow the user to break down the AS2 process, and to allow finer control over the operation of the server. Where ProcessRequest automates the entire process, additional methods are also provided to handle each step separately.
Parsing Incoming Data
To process an EDI message, invoke ReadRequest to process the headers from the server, or alternatively, manually set Request to the contents of the HTTP request. It may contain both headers and body, or the headers may be specified separately in RequestHeaders. This will provide more information about the client's request, without attempting to read the underlying EDI data.
After invoking ReadRequest, the AS2From, AS2To, and MessageId properties will contain the appropriate values. MDNTo will contain a nonempty string if an MDN is requested; RequestedSigningProtocol, RequestedMICAlgorithms, and ReceiptDeliveryOption provide more information about the client's request. Finally, RequestHeaders contains the complete list of HTTP/AS2 headers.
Next, invoke ParseRequest. The certificate used to decrypt and sign should be specified with the Certificate property, and your partner's signing certificate should be specified with SignerCert. This will process the headers, decompress and/or decrypt the message (if applicable), and verify the signature (if present). EncryptionType, SignatureType, and CompressionFormat describe whether and how the data was encrypted, signed, and compressed, respectively.
ParseRequest will populate EDIType and EDIData.
Error Handling
If any errors occur an exception will be thrown and EDIData will not be populated. Information about the exception will be provided through the exception's error code and message and also through ScanResult. An MDN receipt reporting the error may still be generated; it is recommended that server software trap the error and invoke CreateMDNReceipt to report the error to the client.
The ErrorProcessingFlags property may be configured to allow predetermined types of errors. If ErrorProcessingFlags is set when ParseRequest (or ProcessRequest) is invoked, the errors specified will be allowed, an exception will not be thrown, and EDIData will still be determined. However, ScanResult will still report the error, as will the receipt generated by CreateMDNReceipt. To avoid reporting the errors in the receipt, set the ErrorReportingFlags property.
Creating an MDN-based Receipt
An MDN-based receipt may be created by invoking CreateMDNReceipt. Regardless of the success or failure of ProcessRequest, the receipt may be created as specified in RFCs 3335 and 2298. If no errors occurred when ProcessRequest was invoked, the receipt will report success and will be suitable for non-repudiation of receipt (NRR) if signed. If errors occurred, the MDN will report that an error occurred and that the EDI data was not processed. It is strongly recommended that server software trap any errors thrown by ProcessRequest and return the receipt in this case as well.
The MDNReceipt will consist of the MDN itself, a human-readable
message, MIME headers and footers, and a signature if applicable.
The receipt may be generated by invoking CreateMDNReceipt and customized
further by setting the parameters to CreateMDNReceipt.
The Message parameter to CreateMDNReceipt may be used to customize the human-readable message in the receipt. If it is set to an empty string, an appropriate message will automatically be written whenever MDNReceipt is regenerated.
The receipt will be signed using the protocol specified by ReceiptSigningProtocol, if any. The certificate used to sign the receipt is specified by Certificate. By default the receipt will be signed if explicitly requested by the client, and unsigned otherwise.
Error reporting may be controlled by configuring ErrorReportingFlags. By default, any errors will cause MDNReceipt to report a failure to process the message (either "failed/Failure" or "processed/Error" will be reported, according to the specification and the type of error). Setting ErrorReportingFlags will cause the MDNReceipt to overlook the chosen types of errors. If all errors are overlooked, the MDNReceipt will report success and calculate a MIC on the original message as usual. A warning may be reported by setting the MDNWarning configuration setting.
Additional Server-Side Functionality
When used in a server environment such as ASP.NET, the component may be used to interface directly with the underlying HTTP context. If Request is not set by the user, ParseRequest and ProcessRequest will first get the request from the underlying HTTP environment, if possible. SendResponse will send the reply in this environment if able; otherwise the reply will be directed to standard out.
Property List
The following is the full list of the properties of the component with short
descriptions. Click on the links for further details.
Method List
The following is the full list of the methods of the component with short
descriptions. Click on the links for further details.
| |
| AckRequest | Optional. Acknowledges the incoming request. |
| Config | Sets or retrieves a configuration setting. |
| CreateMDNReceipt | Creates MDNReceipt. |
| ParseRequest | Parses the EDI message and determines the EDIData. |
| ProcessRequest | Processes the EDI data, and generates the receipt. |
| ReadRequest | Reads the AS2 request from the HTTP session. |
| SendAsyncMDN | Sends the MDNReceipt to the URL specified. |
| SendResponse | In a server environment, responds to the requesting client with MDNReceipt. |
| SetTPInfo | A convenient way to set AS2 communication parameters using XML strings. |
Event List
The following is the full list of the events fired by the component with short
descriptions. Click on the links for further details.
| |
| Error | Information about errors during data delivery. |
| SSLServerAuthentication | For asynchronous HTTPS MDNs, fired after the server presents its certificate. |
| SSLStatus | Shows the progress of the secure connection. |
Configuration Settings
The following is a list of configuration settings for the component with short
descriptions. Click on the links for further details.
