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:
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
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
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
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).
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
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
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.
(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.