Overview

The Analyze method of the EDI Analyzer API analyzes an EDI stream for warnings, errors, and fatal errors before converting the EDI stream to XML. An XML report generated by the Analyze method identifies any errors in the EDI; this report is used by the Convert method to filter out interchanges, groups, and messages that contain errors during conversion, allowing partial processing of EDI streams that contain errors. The analysis report also includes dialect-specific transmission response messages that can be returned to the EDI sender.

Illustration

The following illustration shows how you can use EDI Analyzer API Analyze and Convert methods to convert EDI to XML. It shows EDI provided by an EDI sender – this could be an EDI document, EDI data stored on a file system, or EDI provided by a business partner’s Web service, for example – being passed to an EDI receiver – a separate business entity, a business partner, or some other consuming application. Transmission response messages contained in the analysis report can optionally be returned to the EDI sender.

EDI Analysis

First the EDI data stream is analyzed by the Analyze method for any errors. Errors are classified as warnings, errors, and fatal errors. Errors, along with other information about the EDI stream and its transmission, are captured in an analysis report. The analysis report is always generated by the Analyze method, whether or not the EDI stream is free of errors. The Analyze method does not throw an exception unless the input stream or output stream could not be opened.

Some input data errors can make the input data file unrecognizable to the Convert method. If such is the case, then the analysis report will contain a <FatalError> element which describes the fatal error.

Analysis Report

The analysis report is an XML report generated by the Analyze method. It identifies any interchanges, groups, or messages that contain errors and describes those errors. For some EDI dialects, the analysis report also includes a Response element, with Receipt and Acknowledgement sub-elements that you can use to send transmission responses to the EDI sender.

You can write the analysis report to any output you choose – you might want to review the report before converting the EDI to XML, for example – but the analysis report needs to be available to the Convert method in order for the EDI to be converted to XML.

See EDI Analysis Report for detailed information about the report’s contents and structure.

EDI Conversion

The same EDI stream specified for the Analyze method must be specified for the Convert method. Once the analysis is complete, you pass the analysis report to the Convert method. The Convert method uses the errors identified in the analysis report to filter the EDI, preventing messages containing errors from being converted to XML while allowing the rest of the messages to be converted. When using Convert without the analysis report, if an error or fatal error occurs, the Convert method will throw an exception and no useful XML output will be generated. When Convert is used with the analysis report, then it will throw an exception only if:

Specifying the EDI Stream and EDI Conversion Settings

The EDI input stream specified for the Analyze method must be the same as that specified in the Convert method for a given XML conversion. When using a UriSource, it is convenient to use the same UriSource object for both Analyze and Convert. If, however, you use an InputStream source, you must rewind the input stream after calling Analyze, so that Convert can reread the same data.

Also, any conversion properties specified for the EDI stream in the Analyze method must also be specified for the EDI stream in the Convert method. These conversion properties were specified when the Converter object was created using the ConverterFactory.CreateConvertToXml(…) method. As long as you use the same Converter object for both the Analyze and Convert, you are assured that the same conversion properties are used for both.

Transmission Response Messages

Some EDI specifications provide message definitions for notifying an EDI sender about the success of a transmission, and about those messages that were successfully processed or rejected because of errors. The Analyze method automatically generates transmission response messages, creating a Response element with Receipt and Acknowledgement subelements in the EDI analysis report. Each subelement holds a complete EDI message in XML format that can be easily manipulated using .NET and then serialized to EDI to transmit the response to the EDI sender.

Communicating with the EDI sender is optional, and business entities will have different requirements for transmitting receipt messages, acknowledgement messages, or both. See Managing Transmission Responses for more information on this topic.

Dialect Support

The Analyze method is supported for all EDI dialects supported by DataDirect XML Converters. The Analyze method is supported for EDI to XML conversions only, and not vice versa.

Note, however, that automatic generation of transmission response messages is supported only for these EDI dialects:

Method Definition

The Source and Result implementations are the same as those supported by the Convert(Source, Result) method. In the case of the Analyze method, the Result object receives the EDI analysis report. Once the analysis report has been created, you use this method to convert the input data file:

		void Convert(Source source, Result result, Source analyzeReportSource)

See EDI Analysis Report for detailed information about the report’s contents and structure. See Example 14 to see an implementation of the Analyze method in a simple .NET application.

Command Line Interface

The EDI Analyzer is supported through the command line interface using /analyze and /report options as part of the CmdLine command, as summarized in the following table.

Table 3-1. EDI Analyzer Command Line Options
Option	Description
`/analyze`	Analyzes the EDI data stream, identifying invalid items (a segment with an error, for example). Invalid items are skipped, and the rest of the data stream is converted to XML. Writes the analysis report to a temp file, which is used during the conversion, and then deleted.
`/report` <Uri>	Saves the analysis report to the specified <Uri>. Allows later use of the transmission response messages that are automatically generated for some EDI dialects. Note: The `/report` option cannot be used alone. It must always be used with the `/analyze` option.

See Command Line Usage for general information about using the XML Converters command line interface.

Sending a Transmission Response

The /analyze option performs the EDI analysis and conversion as a single operation. If you want to be able to send a transmission response to the EDI sender, you must use the /report option and specify a file name in order to make the analysis report’s Receipt and Acknowledgement elements accessible for conversion back to EDI.