BTAHL7 - end-to-end integration across Health Care applications

Microsoft BizTalk Accelerator for HL7 allows you to create applications to integrate your health care computer systems.  Very often, the out of the box schemas will not meet your needs.  An HL7 schema can be updated like any other BizTalk schema with the understanding of the relationship of your common/base schemas:  datatypes_<HL7 version>.xsd, segments_<HL7 version>.xsd and tablevalues_<HL7 version>.xsd

The most common situations that I have encountered are custom message types and namespaces.  The document below outlines the steps to add a custom message type and use a custom namespace.  In the scenario below, the sending application is HIS (value of MSH.3) and the receiving application is NEWSYS (value of MSH.5).

1. Add a solution to contain the Common schema, ACK, and message structure schema for the version you are processing. a) Add a New Empty BTAHL7 Project/Solution by going to File>New>Project, and name the solution HIS_CustomSchema. b) In the Location box, enter C:\BizTalk HL7 Dev or a location of your choice. c) In the Solution Name box, select Create New Solution, name it CustomSchema and then click the Create New Directory box. d) Right-click the solution, click Add a New Project, add the BTAHL7V231Common project, and then name it HIS_231CommonProject. e) Right-click the solution, click Add a New Project, add the BTAHL7V2XCommon project, and then name it HIS_ACK_Schema. f) Add a reference to the project HIS_CustomSchema i) In Solution Explorer, select the HIS_CustomSchema project. ii) Right-click References, and then select Add a Reference. iii) In the References dialog box, click Projects tab, and then select HIS_231CommonProject. iv) Click OK to close the dialog box. g) Right-click the HIS_CustomSchema project, and then add the ADT_A01_231_GLO-DEF.xsd schema to it by selecting Add New Item>BTAHL7 Schema and selecting the proper schema from the dialog box. 2) Change the namespaces in all of the following schema. a) Select the Tablevalues_231.xsd schema in the HIS_V231Common project. b) Right-click it, and then select Open With. c) In the Open With dialog box, select Notepad to open the schema for editing. or d) Select Add, click Browse next to the Program entry, browse to C:\WINDOWS\Notepad.exe, and then click Open. e) Name the entry Notepad and click OK. f) In Notepad, select Edit>Replace, find all references to microsoft.com/HealthCare and replace them with HIS. Save the file and close. g) Repeat these steps with the following schema in this exact order: i) datatypes_231.xsd ii) segments_231.xsd iii) ADT_A01_231_GLO_DEF.xsd 3) Based on business needs, make the needed schema changes. a) Double-click the Tablevalues_231.xsd schema in the HIS_231Common Project to open it. b) Select Table4 in the schema, and then open its Properties window. c) Select the browse ellipsis in the Enumeration setting. d) Add a ZZ to the table. To save your change, click OK. 4) If you need to create a new custom message type, make the following changes along with step 10. a) Select and open ADT_A01_231_GLO_DEF.xsd. In the properties window, modify type name and file name. i.e. ADX_A99_231_GLO_DEF.xsd. b) On the schema editor, click root node ADT_A01_231_GLO_DEF.xsd. On the properties window modify RootNode TypeName and Node Name. i.e. ADX_A99_231_GLO_DEF.xsd. 5) Assign a Strong Key file to the project and deploy. a) In Solution Explorer, right-click the HIS_231Common project, and then click Properties. b) In left pane of the HIS_231Common Project Property Pages page, click Assembly. c) In the right pane, scroll down to the Strong name section, click the field to the right of Assembly Key File, and then click the ellipses (.). d) In the Assembly Key File dialog box, navigate to the location of strong name key, and then click Open. e) To save changes, click OK. f) Repeat these steps for every other project in the solution. 6) Build and deploy the project. It is important to build the project with the Common schema before the project with the Message Structure schema because the Message Structure schema references the Common schema. a) In the Solution Explorer window, right click the HIS_231Common Project project, and then select Build. b) Right-click the HIS_231Common Project, and then select Deploy. c) Repeat these steps for the HIS_CustomSchema project and the HIS_ACK_Schema project. 7) Add party definitions for the sending and receiving parties in the MSH.3 and MSH.5 fields. a) In BizTalk Explorer, right-click Parties, and then select Add Party. b) In the Add Party dialog box, type HIS as the name. c) To close, click OK. d) Repeat these steps to add another party definition named NEWSYS. 8) Configure the incoming party definition: a) Open the HL7 Configuration Explorer from Start>Programs>Microsoft BizTalk Accelerator for HL7 2.0>BTAHL7 Configuration Explorer. b) In the Parties navigation panel, select HIS, and then navigate to the validation tab. c) Add the custom namespace https://HIS/HL7/2X in the Schema Namespace text box and click Save. d) In the BTAHL7 Configuration Explorer, select the Acknowledgment tab. For Acknowledgment type, select OriginalMode and click Save. 9) Configure the destination party definition: a) Open the HL7 Configuration Explorer from Start>Programs>Microsoft BizTalk Accelerator for HL7 2.0>BTAHL7 Configuration Explorer. b) In the Parties navigation panel, select NEWSYS, and then navigate to the validation tab. c) Add the custom namespace https://HIS/HL7/2X in the Schema Namespace text box and click Save. 10) If you are using custom message type, you must also follow the steps below. If you do not, you get an error similar to "message type not found or event code not supported". a) The steps outlined below can be found in the product documentation, section Developing > Programming Guide > Using HL7 2.X Schemas > Extending HL7 2.X Schemas and Z Object b) In these steps, you are adding the custom message type values to Table3, 76 and 354. This is related to step 4 in which the Table 3 holds Trigger Event value A99. Table 76 holds Message Structure value ADX_A99. Table 354 holds Message Type value ADX. If any of those values already exists, you do not have to add it twice. For example trigger event can be A01 instead of A99 and you wouldn't need to update table 3 only the rest of the tables. i) In Solution Explorer, open the MSH_25_GLO_DEF schema, and then click Open. ii) Right-click the MSH node, point to Insert Schema Node, and then click Child Field Element. Visual Studio adds a field node to MSH, called Field. Click ENTER. iii) In the Properties window, click the Data Type node, then from the drop-down list, select the table to which you want to add the enumeration value. <<<The name of the data type node is Table3, Table 76 or Table354 appropriately. Otherwise, you will get an error similar to "the enumeration constraining facet is invalid. The enumeration constraint failed". >>> iv) In the Enumeration Editor, add the new value to the list of existing values, and then click OK. Table 3 - add A99, Table 76 - add ADX_A99 and Table 354 - add ADX. v) When you add a value to the enumeration for any node, such as the Field node, you add that value globally for all objects that use that table. As a result, you can now delete the Field node, and the value will still be present for the table. You can verify this by scrolling in the right pane of BizTalk Editor to the table, and verifying that the value that you added is present. Right-click the Field node in BizTalk Editor, click Delecte and then click Yes. 11) Create the necessary receive port and send ports to send the HL7 message through BizTalk Server. 12) This step is dependent on Step 7. Once you have created the send ports and if you are also creating a custom namespace as well as a custom schema, you must add the send port name to the party. Example, Receiving Party/MSH3 = HIS has custom namespace https://HIS/HL7/2X and send port MySendPort_SP a) In BizTalk Explorer, right-click on Party Properties, select Send Ports, and then select a Send Port from the dropdown list, MySendPort_SP. b) Repeat these steps to the other party/ports (if using multiple ports/parties) by selecting a unique Send Port from the dropdown list. 13) Restart the BizTalk service. 14) Test your solution by passing a sample instance of your custom message.