BizTalk Server EDI Scenario: Send an X12 Message and Receive an Acknowledgement

Article
1/17/2024

The instructions in this article are targeted for a two-machine scenario where both trading partners involved in a B2B scenario have their BizTalk Server setup. If you are looking for a single-machine scenario, see Walkthrough: Sending EDI Interchanges.

This article applies to BizTalk Server 2006 R2 and BizTalk Server 2009. For information on how to set up B2B messaging between two trading partners using BizTalk Server 2010, see Developing and Configuring BizTalk Server EDI Solutions.

Note: To view a complete list of BizTalk Server articles that are available on the TechNet wiki, see BizTalk Server Resources on the TechNet Wiki.

Acknowledgements

We in the BizTalk Server CCxG team gratefully acknowledge the contributions of the following individuals for providing their valuable inputs for setting up the end-to-end scenario used in this article:

Gyan Prakash, BizTalk Server Product Team
Kowshik Pallivela, BizTalk Server Product Team
Farida Bharmal, BizTalk Server PSS

Overview

Note: If you are a new entrant into the world of EDI messaging, you might first want to familiarize yourself with some of the terms that you will read/hear when working with EDI messages. Most of these terms are related to the structure of an EDI message, such as interchange, transaction set, etc. A good place to start reading about these terms would be EDI Messaging.

Electronic Data Interchange (EDI) is the single most commonly used means by which business trading partners exchange data electronically. EDI is largely messaging-oriented. Documents are implemented as flat files that can include batched transaction sets. Batched interchanges can contain multiple groups, each of which can contain multiple transaction sets or messages.

EDI consists of specific data interchange methods agreed upon by standards bodies. The primary EDI standards are X12 (standardized by ANSI and used primarily in North America) and EDIFACT (standardized by the United Nations and used primarily outside the U.S.). Other standards are derived from these, for example, HIPAA from X12 and KEDIFACT in Korea from EDIFACT. The standards are closely parallel in message structure and acknowledgment schemes, but have distinct differences.

The EDI standards prescribe the following:

The formats, character sets, and data elements used in the exchange of documents
The envelopes used in EDI transaction
The acknowledgments required to verify delivery
How to provide guaranteed, exactly-once delivery, and automatic detection and reporting of corrupted or incorrect data.

While the EDI standards establish the rules for the structure of the document, trading partners exchanging EDI messages must agree on the specific information to be transmitted and how it should be used. For example, the partners must agree on details like:

Who will be the sender of the message and who will be the receiver of the message
Whether the message sender expects an acknowledgment
What delimiter to use as a separator for elements in the EDI message
Etc.

In the context of BizTalk Server, the process of defining these parameters of EDI message exchange is achieved by creating a "party" in the BizTalk Server Administration console and then setting the parameters as properties for the party. For more information, see EDI Support in BizTalk Server.

EDI messages are distinguished from their transport. The EDI standards do not prescribe message transport, and EDI messages can be sent by a variety of different means.

EDI Support in BizTalk Server

Before we start discussing how BizTalk Server supports EDI messaging, let us understand a couple of terms:

A home organization is an organization that hosts BizTalk Server and trades with other business partners.
A partner organization is a business partner for the home organization. A partner organization may or may not have BizTalk Server.

One can use BizTalk Server in either of the following ways to set up EDI messaging between trading partners:

Only one of the trading partners have a BizTalk Server set up. In such a case, the partner that hosts BizTalk Server in-house creates a party for its trading organization. For example, if A and B are business partners and A has a BizTalk Server set up, A will create a party for B and then set the properties for the party B.
- Note: A home organization does not have to define itself as a party.

Both the trading partners have a BizTalk Server set up. In such a case, both the trading partners will create a party for the other trading partner in their BizTalk Server set up. To continue with the previous example, A will create a party for B in its BizTalk Server setup and B will create a party for A. Both will then set properties for the parties such that the configurations are compatible. For example, if A is expecting an acknowledgement from B, B must be configured to send an acknowledgement.
Neither of the trading partners have a BizTalk Server set up. In such a case, a third entity, also called the broker organization sets up parties for both A and B and then defines the properties as agreed upon by the trading partners.

This article covers the second scenario where both the business partners have a BizTalk Server environment.

We are now clear about home organizations and partner organizations and who will create a party for whom. The next thing to understand is what properties are set for a party. You can set the following properties for a party:

General party properties such as name, contact information, send ports associated with the party, etc.
EDI properties that define how BizTalk Server will process an incoming message from the party and how it will generate an outgoing message bound to the party.
AS2 properties that define how BizTalk Server will perform AS2 communications, both incoming and outgoing. These properties affect EDI communications only when an EDI message is sent over AS2.
- Note: Configuring general and EDI properties are mandatory for setting up EDI message exchange. AS2 properties are required only if the trading partners are using AS2 transport to exchange messages. Messages can also be exchanged using other means such as using a file adapter, etc.

Set up the Scenario

Now that we have understood some basics of EDI messaging and how BizTalk Server supports EDI, let us understand the scenario we will use in this article to demonstrate how you can use BizTalk Server to process EDI messages.

The scenario involves sending an EDI X12 purchase order message (850) from one trading partner, Fabrikam, to another trading partner, Contoso.
After Contoso receives the message, it sends back an acknowledgement to Fabrikam.
Both the trading partners have BizTalk Server configured at their end.
The message transfer happens using FILE adapters in BizTalk Server. This article/scenario does not cover sending and receiving EDI messages over AS2.

Let us assume that the message that will be transferred is SamplePO.txt. This sample message is available with your BizTalk Server installation under <install drive>:\Program Files\Microsoft BizTalk Server 2006\SDK\EDI Interface Developer Tutorial. Here's the message to be transferred:

ISA*00* *00* *ZZ*THEM *ZZ*US *991221*1226*U*00401*000000025*0*T*>
GS*PO*THEM*US*19991221*1226*1*X*004010
ST*850*0001
BEG*00*NE*3859199838**950727***IBM
PER*AA*Andrew Carlson*TE*(708) 555-2930
DTM*002*970523
PO1*1*93*BX*145.39**CB*KOW-20392-10
PID*F****Uninterruptible Power System
PER*AA*Camilla Anderson*TE*(708) 555-2011
PO1*2*25*EA*35.68**CB*1093-4927-001
PID*F****High Volume Printer Stand
PER*AA*Miranda Cappelan*TE*(708) 555-1111
PO1*3*4*PC*2002.91**CB*ABX-2001
PID*F****Electronics Cabinet Package (56" High)
CTT*3
SE*14*0001
GE*1*1
IEA*1*000000025

Let us now see how both the trading partners will configure this scenario in their respective BizTalk Server environments.

Prerequisites

To setup this scenario, you must have the following:

A computer with BizTalk Server installed and configured (including EDI/AS2 configuration). This machine will represent the FABRIKAM trading partner. We will call this computer FABKAM-BIZTALK
A computer with BizTalk Server installed and configured (including EDI/AS2 configuration). This machine will represent the CONTOSO trading partner. We will call this computer, CONTOSO-BIZTALK.

At Fabrikam

The main requirement at the Fabrikam side would be to simply send the message to Contoso using BizTalk Server. To achieve that, Fabrikam's BizTalk Server setup must have:

Following file folders:
- A local folder from where the FILE receive port will pick the X12 message to be sent to Contoso
- A shared folder where the 997 acknowledgement from Contoso will be sent to Fabrikam
- A shared folder where the TA1 acknowledgement from Contoso will be sent to Fabrikam
A FILE receive port with an EdiReceive pipeline to take the X12 message and move it to the BizTalk Server message box.
A FILE send port with EdiSend pipeline that will subscribe to the X12 message in the message box and send it over to a shared location in the Contoso's set up.
A party for Contoso that has the relevant EDI properties set.
The schema of the EDI message to be transferred must be deployed in BizTalk Server.

At Contoso

Most of the tasks related to the scenario such as processing the X12 message, generating the acknowledgements, sending the acknowledgements to Fabrikam, etc. happen in the Contoso's BizTalk Server setup. To achieve that, Contoso's BizTalk Server setup must have:

Following file folders:
- A shared folder to which Fabrikam will copy over the X12 message.
- A local folder to which the X12 message will be copied after being processed by Contoso's BizTalk Server setup.
A FILE receives port with an EdiReceive pipeline that will consume the X12 message that has been received from Fabrikam and will move it to the BizTalk Server message box.
A FILE send port with EdiSend pipeline that will subscribe to the message in the message box and send it over to a file folder created locally.
A FILE send port with EdiSend pipeline that will subscribe to the 997 acknowledgement in the message box and copy it over to a shared folder in the Fabrikam's set up.
A FILE sends port with EdiSend pipeline that will subscribe to the TA1 acknowledgement in the message box and copy it over to a shared folder in the Fabrikam's set up.
- Note: If you are wondering how 997 and TA1 appear in the message box, here's some quick information. When the EDI receive pipeline processes an X12 message, it stores the X12 message in the message box as XML and in parallel also creates 997 and TA1 for the message and also stores them in the message box, again as XML. We'll discuss more about this when we get to the point where we create these ports.

A party for Fabrikam that has the relevant EDI properties set.
The schema of the EDI message to be received must be deployed in BizTalk Server.

The following illustration depicts how the scenario is set up for Fabrikam and Contoso.

Let us now start setting up the BizTalk Server environment for Fabrikam to send the X12 message to Contoso.

Set up the Scenario at Fabrikam

In this section, we will perform the tasks required at Fabrikam to set up the scenario we discussed above.

Create File Folders

On the FABKAM-BIZTALK computer, under C: drive, create a folder called Messages.

Within the Messages directory, create the following folders:

Folder Name	Folder Access	Remarks
ReceiveX12	Local access	Will be used to drop the request message
Receive997	Shared with everyone, with write permissions	Will be used to receive the 997 acknowledgements
ReceiveTA1	Shared with everyone, with write permissions	Will be used to receive the TA1 acknowledgements

The reason for sharing the two folders with everyone is just for ease of operation and only for the purpose of demo. That's because the acknowledgements will be copied over to these folders from a remote computer.

Create a FILE receive port to get the X12 message

You must create a FILE receive port to get the X12 message into the BizTalk Server message box.

In BizTalk Server Administration console, under BizTalk Application 1, right-click Receive Ports, point to New, and then select One-way Receive Port.
Name the receive port as ReceiveX12, and then click Receive Locations in the left pane.
In the right pane, click New and provide a name for the receive location, such as ReceiveX12_Location
Set the transport type to FILE and click Configure.
For the Receive folder text box, specify C:\Messages\ReceiveX12.
For the File mask text box, specify *.txt. This is because the X12 message that we will use in this scenario is in a .txt file. Depending on the file extension of your X12 message, you can set the file mask accordingly.
Click OK.
In the Receive Location Properties dialog box, select BizTalkServerApplication as the receive handler and then select the EdiReceive as the receive pipeline.

Note: Even though we just need to route the message to the shared folder on Contoso, we use the EdiReceive pipeline because the EdiReceive pipeline will convert the message to XML and then dump to the BizTalk Server message box database. We will then be able to use EdiSend pipeline on the send port that sends the message to Contoso because EdiSend pipeline takes and XML message. If we use a PassThruReceive pipeline here, the message in the message box will be in X12 format and so we would have to use a PassThruTransmit pipeline on the send port as well.
Click OK on the Receive Location Properties dialog box and then click OK on the Receive Port Properties dialog box.

Create a FILE send port to send the X12 message

You must create a FILE send port that will subscribe to the X12 message stored in the BizTalk Server message box.

Verify whether Contoso has created a shared folder with write permissions. The shared folder must be accessible at \CONTOSO-BIZTALK\Messages\ReceiveX12.
Note: For this scenario, we will be creating this shared location when we set up the Contoso side.
In BizTalk Server Administration console, under BizTalk Application 1, right-click Send Ports, point to New, and then select Static One-way Send Port.
Name the send port as SendX12, select the transport type as FILE, and then click Configure.
For Destination folder, specify the shared folder that is created by Contoso to receive the X12, which is \CONTOSO-BIZTALK\Messages\ReceiveX12.
Specify the file name as %MessageID%.txt so that the file received by Contoso is of .txt format, which is the same format in which the file is being sent from Fabrikam.
Click OK.
In the Send Port Properties dialog box, select BizTalkServerApplication as the send handler and then select the EdiSend as the send pipeline.

Note: You use the EdiSend pipeline because the message in the BizTalk message box is an XML message (after being processed by the EdiReceive pipeline) and that has to be passed to the shared folder in the Contoso setup in an X12 format.
In the left pane, click Filters, and enter a filter expression that will be used by the send port to subscribe to the message. For example, you could use the receive location name that will receive the original test message as a filter expression. To do so, for Property, enter BTS.ReceivePortName; for Operator, enter ==; and for Value enter the name of the receive port (ReceiveX12) that you created to receive the X12 message.

Why do we need a filter at all? All the message transfer in BizTalk Server happens via the BizTalk Server message box database. So, there are numerous messages stored there waiting to be consumed. So, how do you figure out which message to pick. That is where filters come in. When you set a filter, you tell BizTalk Server to route only that message to the send port that satisfies the filter criteria.

One such filter is BTS.ReceivePortName, which is used to route the message based on the name of the receive port that initially dumped the message to the BizTalk Server message box. When a message is processed by the receive port, it also promotes the BTS.ReceivePortName on the message and sets it to the name of the receive port. So, in this scenario we can set BTS.ReceivePortName == ReceiveX12. The next obvious question you might get is, there could be so many more messages coming through the same receive port, each having this property set, how would you then ensure that the correct messages are routed? In that case, we would have to have more filters set. For example, the other filter could be on the type of message. In this scenario, an 850 (purchase order) message will be transferred. The message type of an 850 message is http://schemas.microsoft.com/BizTalk/Edi/X12/2006#X12_00401_850. So, to route the message based on the message type, I would add another filter. To do so, for Property, enter BTS.MessageType; for Operator, enter ==; and for Value enter http://schemas.microsoft.com/BizTalk/Edi/X12/2006#X12_00401_850. Make sure you group both these filters using the And operator.
Click OK to close the send port properties dialog box.

Create a Party for Contoso

Like mentioned above, in the Fabrikam's BizTalk Server setup, you must create a party for the trading partner, i.e. Contoso, and then set the EDI properties on that party.

Right-click the Parties node in the BizTalk Server Administration Console, point to New, and then click Party.
Enter a name for the party. Because Contoso is receiving the message, let us name the party as Receiver.
Click Send Ports, and from the Send ports grid, under the Name column, select the send port that you created that will send the interchange to Contoso, and then click OK.

Note: BizTalk Server uses this send port association to determine the party receiving the interchange. Once the party is determined, it uses the properties set on the party to process the outgoing interchange.
Right-click the party in the Parties pane of the BizTalk Server Administration Console, and then select EDI Properties.
In the General page, click Activate EDI Reporting and click Store transaction set/payload for reporting.

The Activate EDI Reporting option ensures that all interchange-related details for a party are tracked in the status report user interface. The Store transaction set/payload for reporting option ensures that the transaction set details and message content are available to view through the status report interface.
In the left pane, under X12 properties, under Party as Interchange Receiver, click ISA Segment Definition. In this interface, you must enter the values for ISA5 to ISA8. The values you enter here will be used by the EdiSend pipeline to create the ISA header for the interchange that will be sent to Contoso. Going by the message (SamplePO.txt), enter the following values:

Use this To do this

ISA5 ZZ-Mutually Defined

ISA6 THEM

ISA7 ZZ-Mutually Defined

ISA8 US

But, why do we need to add these headers when they are already present in the message that is sent to BizTalk Server? When the EdiReceive pipeline (of the ReceiveX12 receive port) processes the message, it rips of the ISA and GS headers from the message, converts it to XML, and then dumps it to the message box database. Now, when that message is picked up from the message box, before sending it to the desired party, the ISA and GS headers have to be added again to the message. In this step, we provided the information to add the ISA header. In the next steps, we provide the information to add the GS headers.

For more information on how these values are used, see How the EDI Assembler Works.

Another thing to question here would be why are these properties being set under Party as Interchange Receiver. That is because the party we created (Receiver) is representing Contoso in Fabrikam's BizTalk Server environment. Because Contoso is "receiving" the interchange, the properties are set under "Party as Interchange Receiver" section.
Under Party as Interchange Receiver, under Separators section, set Suffix to CR LF.
Under Party as Interchange Receiver again, select the check box for ISA14 (Technical acknowledgement required). By setting this property, you specify that you want the receiving party to generate a TA1 acknowledgement and send it back to the sender party.

Note: The sender party cannot set a similar property for requesting a 997 acknowledgement. Generating a 997 is solely governed by the party settings at the receiving trading partner's end.

In the left pane, under X12 properties, under Party as Interchange Receiver, click GS and ST Segment Definition. In this interface, you must enter the values that will be used by the EdiSend pipeline to create the GS headers for the outgoing interchange being sent to Contoso.

Use this	To do this
Default	Select the checkbox.
For ST1	Select the message type of your test message. In this scenario, because we are sending a purchase order message, select 850 - Purchase Order.
Version/Release	Specify the EDI version, 00401.
Target Namespace	Select http://schemas.microsoft.com/BizTalk/Edi/X12/2006.
GS1	Verify that the message type of the test message is selected, for example, PO - Purchase Order (850).
GS2	Enter a value for the interchange sender. Let us enter "THEM"
GS3	Enter a value for the interchange receiver. Let us enter "US"
GS4	Select the date format as CCYYMMDD.
GS5	Select the data format as HHMMSS.
GS7	Select X - Accredited Standards Committee X12.
GS8	Verify that the EDI version has been entered, for example, 00401.

This is how the values in this grid are used by the EdiSend pipeline: BizTalk Server matches the values for ST1, version, and target namespace in the grid with that on the message in the message box database. If there's a match, it uses the other values in the grid to set the values in the GS header for the outgoing interchange. When you select the row as the default, the GS* values are used even if the values for ST1, version, and target namespace are not a match for the message.

For more information on how these values are used, see How the EDI Assembler Works.

In the ACK Processing and Validation Settings page, select the check boxes for EDI type and Extended validation to make sure these validations are performed.

Note: The Functional ACK check box on this page does not govern generation of a functional acknowledgement. It only specifies whether the acknowledgement status is integrated with the interchange status on the status reporting page.
Click OK.

Deploy The Schema for Purchase Order Message

In Visual Studio, create a BizTalk Server project
Right-click the project, point to Add, and then click Existing Item. Move to the folder that your schema is in <drive>:\Program Files\Microsoft BizTalk Server 2006\XSD_Schema\EDI, and then double-click your schema. If the EDI schemas have not been unzipped into the \XSD_Schema\EDI folders, execute the MicrosoftEdiXSDTemplates.exe file in the \XSD_Schema\EDI folder to unzip the schemas into the default folder.
**
Important**: In this article, we will use the SamplePO.txt test message. So, you must use the X12_00401_850.xsd schema that is shipped in the <drive>:\Program Files\Microsoft BizTalk Server 2006\SDK\EDI Interface Developer Tutorial\ folder. You must not use the X12 850 schema in the <drive>:\Program Files\Microsoft BizTalk Server 2006\XSD_Schema folder.
Set the assembly key file, and then build and deploy the assembly. This would deploy the assembly under the default, BizTalk Application 1, application.
Make sure that BizTalk Application 1 has a reference to BizTalk EDI Application. This is required because all the schemas, pipelines, etc. required to process an EDI message are available under the BizTalk EDI Application. This application is created when you configure EDI/AS2 as part of the BizTalk Server configuration. For instructions on adding a reference, see How to Add a Reference to the BizTalk Server EDI Application.

You are now done with setting up the BizTalk Server environment and all the other requisites at Fabrikam's end.

Set up the Scenario at Contoso

In this section, we will perform the tasks required at Contoso to set up the scenario we discussed above.

Create File Folders

On the CONTOSO-BIZTALK computer, under C: drive, create a folder called Messages.

Within the Messages directory, create the following folders:

Folder Name	Folder Access	Remarks
ReceiveX12	Shared with everyone, with write permissions	Will be used to receive the X12 from Fabrikam
ReceiveProcessedX12	Local access	Will be used to receive the X12 after being processed through BizTalk Server

Create a FILE receive port to process the X12 message received from Fabrikam

You must create a FILE receive port that will route the X12 message received from Fabrikam into Contoso's BizTalk Server. The X12 message that is received at C:\Messages\ReceiveX12 is like a request message that has come in. It must be processed by Contoso's BizTalk Server to generate the acknowledgements.

In BizTalk Server Administration console, under BizTalk Application 1, right-click Receive Ports, point to New, and then select One-way Receive Port.
Name the receive port as ReceiveX12, and then click Receive Locations in the left pane.
In the right pane, click New and provide a name for the receive location, such as ReceiveX12_Location.
Set the transport type to FILE and click Configure.
For the Receive folder text box, specify C:\Messages\ReceiveX12.
For the File mask text box, specify *.txt. This is because the X12 message that we will use in this scenario is in a .txt file. Depending on the file extension of your X12 message, you can set the file mask accordingly.
Click OK.
In the Receive Location Properties dialog box, select BizTalkServerApplication as the receive handler and then select the EdiReceive as the receive pipeline.
Click OK on the Receive Location Properties dialog box and then click OK on the Receive Port Properties dialog box.

You have now created a receive port with the EdiReceive pipeline that will process the X12 message. As part of that, the receive pipeline will convert the X12 message to XML, create the 997 and TA1 acknowledgements, and dump all of these into the message box.

We will now create the send ports that will pick these messages from the message box and route it to designated FILE folders.

Create a FILE send port to send the X12 message

You must create a FILE send port that will subscribe to the X12 message stored in the BizTalk Server message box.

In BizTalk Server Administration console, under BizTalk Application 1, right-click Send Ports, point to New, and then select Static One-way Send Port.
Name the send port as SendX12, select the transport type as FILE, and then click Configure.
For Destination folder, specify C:\Messages\ReceiveProcessedX12.
Specify the file name as %MessageID%.txt so that the file received by Contoso is of .txt format, which is the same format in which the file is being sent from Fabrikam.
Click OK.
In the Send Port Properties dialog box, select BizTalkServerApplication as the send handler and then select the EdiSend as the send pipeline.

Note: You use the EdiSend pipeline because the message in the BizTalk message box is an XML message (after being processed by the EdiReceive pipeline) and that has to be passed to the shared folder in the Contoso setup in an X12 format.
In the left pane, click Filters, and enter a filter expression that will be used by the send port to subscribe to the message. For example, you could use the message type of the X12 message. The message type of the X12 purchase order (850) message is http://schemas.microsoft.com/BizTalk/Edi/X12/2006#X12_00401_850. So, for Property, enter BTS.MessageType; for Operator, enter ==; and for Value enter http://schemas.microsoft.com/BizTalk/Edi/X12/2006#X12_00401_850.

If you are wondering why we simply couldn't use the receive port name again, like we used in Fabrikam's setup, here's the reason. When the EdiReceive pipeline processes the X12 message to create the XML, it sets the receive port name on the message context. That is why when we set the filter for the receive name, the send port subscribes to the message and routes it successfully. However, as part of the message processing, the EdiReceive pipeline also creates the 997 and TA1 acknowledgements. Both these messages are also dumped in the message box and because they were routed by the same receive port, they have the same receive port name set on the message context. So, if you use a filter on the receive port name, it would pick all three messages (the interchange, the 997, and the TA1). We do not want this. We only want this send port to pick the X12 interchange. So, we use a filter on the message type because the message type of all the interchange, 997, and TA1 are unique.
Click OK to close the send port properties dialog box.

Create a FILE send port to send the 997 acknowledgement back to Fabrikam

You must create a FILE send port that will subscribe to the 997 acknowledgement message stored in the BizTalk Server message box.

In BizTalk Server Administration console, under BizTalk Application 1, right-click Send Ports, point to New, and then select Static One-way Send Port.
Name the send port as Send997, select the transport type as FILE, and then click Configure.
For Destination folder, specify \FABKAM-BIZTALK\Messages\Receive997.
Specify the file name as %MessageID%.txt so that the file received by Contoso is of .txt format, which is the same format in which the file is being sent from Fabrikam.
Click OK.
In the Send Port Properties dialog box, select BizTalkServerApplication as the send handler and then select the EdiSend as the send pipeline. You must use the EdiSend pipeline because the 997 message in the message box database is stored in an XML format.
In the left pane, click Filters, and enter a filter expression that will be used by the send port to subscribe to the message. For the 997 acknowledgement, you must use the message type. The message type of the 997 acknowledgement is http://schemas.microsoft.com/Edi/X12#X12_997_Root. So, for Property, enter BTS.MessageType; for Operator, enter ==; and for Value enter http://schemas.microsoft.com/Edi/X12#X12_997_Root.
Click OK to close the send port properties dialog box.

Create a FILE send port to send the TA1 acknowledgement back to Fabrikam

You must create a FILE send port that will subscribe to the TA1 acknowledgement message stored in the BizTalk Server message box.

In BizTalk Server Administration console, under BizTalk Application 1, right-click Send Ports, point to New, and then select Static One-way Send Port.
Name the send port as SendTA1, select the transport type as FILE, and then click Configure.
For Destination folder, specify \FABKAM-BIZTALK\Messages\ReceiveTA1.
Specify the file name as %MessageID%.txt so that the file received by Contoso is of .txt format, which is the same format in which the file is being sent from Fabrikam.
Click OK.
In the Send Port Properties dialog box, select BizTalkServerApplication as the send handler and then select the EdiSend as the send pipeline. You must use the EdiSend pipeline because the TA1 message in the message box database is stored in an XML format.
In the left pane, click Filters, and enter a filter expression that will be used by the send port to subscribe to the message. For the 997 acknowledgement, you must use the message type. The message type of the 997 acknowledgement is http://schemas.microsoft.com/Edi/X12#X12_997_Root. So, for Property, enter BTS.MessageType; for Operator, enter ==; and for Value enter http://schemas.microsoft.com/Edi/X12#X12_997_Root.
Click OK to close the send port properties dialog box.

Create a Party for Fabrikam

In this section, you create a party for Fabrikam in Contoso's BizTalk Server setupand then set the EDI properties on that party.

Right-click the Parties node in the BizTalk Server Administration Console, point to New, and then click Party.
Enter a name for the party. Because Fabrikam is sending the message, let us name the party as Sender.
Click Send Ports, and from the Send ports grid, under the Name column, select the send ports that you created that will send the interchange to a local folder on Contoso and send the acknowledgements to Fabrikam, and then click OK.

Note: BizTalk Server uses this send port association to determine the party for outgoing EDI messages. Once the party is determined, it uses the properties set on the party to process the outgoing interchange and acknowledgements. For more information, see Party Resolution and Schema Determination for Outgoing EDI Messages.
Right-click the party in the Parties pane of the BizTalk Server Administration Console, and then select EDI Properties.
In the General page, click Activate EDI Reporting and click Store transaction set/payload for reporting.

The Activate EDI Reporting option ensures that all interchange-related details for a party are tracked in the status report user interface. The Store transaction set/payload for reporting option ensures that the transaction set details and message content are available to view through the status report interface.
In the left pane, under X12 properties, under Party as Interchange Sender, click X12 Interchange Processing Properties. In this section of the EDI Properties dialog box you will configure the properties using which the BizTalk Server set up at Contoso's end will process the incoming interchange. Remember that the party you created in Contoso's setup represents Fabrikam (that's why you named it Sender), and because the incoming interchange is 'sent' by Fabrikam, the properties are set under party as interchange 'sender'. The easiest way to understand this is by asking yourself these questions: who is the sender? Fabrikam. Where is Fabrikam's party? At Contoso and is called Sender. Where do I configure properties for Fabrikam, when Fabrikam is sending an interchange? In the EDI properties for the Sender property, under "Party as Interchange Sender".

In this interface (Party as Interchange Sender > X12 Interchange Processing Properties) you must enter the values for ISA5 to ISA8. The values you enter here will be used by the receive pipeline to perform party resolution. When receiving an interchange, it matches the values of ISA05 through ISA08 in the message with those in the definition of the party as an interchange sender. If a match happens, BizTalk Server will use the other EDI properties set on the property to process the message. Going by the message (SamplePO.txt), that will be sent by Fabrikam, enter the following values:

Use this To do this

ISA5 ZZ-Mutually Defined

ISA6
THEM

ISA7
ZZ-Mutually Defined

ISA8 US

For more information on how BizTalk Server uses these values to determine the party for incoming EDI messages, see Party Resolution, Schema Discovery, and Authorization for Received EDI Messages.
In the left pane, under X12 properties, under Party as Interchange Sender, click X12 Interchange Processing Properties again, and specify the properties that BizTalk Server will use to discover the schema for processing the incoming interchange. To do so, enter the following values:

Use this To do this

GS2 Enter THEM

ST1
Select 850 - Purchase Order

Target Namespace
Select http://schemas.microsoft.com/BizTalk/EDI/X12/2006

So, how does BizTalk Server use these properties to determine the schema of the incoming interchange. Here's how it happens. BizTalk Server makes a match between the GS2 and ST1 values in the incoming interchange with the GS2 and ST1 you set here, as EDI properties. If a match happens, BizTalk Server determines the target namespace from the grid. If a match does not happen, BizTalk Server uses the default target namespace specified just above the grid.

Once the target namespace is discovered, BizTalk Server determines the schema by taking the target namespace and concatenating it with the encoding type (e.g. X12), first five characters for the version/release (this is picked from the value of GS08, e.g. 00401), and the value of ST01 (e.g. 850). So, the schema name becomes X12_00401_850. The schema name finally is http://schemas.microsoft.com/BizTalk/Edi/X12/2006/X12# X12_00401_850.

For more information, see Party Resolution, Schema Discovery, and Authorization for Received EDI Messages.
Under Party as Interchange Sender, click Ack Generation and Validation Settings, and under the X12 ACK section, select Generate TA1 and Generate 997.

Leave EDI Type and Extended Validation check boxes selected.
In the left pane, under X12 properties, under Party as Interchange Receiver, click ISA Segment Definition. In this section of the EDI Properties dialog box you will configure the properties using which the BizTalk Server set up at Contoso's end will process the acknowledgements to be sent back to Fabrikam. Remember that the party you created in Contoso's setup represents Fabrikam and because the incoming the acknowledgements are received by Fabrikam, the properties are set under party as interchange 'receiver'.

In this interface, you must enter the values for ISA5 to ISA8. The values you enter here will be used by the EdiSend pipeline to create the ISA header for the acknowledgements that will be sent to Fabrikam.

Use this To do this

ISA5 ZZ-Mutually Defined

ISA6 THEM

ISA7 ZZ-Mutually Defined

ISA8 US
Under Party as Interchange Receiver, under Separators section, set Suffix to CR LF.

In the left pane, under X12 properties, under Party as Interchange Receiver, click GS and ST Segment Definition. In this interface you must enter the values that will be used by the EdiSend pipeline to create the GS headers for the outgoing interchange being sent to Contoso.

Use this	To do this
Default	Select the checkbox.
For ST1	Select the message type of your test message. In this scenario, because we are sending a purchase order message, select 850 - Purchase Order.
Version/Release	Specify the EDI version, 00401.
Target Namespace	Select http://schemas.microsoft.com/BizTalk/Edi/X12/2006.
GS1	Verify that the message type of the test message is selected, for example, PO - Purchase Order (850).
GS2	Enter a value for the interchange sender. Let us enter "THEM"
GS3	Enter a value for the interchange receiver. Let us enter "US"
GS4	Select the date format as CCYYMMDD.
GS5	Select the data format as HHMMSS.
GS7	Select X - Accredited Standards Committee X12.
GS8	Verify that the EDI version has been entered, for example, 00401.

In the ACK Processing and Validation Settings page, select the check boxes for EDI type and Extended validation to make sure these validations are performed.
Click OK.

Deploy The Schema for Purchase Order Message

In Visual Studio, create a BizTalk Server project.
Right-click the project, point to Add, and then click Existing Item. Move to the folder that your schema is in <drive>:\Program Files\Microsoft BizTalk Server 2006\XSD_Schema\EDI, and then double-click your schema. If the EDI schemas have not been unzipped into the \XSD_Schema\EDI folders, execute the MicrosoftEdiXSDTemplates.exe file in the \XSD_Schema\EDI folder to unzip the schemas into the default folder.
**
Important**: In this article, we will use the SamplePO.txt test message. So, you must use the X12_00401_850.xsd schema that is shipped in the <drive>:\Program Files\Microsoft BizTalk Server 2006\SDK\EDI Interface Developer Tutorial\ folder. You must not use the X12 850 schema in the <drive>:\Program Files\Microsoft BizTalk Server 2006\XSD_Schema folder.
Set the assembly key file, and then build and deploy the assembly. This would deploy the assembly under the default, BizTalk Application 1, application.
Make sure that BizTalk Application 1 has a reference to BizTalk EDI Application. This is required because all the schemas, pipelines, etc. required to process an EDI message are available under the BizTalk EDI Application. This application is created when you configure EDI/AS2 as part of the BizTalk Server configuration. For instructions on adding a reference, see How to Add a Reference to the BizTalk Server EDI Application.

You are now done with setting up the BizTalk Server environment and all the other requisites at Contoso's end.

Test the Scenario

We are now done with setting up BizTalk Server for EDI messaging both at Fabrikam's and Contoso's end. Let us now run a quick test to verify the setup.

To start with make sure that the all the send and receive ports that we configured are up and running. To do so, log on to the BizTalk Server setup for Fabrikam (on the computer FABKAM-BIZTALK), and on the BizTalk Server Administration console, right-click BizTalk Application 1, and then click Start. This will start all the send and receive ports configured in that application. Also, click on Host Instances under Platform Settings, and verify that the default host instance (BizTalkServerApplication) is running. Perform the same step in Contoso's BizTalk Server setup on the CONTOSO-BIZTALK computer.

On the computer FABKAM-BIZTALK, navigate to C:\Program Files\Microsoft BizTalk Server 2006\SDK\EDI Interface Developer Tutorial\ Open the file SamplePO.txt and have a look at it.

ISA*00* *00* *ZZ*THEM *ZZ*US *991221*1226*U*00401*000000025*0*T*>
GS*PO*THEM*US*19991221*1226*1*X*004010
ST*850*0001
BEG*00*NE*3859199838**950727***IBM
PER*AA*Andrew Carlson*TE*(708) 555-2930
DTM*002*970523
PO1*1*93*BX*145.39**CB*KOW-20392-10
PID*F****Uninterruptible Power System
PER*AA*Camilla Anderson*TE*(708) 555-2011
PO1*2*25*EA*35.68**CB*1093-4927-001
PID*F****High Volume Printer Stand
PER*AA*Miranda Cappelan*TE*(708) 555-1111
PO1*3*4*PC*2002.91**CB*ABX-2001
PID*F****Electronics Cabinet Package (56" High)
CTT*3
SE*14*0001
GE*1*1
IEA*1*000000025

Copy the file SamplePO.txt. Paste this file to C:\Messages\ReceiveX12. Wait for the file to disappear.
Now go back to the computer CONTOSO-BIZTALK and navigate to C:\Messages\ReceiveProcessedX12. Verify whether the folder contains the X12 interchange that Fabrikam sent. The filename would be in the form of <GUID>.txt. Open the file and verify whether the values set for the message like ISA5, ISA6, ISA7, ISA8 are the ones you specified in the Sender party. Notice that the segment terminator is different in the X12 message that is received by Contoso. That is because the segment terminator that is defined as part of the EDI properties for Sender party is tilde (~). If you want to play around with this, change the values of segment terminator, data element separator, etc. and see how the output message changes accordingly. You define these values under ISA Segment Definition section, under Party as Interchange Receiver.
```
ISA*00* *00* *ZZ*THEM *ZZ*US *110206*1821*U*00401*000000069*0*T*:~
GS*PO*THEM*US*20110206*182120*45*X*00401~
ST*850*0045~ 
BEG*00*NE*3859199838**950727***IBM~
PER*AA*Andrew Carlson*TE*(708) 555-2930~
DTM*002*970523~
PO1*1*93*BX*145.39**CB*KOW-20392-10~
PID*F****Uninterruptible Power System~
PER*AA*Camilla Anderson*TE*(708) 555-2011~
PO1*2*25*EA*35.68**CB*1093-4927-001~
PID*F****High Volume Printer Stand~
PER*AA*Miranda Cappelan*TE*(708) 555-1111~
PO1*3*4*PC*2002.91**CB*ABX-2001~
PID*F****Electronics Cabinet Package (56" High)~
CTT*3~
SE*14*0045~
GE*1*45~
IEA*1*000000069~
```

Now go back to computer FABKAM-BIZTALK and navigate to C:\Messages\Receive997. Verify whether the folder contains the 997 acknowledgement sent by Contoso. The 997 acknowledgement would resemble the following.
```
ISA*00* *00* *ZZ*THEM *ZZ*US *110206*1821*U*00401*000000070*0*T*:~
GS*FA*US*THEM*20110206*1821*46*X*00401~
ST*997*0046~
AK1*PO*28~
AK9*A*1*1*1~
SE*4*0046~
GE*1*46~
IEA*1*000000070~
```

Similarly, navigate to C:\Messages\ReceiveTA1 and verify whether the folder contains the TA1 acknowledgement. The TA1 acknowledgement would resemble the following
```
ISA*00* *00* *ZZ*THEM *ZZ*US *110206*1821*U*00401*000000071*0*T*:~
TA1*000000028*110206*1821*A*000~
IEA*0*000000071~
```

If the message contents are as you expected, you have successfully transferred an EDI X12 message between two trading partners using BizTalk Server.

Understand the Message Flow

Let us now understand how the message flow happens:

When you drop the interchange to C:\Messages\ReceiveX12 folder on FABKAM-BIZTALK, the ReceiveX12_Location receive location with the EdiReceive pipeline consumes it, converts it to XML, and stores it in the BizTalk Server message box database in Fabrikam's set up.
Once the interchange is in the message box database, the SendX12 send port in Fabrikam's setup picks it up based on the filters we set on that. The filters we had set were for the receive port name and message type. Because the SendX12 send port uses an EdiSend pipeline, it converts the message back from XML to X12. Also, because the SendX12 send port is associated with the Receiver party created in Fabrikam's setup, the EdiSend pipeline uses the property settings on the Receiver party (under Party as Interchange Receiver) to create the X12 message. The send port transfers the message to the shared folder at Contoso's end, \CONTOSO-BIZTALK\Messages\ReceiveX12. The message is now transferred to Contoso but is yet to be processed by Contoso's BizTalk Server setup. That is where the message will be validated and acknowledgements will be generated.
Now at Contoso's end, the ReceiveX12_Location receive location with the EdiReceive pipeline consumes the message from the folder where it was copied to by Fabrikam. The EdiReceive pipeline does the party resolution based on the values of ISA5, ISA6, ISA7, and ISA8 on the interchange with those specified in the party created at Contoso's end. Because the values for ISA5, ISA6, ISA7, and ISA8 set on the Sender party (under Party as Interchange Sender) match with that of the message, the EdiReceive pipeline uses the settings on the Sender party to process the message and converts it to XML. Because the Sender party settings also indicate to generate a 997 and TA1 acknowledgements, the EdiReceive pipeline generates the 997 and TA1 acknowledgements. At this stage, the XML message, the 997 acknowledgement in XML, and the TA1 acknowledgement in XML are all stored in the BizTalk Server message box database of Contoso.

Note: This is where the interchange gets in to the BizTalk Server setup at Contoso's end. What this also means is that if you disable this receive location, the message would be available in the same folder where Fabrikam copied it, which C:\Messages\ReceiveX12 on CONTOSO-BIZTALK. Because the receive location is enabled, the message is consumed as soon it is copied over from Fabrikam. So, if you just want to check the message after it has arrived from Fabrikam's BizTalk Server setup, disable the receive location. Once you have checked the message content, enable the receive location, and the message will be processed further by Contoso's BizTalk Server setup.
Now the three send ports that we configured in Contoso's BizTalk Server setup will pick the messages they have subscribed to, convert them back to X12 format (because they use an EdiSend pipeline), and copy them over to the respective output folders.
- The SendX12 send port will copy the X12 message to C:\Messages\ReceiveProcessedX12 folder on CONTOSO-BIZTALK. This is where you get the output message at Contoso's end.
- The Send997 send port will copy the 997 acknowledgement to Fabrikam's setup at the shared location \FABKAM-BIZTALK\Messages\Receive997.
- The SendTA1 send port will copy the TA1 acknowledgement to Fabrikam's setup at the shared location \FABKAM-BIZTALK\Messages\ReceiveTA1.

Because all these send ports are associated with the Sender party, they will use the settings specified on the party (under Party as Interchange Receiver) to create the X12 and acknowledgement message before sending them back to Fabrikam.

The following illustration presents a graphical representation of the flow for ease of understanding.

What Next? Extend this Scenario

You now have a elaborate two-machine setup now but we can do more. To start with, you can change the values in the EDI properties for the party and see how the output message changes accordingly. That would give you a better understanding of how this works. However, there's one scenario that you can add on to the existing setup.

In the scenario we just tested, the 997 and TA1 acknowledgements are received on a shared folder on the Fabrikam side of the setup. These acknowledgements are simply copied over to the Fabrikam side and are never processed by the BizTalk Server at Fabrikam's side. So, in effect, this will be termed as an "out of band" receipt of the acknowledgements. So, you can extend the current scenario to have both 997 and TA1 acknowledgements processed by the BizTalk Server setup at the Fabrikam side. This is how you should go about doing this:

Set up a receive port with EdiReceive pipeline on the Fabrikam side that will consume the 997 acknowledgement from C:\Messages\Receive997 and stores it in the message box database. You should then create a send port with EdiSend pipeline that will subscribe to the 997 acknowledgement and then route it out to file folder. Make sure you set a filter on the send port to only pick 997 messages.
Similarly, set up a receive port with EdiReceive pipeline on the Fabrikam side that will consume the TA1 acknowledgement from C:\Messages\ReceiveTA1 and stores it in the message box database. You should then create a send port with EdiSend pipeline that will subscribe to the TA1 acknowledgement and then route it out to a file folder. Make sure you set a filter on the send port to only pick TA1 messages.
Once you have done this, in the EDI party properties for Receiver party (created on the Fabrikam side), under Party as Interchange Receiver, under Ack Processing and Validation Settings, select the check box for Functional Ack (Integrated with ACK Reporting). When you select this check box, the status reporting of the acknowledgements is integrated with the status reporting of the interchange.
You must also associate the two send ports that you just created with the party (Receiver) on Fabrikam side. When you do this, the EdiSend pipeline in the send ports will use the properties set on the party (for Party as Interchange Receiver) to construct the ISA and GS headers.

Once you have done this, you will have a setup where every message transfer (interchange as well as acknowledgements) is processed through BizTalk Server.

Common Errors and Troubleshooting Steps

For all troubleshooting information related to EDI, see Troubleshooting EDI and AS2 Solutions.

If you want to read and print this article using Microsoft Word, you can download it from my blog post here. The document is part of the attachment EDI-Send-Receive-Scenario.zip. The zip also contains the MSIs for the BizTalk Server applications for both the machines. You can importing the MSI on different machines to set up the BizTalk Server environment for Fabrikam and Contoso. Importing the MSI will create/import the ports, parties, schemas, etc. used in this scenario. For instructions on how to import an MSI, see How to Import a BizTalk Application.

After importing the applications you would still need to go and create any of the file locations that will be required for the FILE ports. However, I would strongly discourage you from using the MSIs. It would be a completely different learning experience if you build your application ground-up using the instructions in this article.

Watch the Video

You can also watch a 3-video series explaining the concepts and procedures described in this topic. The video series is available here.

Share via

BizTalk Server EDI Scenario: Send an X12 Message and Receive an Acknowledgement

Acknowledgements

Contents

Overview

EDI Support in BizTalk Server