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

Cumulative update information

This issue was first fixed in the following cumulative update of BizTalk Server:

• Cumulative Update 1 (CU1) for BizTalk Server 2013 R2

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 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.