Documentation

Search

Generate EDI acknowledgments

Article author
Admin
  • Updated

What are EDI acknowledgments?

An EDI acknowledgment serves as a receipt, to acknowledge that an EDI transaction, or a group of transactions, was received by the remote party. It is pivotal that the communication between business partners is reliable and audit-able, and that the exact status of the transactions is known to both parties at any moment.

Without specific acknowledgment of receipt and acceptance, subsequent processing of the transactions is usually delayed until their status is confirmed. By incorporating EDI acknowledgments into your business process, most or all status inquiries can be eliminated and trading partners are automatically notified that their transactions have indeed been received and then confirmed, rejected, or partially accepted.

 

X12 and EDIFACT acknowledgments

EDI Tools for .NET supports acknowledgments for the X12 and EDIFACT EDI standards and allows developers to programmatically read EDI acknowledgments, and to automatically generate EDI acknowledgments.

Reading EDI acknowledgments is done in the same way as all other EDI transactions, using either the X12Reader or the EdifactReader, as explained in the Parse EDI files article. Generating EDI acknowledgments is covered in this article.

EDI Tools for .NET can generate the following acknowledgments:

  • X12 997
  • X12 999
  • X12 TA1
  • EDIFACT CONTRL (both functional and technical)

EDI Tools for .NET supports the following EDI error codes (each table indicates which error codes specified by the X12 specification are supported in EDI Tools for .NET and which are not supported):

 

EDI acknowledgment templates

EDI Tools for .NET uses C# classes, called EDI templates, to represent EDI transactions. All of the supported EDI acknowledgments are also represented with EDI templates, however, the templates are built into the product and are not available separately as C# files.

To access the EDI template for each acknowledgment type use the following EDI templates:

 

Generate EDI acks with AckMan

AckMan for X12 and AckMan for EDIFACT are components in EDI Tools for .NET that can be used to produce technical, functional, and implementation (X12 only) acknowledgments.

AckMan is used in conjunction with EDI Reader when the reader is in streaming mode only. On every iteration of the reader, the current item is "published" into AckMan. All items are validated inside AckMan by calling the IsValid() method asynchronously.

Acknowledgments are generated as standard .NET Events, upon reaching the end of a group GE (X12) or the end of the interchange UNZ (EDIFACT). All acknowledgment POCOs are instances of one of the EDI acknowledgment templates described in the previous section.

Generating acknowledgments as .NET events allows the consumer application to process the acknowledgments asynchronously, without interrupting the reading of the EDI file.

AckMan can be used to generate EDI acknowledgment when EDI Reader is in splitting mode. The consuming application needs to ensure that the parts of the EDI transaction are published into AckMan in the same sequence that was produced by the EDI Reader.

  •  using(var ackMan = new Plugins.Acknowledgments.X12.AckMan(settings))
 {
     using (var ediReader = new X12Reader(edi, "EdiFabric.Sdk.X12"))
     {
	  while (ediReader.Read())
		ackMan.Publish(ediReader.Item);
     }
 }

  •  using(var ackMan = new Plugins.Acknowledgments.Edifact.AckMan(settings))
 {
     using (var ediReader = new EdifactReader(edi, "EdiFabric.Sdk.Edifact"))
     {
	  while (ediReader.Read())
		ackMan.Publish(ediReader.Item);
     }
 }

AckMan implements IDisposable and needs to be disposed of. This is to ensure that a final validation is always executed even for EDI documents that are missing closing trailers.

When using AckMan all processing happens within the handlers in AckSettings - all acknowledgments arrive in the AckHandler and all messages arrive in the MessageHandler together with their validation context and interchange\group headers. The reader is only used to read the stream and publish the items to AckMan.

The benefit of utilizing AckMan is not just its ability to generate acknowledgments, but to also provide the messages from the EDI document in the context of their respective groups and interchanges, and to indicate their conformance according to their rules.

Examples in GitHub:

 

Configure AckMan with AckSettings

The first step in generating acknowledgments is to configure AckMan. The only parameter that AckMan takes is AckSettings which provides all configuration options.

Common ack settings

  • AckHandler - the acknowledgment handler. It is raised after reaching the end of each group as the EDI document is read along. This is where the acknowledgments will be raised and it's the same handler for all acknowledgment types.
  • MessageHandler - the message handler. It is raised after reaching the end of each message as the EDI document is read along. The event arguments contain the interchange and group headers and whether the message is valid or duplicated.
  • MessageControlNumber - this is the initial value for EDI transaction sets control numbers. By default, it assigns consecutive numbers starting from 1. This property is incremented every time a new acknowledgment is generated.
  • GenerateForValidMessages - indicates if AK2 or UCM segment groups should be generated only if the message is rejected or always.
  • TechnicalAck - controls the generation of technical acknowledgment. You can enforce or suppress technical acknowledgments. By default, it generates it according to the ISA14 flag (for X12) or UNB9 flag (for EDIFACT).
  • TransactionSetDuplicates - indicates whether to detect duplicate messages within the same group.
  • GroupDuplicates - indicates whether to detect duplicate groups within the same interchange.
  • InterchangeDuplicates- a delegate to detect duplicate interchanges.
  • ValidationSettings - the validation settings to be applied when validating EDI transactions.

X12 only ack settings

  • Ak901ShouldBeP - indicates the partially accepted code to be either E or P. The default is E.
  • AckVersion - the version of the acknowledgment. This can be X12_997 (004010 compliant), Hipaa_997 (005010 compliant) or Hipaa_999 (005010 compliant). The default is X12_997.
  • IncludeLoopId - indicates if Loop ID's should be included in IK3 and AK3.
  • Ta1AfterTrailer - to enforce technical acknowledgment TA1 to be raised after the IEA was read, even if ISA was invalid.
  •  var settings = new AckSettings
 {
	AckHandler = (s, a) =>
	{
		if (a.Message.Name == "TA1")
		{
			// a.AckInterchange is TA1 
		}

		if (a.Message.Name == "999")
		{
		   var ack = BuildAck(a.InterchangeHeader, a.GroupHeader,
                        a.Message, AckVersion.Hipaa_999);
		   Debug.Write(ack);
		}
	},
	MessageHandler = (s, a) =>
	{
		if (!a.ErrorContext.HasErrors)
		{
			// do something with the message a.Message
		}
	},
  Ak901ShouldBeP = true,
  AckVersion = AckVersion.Hipaa_999,
  GenerateForValidMessages = true,
  TransactionSetDuplicates = true,
  GroupDuplicates = true,
  InterchangeDuplicates = a => a == "810000263",
  MessageControlNumber = 300,
  TechnicalAck = TechnicalAck.Suppress
 };

  •  var settings = new AckSettings
 {
	AckHandler = (s, a) =>
	{
		if (a.Message.Name == "CONTRL" && a.AckType == AckType.Technical)
		{
			// a.AckInterchange is technical acknowledgment 
		}

		if (a.Message.Name == "CONTRL" && a.AckType == AckType.Functional)
		{
		   var ack = BuildAck(a.InterchangeHeader, a.GroupHeader,
                        a.Message);
		   Debug.Write(ack);
		}
	},
	MessageHandler = (s, a) =>
	{
		if (!a.ErrorContext.HasErrors)
		{
			// do something with the message a.Message
		}
	},
  GenerateForValidMessages = true,
  TransactionSetDuplicates = true,
  GroupDuplicates = true,
  InterchangeDuplicates = a => a == "810000263",
  MessageControlNumber = 300,
  TechnicalAck = TechnicalAck.Suppress
 };

By default, data elements with alpha or alphanumeric types are not validated. To enable this type of validation, configure the ValidationSettings property. Read more about validating X12 data elements and validating EDIFACT data elements.

 

The EDI ack is in AckHandler

The acknowledgment handler AckHandler provides the generated ack as a C# POCO (see the references above).

AckMan does support the CTX segment (segment context only) for all DataElementContexts marked with IsSituational = true.

The AckHandler also provides the original interchange header (ISA, UNB) and group header (GS, UNG) which can be used for producing the final acknowledgment. The values for sender ID and sender qualifier are swapped with the values for receiver ID and receiver qualifier in both ISA and GS (UNB and UNG).

  • AckHandler = (s, a) =>
{
    if (a.Message.Name == "TA1")
    {
        // a.AckInterchange is TA1 
    }

    if (a.Message.Name == "999")
    {
        // a.AckInterchange is 999
    }
}

  • AckHandler = (s, a) =>
{
    if (a.Message.Name == "CONTRL" && a.AckType == AckType.Technical)
    {
	// a.AckInterchange is technical acknowledgment 
    }

    if (a.Message.Name == "CONTRL" && a.AckType == AckType.Functional)
    {
	// a.AckInterchange is functional acknowledgment 
    }
}

 

How to detect duplicates

Interchanges can be identified as duplicates by their unique identifier comprised of the three values for Sender code, Receiver code, and Control number.

For example the unique identifier of the following interchange header:

ISA*00* *00* *ZZ*FROM *ZZ*TO *071214*1406*U*00204*810000263*0*T*>~

is Sender code: FROM, Receiver code: TO and Control number:810000263

In order to be able to detect duplicate interchanges, the unique identifiers need to be preserved externally (in a database for example). An external delegate can be configured in AckMan, which takes the unique identifier as a string and returns an indicator if a duplicate was found.

Func<string, bool> InterchangeDuplicates

Interchange unique numbers should be considered valid only for a certain amount of time that was agreed with the trading partner. After that time the same control numbers can be assigned again and will not be considered duplicates.

Duplicate groups within an interchange are identified by the group control number GS06. Duplicate messages within a group are identified by the transaction control number ST02.

 

FunctionalGroupVersion error code

FunctionalGroupVersion error code is:

  • In X12 999 or 997, in AK905 with code 2
  • In EDIFACT CONTRL in UCM with code 17

By default, the FunctionalGroupVersion error code isn't generated. You can configure AckMan to include it in the final acknowledgment by raising GroupNotSupportedException in the type resolution factory of EDI Reader:

Share this:

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.