How to apply maps and custom ACK codes to ACK messages in HL7 for BizTalk Server 2013 R2

Symptoms

Issue 1

Consider the following scenario:

  • You're running Microsoft BizTalk 2013 R2 Accelerator for HL7 (BTAHL7).
  • You're using an MLLP receive adapter and an HL7 receive pipeline in a two-way receive port.
  • You set the Use Direct Synchronous HL7 ACK option to True in MLLP Transport Properties.
  • You create an outbound map on this two-way receive port to transform the ACK before it is sent out.

In this scenario, the outbound map is not applied to the HL7 ACK, and therefore the ACK is not transformed.

Issue 2

MLLP send port checks the ACK code in the ACK (the MSA.1_AcknowledgmentCode field of MSA segment) that's returned by the downstream system and compares it with the acceptable ACK codes that are set in the MLLP send port configuration properties. The ACK codes that are currently supported by MLLP send port are AA, CA, AE, CE, AR, and CR. You can select all ACK codes or a combination of them. For example, the following codes are all valid:

AA and CA
AA, CA, AE, and CE
AA, CA, AR, and CR

However, you cannot enter any additional acceptable ACK codes.

After you apply this hotfix, a new acceptable ACK code that's named Custom is added in the Acceptable ACK Codes list. Additionally, a new text box is added in which to enter the acceptable custom ACK codes.







Note
s
  • The custom codes should be separated by a comma (,). For example: AE,CE,AR,CR,XX,ZZ
  • If one of the standard combinations (a non-custom option) is selected, you do not have to enter any values in the Acceptable Custom ACK Codes property.
  • To make sure that the pipeline validation succeeds for the custom ACK codes, you must add the required custom ACK codes to the corresponding ACK schema.
  • You can use the BizTalk Tracking feature (by enabling tracking) to track the message by using the MessageID that is logged in the event log when the message is retried or suspended.

Resolution

Cumulative update information

This issue was first fixed in the following cumulative update of BizTalk Server:
Make sure that you deploy the required Outbound Map DLL file and that you install this DLL file in the global assembly cache (GAC):
  1. OutboundMap assembly name

    This requires the full name of the assembly that hosts the outbound map. You can find this information in the properties of the map in the BizTalk Server Admin Console. Here you'll find the information for the assembly and the complete OutboundMap name that's required in the next step.

    For example: Outbound, Version=1.0.0.0, Culture=neutral, PublicKeyToken=83f92b3673c9005d
  2. OutboundMap name

    This requires the full map name, including the namespace. You can find this information in the properties of the *.btm file (Namespace.TypeName).

    For example: Outbound.Map1
Note These properties are applied only if Direct Synchronous HL7 ACK is set to True.

If you don't need the HL7 Disassembler (DASM) in the HL7 Receive Pipeline to automatically generate HL7 acknowledgements (for example the ACK that's returned by some downstream system will be handed over to the upstream system), turn off the Route ACK to send pipeline on Request Receive port option for the source party, and set Use Direct Synchronous HL7 ACK to False. Then, use the outbound map option that's provided in the receive port.

For Issue 1

This new feature applies to Receive Port/Location only. Currently, any BizTalk receive port has an Inbound Maps property. After this hotfix is installed, there is an additional property available in the receive location to apply a map to an HL7 ACK. This additional property lets you apply a map to a two-way receive location that has the Use Direct Synchronous HL7 ACK set to (=) True. The only purpose of this hotfix is to allow the user to specify a map for an ACK when Use Direct Synchronous HL7 ACK is set to (=) True.

After you install the hotfix, you will see two additional properties in the MLLP receive location configuration window. The default setting for the two properties is blank, and they must be populated and Use Direct Synchronous HL7 ACK must be set to (=) True.



To set the two properties, follow these steps:
  1. OutboundMap Assembly Name property requires the full name of the assembly in which the outbound map is hosted, as in the following example:

    Outbound, Version=1.0.0.0, Culture=neutral, PublicKeyToken=83f92b3673c9005d
    The assembly must be previously cached by the Global Assembly. Otherwise, the transformation will fail.
  2. OutboundMap Name property requires the full name of the map including namespace.

One shortcoming of this new functionality: the HL7 ACK is not tracked. If you must track the ACK, you must also set the Inbound Maps property in the BizTalk receive port. Technically, you will be applying the map to the ACK that was put in the Message Box and the ACK that was returned to the upstream system. Both should be identical because both will have the same map applied. The following screen shot is included for clarification and is necessary only if the ACK must be tracked.



Note The Use Direct Synchronous HL7 ACK option improves inbound message processing performance. This is done by sending the ACK back to the upstream system as soon as the message is deposited to the message box. This setting improves the performance if the following conditions are true:
  • The receive port is a two-way receive port, and the Use Direct Synchronous HL7 ACK option is set to True in the MLLP Receive port configuration.
  • BizTalk HL7 DASM is used to generate the ACK. The DASM component must be used either as included in the default BTAHL72XReceivePipeline or by using the native BTAHL7.HL72fDasm component in a custom pipeline.
  • The Route ACK to Send pipeline on request-response receive port setting of the Source party must be in the HL7 Configuration Explorer, and the Acknowledgement Type must be set to a value other than None.

For Issue 2

The new feature applies to send ports only. After you install the hotfix, the behavior will be based on the Acceptable ACK code that you select in the drop-down list instead of the code that's provided by the downstream system.

The MLLP Send port checks the ACK code in the ACK (MSA.1_AcknowledgmentCode field of MSA segment) that is returned by the downstream system and compares it with the Acceptable ACK codes that are set in the MLLP send port configuration properties. Current acceptable ACK codes that are supported by MLLP Send port include AA, CA, AE, CE, AR and CR. You can select all ACK codes or a combination of them (AA and CA), (AA, CA, AE and CE), (AA, CA, AR and CR) as valid. But there is no option to enter an acceptable ACK code combination.

An additional Acceptable ACK codes value that's named "Custom" is added in the drop-down list in the Acceptable ACK Codes property. All previous combinations remain and are applied as they were before the new feature was added.





After CUSTOM is selected, you must also enter the new values in the Acceptable Custom ACK Codes property. These new ACK values must each be separated by a comma (,).

After you install the hotfix, the behavior will depend on the Acceptable ACK Codes setting that's selected. If the ACK code that's returned matches the selected acceptable code, processing occurs successfully. It will retry for standard ACK codes and suspend for any ACK code that's not listed (which will make it a nonstandard or a non-custom ACK code).

The following table represents this scenario. A written interpretation follows the table.



For AA and CA, message processing always succeeds regardless of any acceptable ACK codes setting that's selected. Here's more information about Acceptable ACK Codes settings:
  • AA, CA: Retries AE, CE, AR, CR and suspends any other.
  • AA, CA, AE, CE: Accepted and successful: AA, CA, AE, CE and retries AR and CR. Suspends any other.
  • AA, CA, AR, CR: Accepted and successful: AA, CA, AR, CR and retries AE and CE. Suspends any other.
  • AA, CA, AR, CR, AE, CE: Accepted and successful: AA, CA, AR, CR, AE, CE and no other is returned. ACK is retried and message suspended.
  • Custom (values are entered and separated by a comma). Example: AA,AE,Foo,ZZ,ZZZ). Accepted and successful: AA, CA, AE plus any other entered custom ACK such as Foo, ZZ, and ZZZ in this case. Retries CE, AR.
  • Any ACK code that's not specified in Acceptable Custom ACK Codes is not retried and is suspended.

When a standard ACK is not entered under Acceptable ACK Codes, an error that resembles the following is returned:  

The adapter failed to transmit message going to send port "<SendPortName>" with URL "127.0.0.1:33000". It will be retransmitted after the retry interval specified for this Send Port. Details:"Message with MessageID: <MessageID>, received with acknowledgement type: Error and with ACK code: CE.

The out-of-the-box ACK schema must be modified by adding to the existing list of standard ACKs (AA,AE,AR,CA,CE,CR). Any additional acceptable custom ACKs (XX,ZZ, for example) must be added to the MSA.1_AcknowledgementCode field of the ACK schema. If the additional custom ACKs are not added to the schema, the pipeline validation fails with a “Table value not found” error.



More information

Prerequisites to install the software update

To apply this hotfix, you must have the following software installed:
  • Microsoft BizTalk Server 2013 R2
  • Microsoft BizTalk 2013 R2 Accelerator for HL7

Restart requirements

You do not have to restart the computer after you apply this hotfix. However, we recommend that you close and reopen the BizTalk Admin Console after hotfix installation.

File information

The English version of this hotfix has the file attributes (or later file attributes) that are listed in the following table. The dates and times for these files are listed in Coordinated Universal Time (UTC). When you view the file information, it is converted to local time. To find the difference between UTC and local time, use the Time Zone tab in the Date and Time item in Control Panel.
File nameFile versionFile sizeDateTimePlatform
Microsoft.Solutions.BTAHL7.HL72fDasm.dll3.10.325.2107520

09-Feb-2015
22:52x86
Microsoft.Solutions.BTAHL7.PipelineCommon.dll3.10.325.295232

09-Feb-2015
22:52x86
Microsoft.Solutions.BTAHL7.Shared.dll3.10.325.299328

09-Feb-2015
22:52x86
Microsoft.Solutions.BTAHL7.MLLP.dll3.10.325.2128000

09-Feb-2015
22:52x86
Microsoft.Solutions.BTAHL7.HL7AckHelper.dll3.10.325.229696

09-Feb-2015
22:52x86
Status
Microsoft has confirmed that this is a problem in the Microsoft products that are listed in the "Applies to" section.
References
For more information about BizTalk Server hotfixes, see Information about BizTalk Server hotfixes.

Learn about the standard terminology that's used to describe Microsoft software updates.

Third-party information disclaimer

The third-party products that this article discusses are manufactured by companies that are independent of Microsoft. Microsoft makes no warranty, implied or otherwise, about the performance or reliability of these products.

Properties

Article ID: 3026048 - Last Review: 07/02/2015 23:48:00 - Revision: 5.0

Microsoft BizTalk Server 2013 R2 Branch, Microsoft BizTalk Server 2013 R2 Developer, Microsoft BizTalk Server 2013 R2 Enterprise, Microsoft BizTalk Server 2013 R2 Standard

  • kbsurveynew kbfix kbqfe kbexpertiseadvanced kbbts KB3026048
Feedback