V3 PubProcess Content Submission

Preparation of V3 Content for Submission

This "How To" is intended to help those preparing and submitting content for a V3 ballot in the preparation of that material. While the main emphasis is on V3 domain content preparation, much of the guidance provided here is applicable to other V3 submissions as well. This guide assumes you have the basic knowledge needed to prepare and submit content, so the focus is on other considerations that often get missed. These include topics such as checking to ensure the authors and cochairs list is current, ensuring the ballot status is set, and the like.

Presently, this "How To" covers the V3 Publishing Database (the Pub DB), Visio RMIM and XML submissions, graphic images submissions (such as storyboards), and other supplemental content. For additional guidance outside the scope of this "How To", please reference the Publishing Facilitators Guide (PFG) in the V3 Ballot Web Site (located under Background Documents) or join one of the weekly V3 Publishing Conference Calls. A full listing of the conference calls can be found on the HL7 Web Site under Conference Calls.

The HL7 Version 3 Publishing Database

The HL7 Version 3 Publishing Database, aka the pub db, is an access-based tool developed specifically to manage domain content. For specific instructions about installing the pub db tool, please refer to the Installing and Configuring HL7 Tools page Installing_and_Configuring_HL7_Tools. This section covers the following:

1. Updating the Notes to Balloters in the Domain Introduction
2. Checking the Authors List to Ensure it is Up to Date
3. Setting the Ballot Status on Topics
4. Validating the pub db html

1. Updating the Notes to Balloters in the Domain Introduction

While a pub db may contain references to a number of domains, there will be two main records devoted to the specific domain the pub db expresses content for, the domain introduction page (indicated by a code like PORX_DM999999UV) and the primary domain page (indicated by a code like PORX_DM00000UV). The "Preface" is located in the html section of the domain introduction page. If you pub db is installed correctly and you also have XMLSpy installed, you should be able to double-click in the Preface field (also identified as "Overview") and the XMLSpy editor will launch and display the current text for editing. According to section 9.3 of the PFG, the Preface is required to have, at a minimum, the following sections:

1. Notes to Readers (Balloters)
2. Changes from Previous Release (i.e. - last ballot)
3. Message Design Element Navigation (created automatically during the publishing process)

Ensure that the "Notes to Readers" contains any relevant information or reminders for balloters. It is helpful to indicate the ballot level that the material is balloting at at remind reviewers what this might mean in regards to their comments. Ensure as well that ALL SIGNIFICANT CHANGES are listed in the "Changes from Previous Release (or Ballot)" section. These can usually be pulled from the ballot announcement text that was used when the WG submitted its Notification of Intent to Ballot.

2. Checking the Authors List to Ensure it is Up to Date

WG Co-chairs and contributors change on a regular basis, so it is important to update the Authors section of the pub db. Clicking into the primary domain page will take you to the tabbed page listing the different content sections. The Authors tab is the last on the right. Select it and review the contributors listed there. Double-check each person's affiliation and email as well, as sometimes a person will remain in this list but need this information updated.

3. Setting the Ballot Status on Topics

Check that the correct ballot status is set for the domain and for each topic in the pub db. From the pub db starting page, click the "Edit Ballot Artifact Status" button located in the lower right of the screen. The listing defaults to the "Domain" list. Make sure there is an entry for the domain using its 4-letter code, and that the ballot status is set correctly (usually to MembershipNormativeBallot for Normative ballots and to DSTUBallot for DSTU ballots). You should also update the "ballotNumber" and &uqot;effectiveDate" fields. Once the domain is set correctly, you should use the selector in the upper left-hand corner to choose "TOPIC". You should have an entry for every topic in the pub db. If a topic has been removed, you should also remove the corresponding record here. Make sure to click off a record onto another to force the update of any edits.

While it is not common, sometimes you will need to set the ballot status on other elements such as RMIM or interactions. You can use the selector in the upper left to choose the necessary category. It is important to remember that if the status is not set on an element it simply inherits the status of the topic it falls under.

4. Validating the pub db html

In some instances, topics, RMIM, storyboards and other elements may have extensive text associated with them. While the pub db markup is similar to HTML, it is important to recognize that they are not the same. For instance, the anchor tag (<a>) is used in html to create anchors in links, but in the pub db a <loc> tag is used. If you are using XMLSpy and have the "Entry Helpers" window set to display, the "Elements" helper will display all of the allowed elements that are available at the selected entry point. XMLSpy can be a very powerful tool as you can not only use it to check the well-formedness of your markup, you can also validate your markup against the pub db markup xsd.

Some people try to make their edits in other editors or even in Word and then paste their markup directly into the pub db. While this may appear to work, often times whole sections of the text will be dropped from the final HTML expression in the publishing process due to unexpected markup errors. It is possible to validate all of your markup in a pub db using the Validate and Update Descriptive "Mark-up" functionality of the pub db.

From the main pub db entry page, click the "Validate and Update Descriptive Mark-up" button. The will launch the "HL7 Description Editor". Click the "Load Descriptions from Data Base" button. If your markup is correct, a "Finished processing descriptions with NO errors" message will display. If there are errors, the Description Editor will let you step through the sections with errors and correct them.

Please note that in some instances you will not be able to correct the errors using the description editor. This sometimes happens when a description has been previously updated using XMLSpy. If this happens, make note of the section with the error and then navigate to it in the pub db to correct the markup section in place.

Visio RMIM and XML Submissions

When submitting a RMIM model design, especially for a new model, keep in mind the following:

• Submissions should include both the Visio file and its related xml file
• Submissions should not include any additional backup xml files (those with '_bak' in the filename)
• Files should follow the correct naming pattern, that is AAAA_RM######UV, where 'AAAA' is the full domain abbreviation and '######' is the unique numeric identifier matching the pub db entry for this RMIM
• Note that model files should NEVER use 'MT' in place of the 'RM' in the file name
• Note that the entry point in the model should match the file name identifier

Storyboard and Other Graphics Submissions

When submitting storyboard graphics, keep the following in mind:

• All storyboards should be submitted as '.gif' files. (If you submit a Visio file, it will be saved as a '.gif' using the default image settings.)
• The filenames of storyboard images must match the full identifier used in the pub db. For instance, if the identifier in the pub db is 'PORX_ST000001UV', then the file name must be 'PORX_ST000001UV.gif'.
• If you have defined a storyboard in the pub db and have not submitted a corresponding storyboard graphic, a default graphic with the caption 'Diagram or Graphic Unavailable' will appear in the Diagram section.

When submitting other graphics, keep the following in mind:

• All graphics use the <graphic/> tag.
• Typical tag usage is as follows: <graphic source="filename.jpg"/>
• Acceptable formats are '.jpg', '.gif', and '.png'.

Supplemental Materials Submissions

In general, other materials such as PDFs, zip files, and files for specific or special purposes can be submitted. In the ballot output, these files will be placed in the root directory, so any links to these files should link to this location.

You can use the <loc> tag to link to additional materials. Typical usage is as follows: <loc href="samplefile.pdf">click here</loc>.

Jump to top of page