Messaging Workbench Tutorial Review Guide

 

This guide is meant to be a supplement to the MWB tutorial and online help. The MWB is a feature rich application, and during the typical two quarter HL7 tutorial the coverage of individual features is brief at best. Consequently it is not surprising that the typical tutorial attendee has difficulty remembering how best to approach a given messaging project when using the workbench “back at the ranch”.

 

This guide, which relies heavily on pictures and diagrams, is intended to serve as a bridge between the tutorial experience and the textual online documentation. Hopefully it will provide the novice MWB user with a sufficient memory  “jog” to facilitate easy access the more important basic features of the tool - it does not go into detail.

 

For more in depth discussions of features consult the online documentation articles available on the MWB Help menu, and the FAQ included as part of this handout. Feel free also to post questions to the Yahoo MWB Tools forum or the Conformance List serve.

 

 

Tutorial and Presented by:

Peter Rontey

 

 

 

 

 

 

 

 

 

 

 

 


Contents:

 

Section                         

1.     Starting a new profile using the available message structure libraries – page 3

 

2.     Producing Profile Reports - page 6

 

3.     Message Capture – page 9

4.     Segment and Message Library Selection – page 13

5.     MWB Options – page 15

6.     Maintaining Segment Libraries – page 20

7.     Data Type Library Maintenance – page 24

8.     Table Library Maintenance – page 28

9.     Basics – page 31

 

Messaging Workbench FAQ - page 32                        

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 


 

 

 

Peter Rontey    Page 3  1/14/2004

1. Starting a new profile using the available message structure libraries

 

fig 1. Load Msg Structure option

 

fig 2. Message and event type selection list

 

fig 3. Selected message structure and location of compile button

 

Notes:

Before pressing the Compile button, the structure field may be edited to add/remove segments/segment groups using the keyboard. After compilation, the Structure field can no longer be edited with the keyboard, and the compile button is no longer active.

 

Message structure changes after compilation using tools specific to that purpose on the toolbar (see below).

 

 

 

 

 

 

 

 

 

 

 

 

 

fig 4. Nascent profile ready to be constrained, created from standard libraries

 

 

 

 

2. Producing Profile Reports

 

 

 

fig 5. Reports Display Tab

 

 

figure 6. Reports drop down list and report viewer toggle button

 

 

 

figure 7. Text view of SpecXML report when toggle button displays a scroll icon

 

 

figure 8. HTML view of SpecXML report; toggle button displays Internet Explorer icon

 

 

 

figure 9. Report File Menu showing XSL Translation and Validation options; HL7 Registry Profile production button


 

 

3. Message Capture

 

figure 10. Message Capture tab; message file navigation button; an example message file is shown highlighted

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

figure 11. Captured message instance in message text window; message parse button indicated.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

figure 11. Parse tree and derived message structure resulting from Parse Message button click indicated. Button used to derive profile also indicated.

 

 

 

 

 

 

figure 12. Illustrates profile reverse engineered from captured message instance above

 

 

 

 

 

 

 

 

 

 

 

 

 

 

4. Segment and Message Library Selection

 

figure 13. Segment library selection

 

Notes:

Although a default segment library may be defined, it is important to ensure that the segment library selected is appropriate for the particular HL7 version and local extensions of the project under consideration. Segment libraries come into play whenever an segments are being compiled (e.g. starting a new profile, reverse engineering from a captured message instance, or adding a segment to a profile).

 

 

 

 

 

figure 14. Selecting a message structure library; the dot indicates the currently selected library.

 

figure 15.  Message structure selection list indicates the library source of the list – may be a custom message library list.

 

Notes

Data type libraries are associated with segment libraries at segment library creation. The active table library is selected through the Maintenance/Options general tab (shown below).

5. MWB Options

 

figure 16. Selecting Maint/Options from the main menu

 

 

 

 

 

 

 

 

 

 

 

 

 

 

figure 16. General options tab; default Conformance (segment) library and table libraries indicated. Note that the table library selected is customized for the VA.

 

 

Notes:

Conformance file is synonymous with segment library in the MWB.

The buttons with ellipsis are used to navigate to the appropriate library files. Both the segment and table libraries installed with the MWB are in the ..\Lib folder.

 

 

figure 17. MWB Options/Reports tab indicates ability to set default style sheets, reports listed on the reports tab, and portal for defining custom reports.

 

 

 

 

 

 

 

 

 

 

 

 

 

figure 18. List of field element attributes that may be set to be used in profile comparisons. Default attribute selection (click Set Default button) is partially displayed.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

figure 19. Message structure library creation/maintenance tab

 

 

 

 

 

 

 

 

 

 

 

 

 

6. Maintaining Segment Libraries

 

 

figure 20. Selecting segment library maintenance

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

figure 21. Selecting a custom segment library to edit

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

figure 22. Selecting a profile from which segments will be added to segment library

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

figure 23. Significant aspects of segment library maintenance

 

 

 

 

 

 

 

 

 

 

 

 

 

 

7. Data Type Library Maintenance

 

 

figure 24. Selecting Data type maintenance option

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

figure 25. Selecting a custom data type library to edit

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

figure 26. Selecting a data type to edit

 

 

 

 

 

 

 

 

 

 

 

 

figure 27. Data type edit form

 

 

 

 

 

 

 

 

 

 

 

 

 

 

8. Table Library Maintenance

 

figure 28. Selecting table maintenance option

 

figure 29. Selecting a table file to edit

figure 30. Table and table element maintenance form with button for batch addition of table elements indicated

 

 

 

 

 

 

 

 

 

 

figure 31. Batch table element entry form

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

9. Basics

 

figure 32. Messaging Workbench directory structure with Examples folder selected

 

 

Notes:

New releases and periodic updates are announce on the HL7 Conformance SIG list serve (conf@lists.hl7.org ) and can be downloaded from the Conformance SIG documents page at http://www.hl7.org/lib_admin/docs.cfm?dir=library/committees/conf&comm=conf.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Messaging Workbench FAQ

(12/03)

 

My MWB is currently using HL7 v 2.4 libraries. How can I take advantage of the new v 2.5 libraries?

First thing to do is to go to Maint/options. At the bottom of the General tab, navigate to the new table file "HL7TableFile 2-5.mwt" and select it. If you want the 2.5 segment lib as your default, select it too ("Select Default Conformance File"). Remember, for segment libraries, you can easily change those from the tool bar (line of books icon; mid right).

 

To load the 2.5 message structure library is a little trickier. Go to Maint/Options "Msg Structs" tab. In the "Structure Store" dropdown box, type "HL725Structs". Click on the button to the right labeled "Associate Text File", and navigate to the "structs" folder (in Lib folder) and select the "HL725Structs.txt" file. If you wan this to be your default message structure file, be sure to check the "default" checkbox to the left of the "Associate text file" button. Toward the bottom of the form, click the "Save Button". Click the OK button to leave the Maint options.

 

Go to the main menu "File" option, "Change Structure List" option to see if "HL725Structs" is on the list. If you made it the default, you should see a ball next to it on the list. If you don't see it on the list, exit the workbench and restart.  Go to File\Load msg Structure. The list of available v2.5 messages should display for you to select.

 

Are there any examples available to help me get started using the MWB?

Example profiles come with the install package. They can be found in the MWB root directory in folder Projects\Examples. Look for Big Red...mwb and Wondercis.mwb among other examples. To load, go to the MWB File menu and select the Open option. Navigate to one of the examples.

 

If you want to start with a new profile from scratch, go to File\Load Msg Structure... A list box will fill with all of the message types for a particular HL7 version. Click on the '+' under each message type to reveal a list of 1 or more event types. Select an event type of interest (double click is quickest). You'll see the selected message structure appear in the structure field of the Message Definition tab. Click on the yellow gear icon on the tool bar (4th from left) to compile the abstract message structure. After a few seconds, you'll see the message tree for the profile appear. Constrain it as desired to meet your needs, then use File\Save.

 

Those are a couple of ways to get started. If you still have problems, or questions, give me a call. I can get you started easier by phone than writing it all down. Let me know how you make out.

 

The XML profile that I generate from the workbench does not validate against the HL7 normative DTD, am I running the wrong report?

The problem that you're having is based on the fact that there are 2

different main XML profile reports available from the MWB. The most popular for local usage is the SpecXML report, which is right at the top of the report drop down list. When you run this report it produces an XML file that has a default style sheet attached which you can toggle with the browser button to view it as xml text or html.

 

There is another step that you must take to produce the HL7 registerable xml profile. Notice that there is a button on the far right of the tool bar with a stylized "HL7" on it. With the XML text from the SpecXML report showing in the window, click on the HL7 button. This causes another transform to be applied the specXML report which produces the HL7 registerable profile (the one with the element name HL7v2xConformanceProfile ). Name and save this XML text. It can be registered with HL7 and can be imported back into the MWB.

 

There are other XML reports that you'll run across, most importantly the spec XML with tables, which adds all table references and associated elements for message elements in use in the profile specification – very handy for documentation. Unfortunately at this point the HL7 registry does not store tables in a profile.

 

For fields that are not supported in a message we are selecting "conditional" as the usage and in the predicate we enter "EMPTY".  However, in our formal documentation we want to convert all the fields that were marked as conditional/empty as 'Not Supported'. Is there some magical way of performing a global change or do I need to go into each field and make this change?

There is a way of performing the change "magically" for your formal documentation leaving the .mwb profile as is. Its the magic of XSLT. All you need to do is to change your style sheet to translate "C" to "NS". Of course if I understand correctly you don't want to just change all "C", but only those that also have "EMPTY" in the predicate field. This complicates the XSLT logic a little, but is still doable. I did a quick test using the MWBProfile.xsl that is shipped with the MWB, and had it change all fields marked "C" to "NS" and it went smooth.

 

Is there a way to get a message profile from the MWB into a spreadsheet?

That can be done in a couple of different ways, although not directly from the MWB. The quick and dirty way is to run the SpecXML report, copy and paste the html view of it into Excel. You'll probably want to go in and delete all but one of the segment header rows, and all of the legend rows, but with a modest amount of editing, you'll have a spreadsheet version of the profile.

 

A more elegant and ultimately quicker solution to porting a profile to a spreadsheet is to create a modified version of the  MWBProfile.xsl that will output the html from the SpecXML report formatted specifically for the spreadsheet. Then for each profile that you want to port its just a matter of copying from MWB and pasting into Excel. I've used this technique myself to port profile information to spreadsheets. Take a look at the MWBProfileFO.xsl which plucks out only the field level information from SpecXML to get an idea of what I'm talking about.

 

The application that I’m working with doesn’t use the HL7 recommended delimiter set. How can I get the MWB to produce example ER7 message instances using my delimiter set?

You can change the field separator and encoding characters that are used in the Ex Msg-ER7 report by providing the appropriate example values in MSH.1 and MSH.2. So for example if the example value for MSH.1 is @ and for MSH.2 is '*-+_' then the output of the Ex MSg-ER7 report might look like this:

 

            MSH@*-+_@1*2*3@a*b*c@@@@@@@@2.x*usa_united states of america*2.y_2 dot why

 

Obviously you can see that for this example I've only valued a couple of fields in the MSH in addition to MSH.1 and MSH.2.

 

On the message capture side, the delimiters found in the captured message MSH.1 and .2 are used for parsing and automatically set as example values for MSH.1 and MSH.2 when you reverse engineer the profile.

 

Can I represent segment and field repetitions in a profile created with the MWB?

The MWB handles both repeating segs, and repeating fields. To demonstrate a repeating seg, just add the replicate seg(s) to the profile at the appropriate location. Be sure to add example values to the fields of the replicate if you want to see them in the ER7 report.

 

Similarly, you can add replicate fields to a seg. This feature was introduced in release 5. On the toolbar in the vicinity of the Add Seg (S), Add Field (F) etc., you'll see a button that looks like a pile of pages. Use this to insert replicate fields. Highlight the field for which you want a replicate, then click the tool button. The replicate field will be added immediately after the highlighted one. Repeat this for the number of replicate fields that you want. The pages symbol will be displayed next to the replicate(s) in the message tree. The name of the field is the same as the principal field, but has "_rep" concatenated at the end. Just as with the replicate segments, make sure that you provide example values for the field and its components, otherwise you won't see the replicates in the ER7 report.

 

By the way, if you do a message capture on a message with replicate fields and or segments, there are options (check boxes)that allow you to preserve or ignore the replicates. The beauty of using message capture of course is that the example values are captured for you automatically.

 

I am trying to change the Family name component of the XCN data type from a data type of FN to ST, but the MWB won’t let me. Is this a bug?

The MWB will only allow you to change data types at the field level, since changing the data types of components/subcomponents within fields creates erroneous data types. So for example, if the MWB allowed you to change the family name component of an XPN field from FN to ST, you would in fact be creating a bogus data type (i.e. not a Kosher XCN in this example).

 

The MWB however will allow you to create your own data types. You can create Z data types and you can redefine standard data types (e.g. you could go into the MWB's 2.4 data type file and redefine the XCN data type erroneously as it is in chapter 3), but obviously this isn't recommended. The only time you might legitimately want to change standard data types is when you are upgrading to a new version of the standard or making an HL7 sanctioned correction.