Home

Working with MWB Segment Libraries

 

Using and Associating Libraries with Segments

The Messaging Workbench actually employs 3 different types of library files: Segment Libraries also referred to as Conformance Libraries or just libraries are the ones we’ll be concerned with here. The other 2 are the Data Type libraries and the Table Library, which will be discussed elsewhere. 

The Segment libraries (referred to simply as libraries or library from now on) are collections of segment definitions that are derived from message specifications. Message specifications are complete in that they do not need to refer to library files outside of themselves. Libraries come into play is when you create a new message specification from scratch, or add a new segment to and existing specification. When a new segment is added to a specification, the MWB message compiler looks for the segment definition in the currently active conformance library, and adds it to the message specification. 

Libraries are used when a Profile Consistency Check is done.  The library active for a particular segment is used as the standard against which that segment is checked.

Libraries are additive, so for any given message specification you can define one or more associated libraries. When a new segment is introduced into a specification, the MWB message compiler will search through the list of libraries until it encounters a library in the list with a definition for that segment. You can view the currently active list of libraries using the 'Show Lib/Datatype Libraries in use' option on the Maint/Libraries menu.  It is important to realize that the first segment definition encountered will be compiled into the specification and that library definition remains associated with that segment.  So for example if your library list contained 2 libraries each of which contained a PID definition, then only the first PID definition encountered would be used. The list of libraries and their order for a specification can easily be arranged to suit your needs in the Select Conformance Spec option available as a button on the tool bar, or under the Maint/Libraries menu.

The primary intent of this feature is to allow developers to keep custom library definitions separate from standard libraries, but to bring them together as circumstances require. So for example, you may work primarily with the HL7 2.3.1 library, but you need to incorporate your own custom Z segments into a particular specification. In this instance, you might have a library list consisting of 2 libraries, one for the standard and one for the corporate Z segment library. There is however no requirement that standard and custom segments be sequestered into different library files. You may elect to put all of your segment definitions into one library file. We’ll describe how to do this in library maintenance below. 

The library list that you select by the way is saved as part of the application start-up parameters, so if you work with the same library or list of libraries most of the time, you’ll seldom have use the Select Conformance Files option. This convenience however has a downside in that people often forget to select the appropriate library for a given specification. For example, if as above you ordinarily work with the HL7 2.3.1 library, but for a particular interface you’re required to conform to HL7 2.2, you must remember to select the appropriate Hl7 2.2 library before you compile your new message specification, or add segments to an existing one.

 Changing the Library Associated with a Segment

You may want to change library associated with a segment after a segment has been compiled into a message specification.  Here's how you can:

 

1.      With the message specification loaded, right click in the box containing the Message Tree.

2.      Select 'Assign Seg Lib' from the menu.  The dialog will show the current library to segment association.

3.      Use the Select Segment Library button to choose the Library you want to be the new assignment.

4.      In the Message Tree, select the segments you want to assign to that library.

5.      Press the Assign button.  This will change the assignment for the selectd segments.  When you are done, Close the dialog box.

Creating and Maintaining Segment Libraries

Create a new library

The MWB is delivered with a set of libraries for each version of the standard. Before making modifications to them, it would be a good idea to make back-up copies. To start with though, we’ll create a new library. Follow these steps:

1.      Bring up the MWB and start a new specification (File/new). Click on the Books icon on the tool bar (or click on Maint/Libraries/Select Conformance Files). Remove any files in the Prioritized Conformance Files list using the left arrow. Then select the HL7 2-3-1.mcf file and click the right arrow to include it on the list. Click OK.

2.      In the Structure field of the main MWB screen, enter ZZZ right after the MSH,. Press Enter or click on the Gear icon to compile the message.

3.      Notice that the message tree has a top-level node of MSH, followed by ZZZ. Expand the MSH node by clicking the ‘+’ to the left of it and notice the list of fields that were added to the tree by the compiler from the library. Expand the ZZZ node in the same way and notice that it has one child element – Set ID. This is how the MWB installs segments that it can find no definition for in the selected library list. Since ZZZ is not in the HL7 2-3-1 library it adds a stub segment to the specification.

4.      Select the Set ID element in the tree with the mouse, and then click on the Add Field (F+) button on the tool bar. In the Add Field dialog that pops up, enter a field name of ‘z stuff’, select a data type of CE from the drop-down list, and click OK. Click the Close button on the Field Add form.

5.      Just for purposes of illustration, select the ZZZ segment in the tree, click on the Add Segment tool bar button (S+). Enter PID and click the ADD button. Click the Close button on the Add Segment form after the segment appears on the tree. Select the PID segment on the tree. In the ‘Element Name’ field to the right, change the segment name to ZPD. Select the Patient ID Field (ZPD-2) and change its data type to ST by selecting the data type in the dropdown list to the right (ignore the warning about data linkage – click OK). Select the Patient Identifier List field (ZPD-3) and click on the Delete an Element icon (left pointing arrow to right of G+) on the tool bar to delete this element from the segment.

Note that we have just used 2 different methods to create custom segments. In the first method (ZZZ), we created one entirely from scratch. In the second method, we created one (ZPD) by modifying a standard segment (PID).

6.      In the Specification field above the Message Tree, enter ‘Test Spec’. In the Message Type filed enter ‘ZZZ’; do the same for the Event Type field. Click the Save button on the tool bar (diskette) or use the File/Save menu option, and save the new ‘Test Spec-ZZZ_ZZZ’ specification to Projects directory (note that the MWB automatically affixes the Message and Event type to the name – you may change the name before filing if you desire). Select File/Close after the specification is saved.

We have just created a new specification that we’ll use in the steps below to create a new segment library.


7.      Select Maint/Libraries/ New Library File. In the dialog that appears, click on the Add Spec button, navigate to the application /Projects directory and select the ‘Test Spec-ZZZ_ZZZ.mwb’ file that you just created. The selected file appears on the Source Specifications list. Note that you could add other specification files to this list if appropriate to your project.

8.      Next, click on the ‘Attach DT’ button, navigate to the DT2-3-1.mdf file and select it. This step attaches a data type file to the library. You will seldom have to use the Force Data Type re-compile, and can ignore it here. Data Type file use and maintenance are discussed elsewhere.

9.      Click on the ‘Compile’ button to create the new library. This process may take a few moments. The time it takes to compile is proportional to the size and number of specifications on the list. Wait for the compile to complete before proceeding.

10.  Click on the SaveAs button. Name the File ‘Test Lib’ and save into the application library directory /Lib. Click the ‘Done’ key after the file is saved.

11.  We are going to add this new library file to the list of conformance files following the procedure we used in step one. Click on the Books icon, and in the dialog that appears; add the ‘Test Lib.mcf’ file to the list right under the HL72-3-1.mcf. Click OK when done.

We have just created a new segment library file, which can be used alone or in combination with others to create new message specifications.


12.  To see our new library file in action, select File/New from the main menu. In the structure field after the MSH, add the following: EVN,ZPD,PV1,ZZZ. Press Enter, or click the Gear icon on the tool bar. Expand each segment in turn. Notice that the ZPD-2 Patient ID has a data type of ST, just as you re-defined it, and that the Patient Identifier List field no longer exists. Notice too, that the ZZZ segment appears just as you defined it.

 

 

Maintain Existing Libraries 

Maintaining a Segment Library is very similar to creating a new one. Through modification to existing specifications or new specifications, you may add, remove or redefine segment definitions. Basically, the procedure is to recompile the library under the association of one or more specification files. Use the Maint/Libraries/Edit Library File option on the Main menu for this purpose. This option offers the ability to overwrite existing segment definitions, Add New segment definitions only, or Replace the entire library with the new compilation. We’ll work through an example where we add new segment definitions only.

 

The following procedure assumes that you have worked through the creation of the new library file described above, that you have the last message that we created in that procedure in the Message Tree(MSH, EVN,ZPD,PV1,ZZZ), and that you are using a library list consisting of the HL72-3-1.mcf and the Test Lib.mcf.

In this exercise we will pretend that we are extending an existing message specification, by adding another segment to it. We will want to use this new segment in other messaging projects, so we’ll add it to the Test Lib library. The procedure outlined below, will add the segment to the existing specification. We’ll save the specification, and then we’ll edit the Test Lib library file to add the new segment to it. Keep in mind that while we are only adding one segment to the specification and thus to the library, we could add any number of segments to both

1.      With the message described above loaded, click on the S+ icon on the tool bar to add a Segment. In the Add Segment dialog, name the segment ‘ZXX’, and click OK to add the segment to the tree. Close the Add Seg Dialog.

2.      Expand the ZXX segment in the Message Tree, and select the Set ID field. On the tool bar select the F+ icon to add a new field. In the Add Field dialog, name the field ‘stuff’’, and give it a data type of CE. Press OK to add the field to the tree. You should see the stuff’ field together with its components added right after the Set ID field in the tree. Close the Add Field dialog.

3.      For purposes of illustration, expand the MSH seg, and select the Sending Application field. Change its data type from HD to ST. We’ll examine this after we modify the library file.

4.      Select File/SaveAs and save the new specification as Test Spec 2.

5.      Select Maint/Libraries/Edit Library File from the main menu. Navigate to the Test Lib.mcf file that you created earlier and select it. You may get a warning that source message specifications or constituent files cannot be found. Ignore this warning (its purpose is currently deprecated and will most likely be removed in future versions). If you don’t get the warning, you may see the source specifications list populated with one or more files. You may leave them there if you want to re-compile them into the library, or remove them by clicking on the Delete Spec button.

6.      Notice that on the left hand side of the form, you’ll see a list of the Constituent Segments in this library. Note too, that at the bottom of the form, the Data type file that you previously associated with this library is displayed. Click on the Add Spec button, navigate to the Test Spec 2.mwb specification that you just saved, and select it. You should see it added to the Source Specifications list. Note that if you had several specifications that you wanted to harvest segments from for this library, you could add them as well.

7.      Examine the Seg Actions group of buttons. In this example, we will only add new segments to the library. The application defaults to the Add New Only option. This means, that the library compiler will go through the source specification a segment at a time and if it finds the segment already defined in the library, it will ignore the specification definition. If on the other hand the compiler does not find a specification segment in the library it will add it to the library.

8.      Click on the Compile button. When compilation is complete, Save the file, then click Done.

9.      To confirm that the new segment has been added to the library, select File/New, then add ZPD,ZXX after the MSH, in the structure field. Press return. Expand each of the segments in turn. Note particularly that the ZXX segment that we defined is now part of the library. Examine the MSH-3  Sending Application field. Not that the field has a data type of HD indicating that the change we made to ST did not get compiled into the new library definition. Since we selected the Add New Only option this is what we should have expected.

Notes on other library compilation options

If you want to make changes to existing segment definitions as well as add new segments to a library, select the ‘Overwrite Existing’ Seg Actions option in the Maintain Specification Libraries dialog. So for example if you want to change field parameters for a segment or segments, you may create a new message using those segments (with the object conformance library selected of course), make the changes say to some fields data type, field lengths etc. save the specification, then compile it into the object library just as described above. In this instance however be sure to select the Overwrite Existing option.

 If you anticipate making changes to several segments in a library you may want to use Maint/Libraries/Rebuild Lib from Segs option. This option reads the currently selected conformance libraries and builds an HL7 abstract message representing each of the constituent segments. It loads this abstract message into the Structure field of the MWB. Click on the Gear icon to compile the message and populate the tree. You can now go and make updates to any or all of the segments in the library save it as a specification and re-compile it into the library to capture changes. This feature is also handy when used in conjunction with Data type maintenance utilities and HL7 version upgrades. Data type maintenance will be discussed in another article.

 The Replace File option of the Library Compilation utility will allow you to recreate a library from scratch. It is used primarily for deleting segments from an existing library, and may be used to create a new library for an occasion like a version change. In either event, the Maint/Libraries/Rebuild Lib from Segs option can be helpful. If you want to delete segments from a library, use the option to load all of the segments into the message tree, then use the Delete button on the tool bar (arrow with '–' sign) to delete the unwanted segments. Save the resultant specification and compile it into the existing library using the replace file option.

The MWB library utilities afford messaging developers and implementers the ability to create custom libraries that may be used in a wide variety of projects. Aside from the fact that you can inherit message elements from specifications and other libraries, keep in mind that you may record implementation specific notes and example values for the fields within your segment libraries. This together with other features of the MWB can be very helpful in rapid messaging application prototyping and development. Create corporate specific, partner specific or version specific libraries that can be easily re-used or extended to maximize your productivity.

Home