BizTalk Server: Working with Preserve Interchange EDI Xml (Part 1)

Article
1/17/2024

Introduction

This is Part 1 of a 2 part article on working with BizTalk EDI's Preserve Interchange feature.

Part 2: BizTalk: Working with Preserve Interchange EDI Xml (Part 2)

The Visual Studio Solution with the sample code can be downloaded from the MSDN Code Gallery at: http://code.msdn.microsoft.com/BizTalk-Working-with-99f2af3b

This article presents some advanced concepts and requires familiarity with BizTalk EDI processing in general. If you are new, please complete all the EDI Tutorials at:

What is an Interchange?

In EDI parlance, an Interchange is the block of data the ISA…IEA envelope for X12 and UNB…UNZ for EDIFACT.

In BizTalk, and Interchange is all messages debatched in the Disassemble Stage of a Pipeline.

It’s important to note that there is a minor different in the practical usage here. In both X12 and EDIFACT, it is acceptable for a transmission to include multiple EDI interchanges, meaning multiple ISA…IEA or UNB…UNZ blocks. In BizTalk, that transmission is represented physically by the Stream that is processed by the Pipeline. The origin of that Stream can be a file, HTTP POST, MSMQ Message or any other transport.

For a business process, an Interchange is most often a group of transactions of the same type. In an EDI Interchange, this is represented by the Functional Group, GS…GE in X12 and UNG…UNE in EDIFACT.

Understanding the interchange boundaries, also referred to as a ‘batch’, for a given business requirement is crucial in selecting an appropriate pattern for a BizTalk app.

This article describes some techniques for using BizTalk EDI’s Preserve Interchange option when maintaining a group of messages has a business justification.

What is Preserve Interchange?

BizTalk EDI offers two ways to process an incoming EDI stream:

Split Interchange as Transaction Sets
Preserve Interchange

Split Interchange as Transaction Sets, which is the default, is what I imaging most developers are familiar with. With this option, the EDI Disassembler debatches each ST…SE into an individual BizTalk Message as represented by the included EDI Schemas.

Preserve Interchange however only breaks the EDI stream at the ISA…IEA/UNB…UNZ level. Each entire ISA…IEA/UNB…UNZ block is parsed into a single Xml message of one of two BizTalk Schema types:

Here’s it’s important to note that while the interchange type is baked into the EDI Disassembler, all of the standard, configurable Transaction Set Schema resolution still takes place and the ST…SE Xml content can still use any custom Schema deployed for that transaction type. As a good practice, you should always change the namespace of the EDI Schemas to one owned by the app itself, meaning not the default Microsoft namespace.

Preserve Interchange Scenarios

When considering a Preserve Interchange solution, there are two practical ways to approach it:

Single Transaction: A Transmission with only EDI Interchange with one Transaction Type. Meaning a single ISA…IEA and GS…GE.
Multiple: A Transmission with any combination of Interchanges and Transaction types.

Most Trading Partner relations seem to use the Single Transaction model where even if the business relationship involves multiple transactions, the generated EDI is only one Transaction Type at a time. However, there are still many situation where any Multiple combinations must be supported. This distinction is important because it will drive how the Schemas are composed.

The Interchange Schemas

A complete Schema for an EDI Interchange is not included with BizTalk Server. This due to very practical considerations as any actual instance of an EDI interchange can contain many combinations of dozens of transactions.

So, when working with Preserve Interchange messages, we have the take the extra step of creating our own set of Schemas.

This article uses the Inbound_EDI project included in the BizTalk SDK at %\Microsoft BizTalk Server 2010\SDK\EDI Interface Developer Tutorial\Inbound_EDI. Following good practices, Parties and an Agreement have been configured for this sample.

The sample schema, X12_00401_850.xsd, has also been modified to use an app specific namespace, http://PreserveInterchangeSample. This namespace is configured as the default namespace on the Local Host Settings section of the THEM->US tab of the Agreement. This is important when following the steps to create the single transaction Schema.

One last note regarding the Interchange Schemas, because the interchange format is baked into the EDI Disassembler, it makes no attempt to resolve the schema against any deployed schemas. So, having multiple copies of the Interchange schemas deployed will not result in an error from the Disassembler

Schema for a Single Transaction Type

The easiest way to create Preserve Interchange Schema for a single transaction is to process an Interchange and use the Well-formed Xml Schema Generator.

If you haven’t setup the Inbound_EDI sample, create a Receive Port/Location and Send Port to process the EDI messages. The Send Port can subscribe to the BTS.ReceivePortName.
In the Agreement, set the Inbound batch processing option to Preserver Interchange – suspend Interchange on Error

Drop the sample EDI file into the receive folder.
Navigate to the Send Port folder and open the xml file. The output will be similar to the following:

In the Inbound_EDI Project, launch the Generate Schemas Wizard and set the Document type: option to Well-Formed XML. Browser to the Xml Interchange file and click OK.

The Wizard will generate a set of schemas based on the xml file.

The auto-assigned GUID’s are not very pretty, but we can easily do a Project scope replace. Note, the Schema editor will raise errors about missing references. This expected at this point and can be ignored.

After completing the Replace operation, you must then rename the .xsd files to match the new name. You should now be able to open the root file without error.

We now have a complete schema for the Preserve Interchange batch. Navigate down to the X12_00401_850 node and expand. Now we see a problem. The generated Schema includes only the segment that were in the sample file.

In order to process all valid 850 transactions, we need to replace this definition with our existing full 850 definition in the file X12_00401_850.xsd.

This can be accomplished with another Replace Operation to replace the PreserveInterchangeSample_X12_8503.xsd reference with X12_00401_850.xsd.

Alternatively, you can modify the PreserveInterchangeSample_X12_8502.xsd file directly using the Xml Editor. The file PreserveInterchangeSample_X12_8503.xsd can now be deleted as it has been replaced by X12_00401_850.xsd.

Finally, remember to change the .Net Type Name for all the generated Schemas.

Now, when viewing the X12_00401_850 element in the Preserve Interchange Schema, we see the full 850 transaction.

If the EDI used to generate the Preserve Interchange Xml contained only one Transaction set, ST…SE, you must change the Max Occurs property of the TransactionSet element to unbounded. Otherwise, you may not get the expected results when Mapping.

Using the Single Transaction Schema

The Schema created in the previous steps can now be used like any other schema to process an entire batch of EDI transactions as a single message.

In this example, the Inbound_EDI Project’s sample Map has been modified to use the Preserve Interchange Schema which will create an OrderFile with multiple Order elements.

Referencing the X12_ServiceSchema

Worth noting is the Envelope Elements, ISA, IEA, GS and GE are already defined in the X12_ServiceSchema that ships with BizTalk Server. You can find this Schema by referencing Microsoft.BizTalk.Edi.BaseArtifacts.dll.

In the scope of this sample, the X12_ServiceSchema can be use instead of PreserveInterchangeSample_X12_8501.xsd, which contains the same definitions generated by the Wizard.

To use the X12_ServiceSchema instead of the generated definitions, location the following xs:import tag in the generated schema:

<xs:import schemaLocation=".\PreserveInterchangeSample_X12_8501.xsd" namespace="http://schemas.microsoft.com/Edi/X12ServiceSchema" />

Replace it with:

<xs:import schemaLocation="Microsoft.BizTalk.Edi.BaseArtifacts.X12ServiceSchema" namespace="http://schemas.microsoft.com/Edi/X12ServiceSchema" />

No other modifications are necessary and PreserveInterchangeSample_X12_8501.xsd can be removed from the project. Additionally, the individual field definitions, ISA01, ISA02, etc. can be deleted form PreserveInterchangeSample_X12_8502.xsd.

You would do this to avoid deploying duplicate definitions. However, if you scenario required promoting specific ISA values for routing, you must use the generated Schema and explicitly specify that in the XmlDisassembler.

Share via