This wiki has undergone a migration to Confluence found Here
<meta name="googlebot" content="noindex">

Difference between revisions of "VocApp-Tutorial"

From HL7Wiki
Jump to navigation Jump to search
 
 
(5 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
===Introduction===
 
===Introduction===
−
In order to familiarize the user with the tool, this section provides a step by step example of the process, starting with a newly installed Harmonization Editor.
+
This is a '''Do It Yourself - Step-by-Step''' exercise that leads you through the steps necessary to
−
 
+
*[[#Startup|Start the application]] and load the vocabulary;,
−
In this walk-through, a '''sequence of instructions''' is presented on the left, and the figure to the right shows the result. Where text needs to be entered into a form, it is usually shown on the '''''screen shot'''' rather than in the instructions.
+
*[[#Create_Header|Create a change proposal]];
−
===Create Header===
+
*[[#Add_Code_Change|Define the change]];
−
===Add_Code===
+
*[[#Apply_Changes|Apply the changes to the data base]];
−
===Review Proposal===
+
*[[#Review_Results|See the results]]; and
−
===Apply Changes===
+
*[[#Remove_Changes|Undo the changes]]
−
===Review Results===
+
====Requirements====
−
===Remove Changes===
+
In order to do this exercise, you will need:
 +
*to have [[Harmonization_Editor_Manual_%28Installation%29|installed the application]] and
 +
*a [[Installing_and_Configuring_HL7_Tools#Design_Repository|design repository]] with the vocabulary content available.
 +
====Tutorial layout====
 +
In this exercise:
 +
*Each step is defined by '''text on the left''' and a resulting '''"screen-shot" on the right'''
 +
*The text includes a '''short title''' followed by a '''numbered sequence of instructions''' or comments.
 +
*Where the instructions require text to be entered into a form, the text is usually shown on the '''''screen shot''''' rather than in the instructions.
 +
*The '''result of the step''' is the screen-shot shown to the immediate right of the instructions. 
 +
*When you execute the step, your application (or a portion of it) should be '''similar but not identical''' to the screen shot.
 +
*''because of the instructions-left/results/right pairing, several of the instruction sequences start with a phrase like "Press '''SomeButton''' (on previous screen)"
 +
*:That is, the button or control to be selected is shown on the previous screen shot.''
 +
===Startup===
 
{| align="center" style="text-align:left"
 
{| align="center" style="text-align:left"
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Start the program'''
 
#Start the '''Harmonization Editor''' application
 
#Start the '''Harmonization Editor''' application
 
|[[Image:VocAppIntro-020.gif|thumb|center|512px|Newly started Harmonization Editor with notes]]
 
|[[Image:VocAppIntro-020.gif|thumb|center|512px|Newly started Harmonization Editor with notes]]
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Load Vocabulary'''
 
#Select '''Menu...File...Load Vocabulary'''
 
#Select '''Menu...File...Load Vocabulary'''
 
#In the file system browser, select your '''design repository'''
 
#In the file system browser, select your '''design repository'''
Line 22: Line 36:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Populate Value Set Navigator pane'''
 
#Click on '''Concept Domain Tree''' tab
 
#Click on '''Concept Domain Tree''' tab
 
#Scroll down until you can see '''ActClass'''
 
#Scroll down until you can see '''ActClass'''
 
#Click on '''ActClass''' to select it
 
#Click on '''ActClass''' to select it
 
|[[Image:VocAppBrowse-030.gif|thumb|center|512px|Harmonization Editor with Domain selected]]
 
|[[Image:VocAppBrowse-030.gif|thumb|center|512px|Harmonization Editor with Domain selected]]
 +
|}
 +
:{{to-top}}
 +
===Create Header===
 +
{| align="center" style="text-align:left"
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Initiate change proposal'''
 
#Select '''Menu...File...Create New Vocabulary Change Request'''
 
#Select '''Menu...File...Create New Vocabulary Change Request'''
 
#This is the panel in which you enter the '''primary proposal identification data'''
 
#This is the panel in which you enter the '''primary proposal identification data'''
Line 33: Line 53:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Add identifying data to form'''
 
#Use drop-downs and text entry to add text shown at right
 
#Use drop-downs and text entry to add text shown at right
 
#Note '''''tool tips''''' that appear when you hover over a box
 
#Note '''''tool tips''''' that appear when you hover over a box
Line 38: Line 59:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Add supporting text'''
 
#Click '''Next''' ''(on the previous screen)''
 
#Click '''Next''' ''(on the previous screen)''
 
#This is the first of four dialogs for entering supporting information as indicated in the text pane
 
#This is the first of four dialogs for entering supporting information as indicated in the text pane
Line 44: Line 66:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Complete creation of proposal header'''
 
#Click '''Next''' ''(on the previous screen)''
 
#Click '''Next''' ''(on the previous screen)''
 
#Note that an entry for your proposal has been added in the '''Proposed Change Requests''' box of the  '''Proposal View'''
 
#Note that an entry for your proposal has been added in the '''Proposed Change Requests''' box of the  '''Proposal View'''
Line 50: Line 73:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Display initial proposal in browser'''
 
#Click '''View''' ''(on the previous screen)''
 
#Click '''View''' ''(on the previous screen)''
 
#This is an XML viewer that will allow you to review the content of your proposal as it currently stands.  (The '''Edit''' button and '''Edit XML''' tab do not currently do anything.)
 
#This is an XML viewer that will allow you to review the content of your proposal as it currently stands.  (The '''Edit''' button and '''Edit XML''' tab do not currently do anything.)
 
#'''If you wish to edit any of the meta-data''' about the proposal, the '''Edit Meta-data Wizard''' button would take you back to the screen three above here.
 
#'''If you wish to edit any of the meta-data''' about the proposal, the '''Edit Meta-data Wizard''' button would take you back to the screen three above here.
 
|[[Image:VocAppProposal-060.gif|thumb|center|512px|Change Request Browser showing new proposal]]
 
|[[Image:VocAppProposal-060.gif|thumb|center|512px|Change Request Browser showing new proposal]]
 +
|}
 +
:{{to-top}}
 +
===Add Code===
 +
{| align="center" style="text-align:left"
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
Line 65: Line 93:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
 +
'''Begin to add code to selected value set'''
 
#Select the '''Add Codes to Value Set''' option on the '''''value set operations menu''''' ''(on  previous figure)''
 
#Select the '''Add Codes to Value Set''' option on the '''''value set operations menu''''' ''(on  previous figure)''
 
#At right is the first of a set of dialogs used to add coded concepts to a value set
 
#At right is the first of a set of dialogs used to add coded concepts to a value set
Line 73: Line 103:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Add new coded concept to Code System'''
 
#Click '''Next''' ''(on the previous screen)''
 
#Click '''Next''' ''(on the previous screen)''
 
#This is the panel used to add a new coded concept '''to a Code System'''
 
#This is the panel used to add a new coded concept '''to a Code System'''
Line 80: Line 111:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Verify concept to be added to value set'''
 
#Click '''Next''' ''(on the previous screen)''
 
#Click '''Next''' ''(on the previous screen)''
 
#This screen is a '''''verification''''' step showing the value set above and the code to be added below.  If these were in error, the '''Back''' button would allow correction.
 
#This screen is a '''''verification''''' step showing the value set above and the code to be added below.  If these were in error, the '''Back''' button would allow correction.
Line 85: Line 117:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Review value set addition(s)'''
 
#Click '''Next''' ''(on the previous screen)''
 
#Click '''Next''' ''(on the previous screen)''
−
#The screen at right summarizes the actions taken so far.  The Value set being expanded is shown above, and the list of coconcepts (only one, here) being added is shown below.
+
#The screen at right summarizes the actions taken so far.  The Value set being expanded is shown above, and the list of concepts (only one, here) being added is shown below.
 
#If you wished to add more codes, you could click the '''Next''' button here, which would return you to the "create/add" screen three above, but '''<u>do not do this</u> for this example exercise'''.
 
#If you wished to add more codes, you could click the '''Next''' button here, which would return you to the "create/add" screen three above, but '''<u>do not do this</u> for this example exercise'''.
 
|[[Image:VocAppProposal-130.gif|thumb|center|512px|List of codes to be added to Value Set (dialog)]]
 
|[[Image:VocAppProposal-130.gif|thumb|center|512px|List of codes to be added to Value Set (dialog)]]
 +
|}
 +
:{{to-top}}
 +
===Review Proposal===
 +
{| align="center" style="text-align:left"
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Review proposal as an XML command file'''
 
#Click '''Finish''' ''(on the previous screen)''
 
#Click '''Finish''' ''(on the previous screen)''
 
#This is an '''OPTIONAL REVIEW STEP'''
 
#This is an '''OPTIONAL REVIEW STEP'''
Line 99: Line 137:
 
<code>C:\russ\projects\development\ HL7Tooling\HL7HarmonizationTooling\ resources\requestedProposals Modelling and Methodology-Trial Proosal For Editor Manual-2007-10-02.xml</code>
 
<code>C:\russ\projects\development\ HL7Tooling\HL7HarmonizationTooling\ resources\requestedProposals Modelling and Methodology-Trial Proosal For Editor Manual-2007-10-02.xml</code>
 
|[[Image:VocAppProposal-140.gif|thumb|center|512px|XML file content for example code addition]]
 
|[[Image:VocAppProposal-140.gif|thumb|center|512px|XML file content for example code addition]]
 +
|}
 +
:{{to-top}}
 +
===Apply Changes===
 +
{| align="center" style="text-align:left"
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''"Activate" proposal and apply changes to data base'''
 
#On the '''ProposalView''' pane:
 
#On the '''ProposalView''' pane:
 
##Click on your proposal file in the list of '''Proposed Change Requests''' to select it
 
##Click on your proposal file in the list of '''Proposed Change Requests''' to select it
Line 111: Line 154:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Verify successful completion of update'''
 
#Use the log scroll bar to scroll to the bottom of the log.   
 
#Use the log scroll bar to scroll to the bottom of the log.   
 
#The last line should read '''Successful load!'''
 
#The last line should read '''Successful load!'''
 
|[[Image:VocAppProposal-180.gif|thumb|center|512px|End of log from Applying update showing successful completion]]
 
|[[Image:VocAppProposal-180.gif|thumb|center|512px|End of log from Applying update showing successful completion]]
 +
|}
 +
:{{to-top}}
 +
===Review Results===
 +
{| align="center" style="text-align:left"
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Note "prior state" of value set view'''
 
#Click '''Close''' ''(on the previous screen)''
 
#Click '''Close''' ''(on the previous screen)''
 
#Check your '''Value Set Navigator''' pane.  It should still be showing the old data, as at right.
 
#Check your '''Value Set Navigator''' pane.  It should still be showing the old data, as at right.
Line 121: Line 170:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Refresh view to see change added'''
 
#Click on the '''ActClass''' line in the '''Concept Domain Tree''' '''(upper panel)'''
 
#Click on the '''ActClass''' line in the '''Concept Domain Tree''' '''(upper panel)'''
 
#After the '''Value Set Navigator''' contents refresh, click on the '''+/- box''' to the left of the '''ActClass''' node in order to expand the branch
 
#After the '''Value Set Navigator''' contents refresh, click on the '''+/- box''' to the left of the '''ActClass''' node in order to expand the branch
Line 126: Line 176:
 
#'''Abra-ca-dabra''' the '''AAR (aardvark)''' has been added to your Act Class vocabulary.  You should also see this if you use RoseTree to browse the same repository.
 
#'''Abra-ca-dabra''' the '''AAR (aardvark)''' has been added to your Act Class vocabulary.  You should also see this if you use RoseTree to browse the same repository.
 
|[[Image:VocAppProposal-192.gif|thumb|center|512px|Value set tree after "refreshing" pane to see change]]
 
|[[Image:VocAppProposal-192.gif|thumb|center|512px|Value set tree after "refreshing" pane to see change]]
 +
|}
 +
:{{to-top}}
 +
===Remove Changes===
 +
{| align="center" style="text-align:left"
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Restore data base to prior state'''
 
#When you are ready to remove this change from you database, Select '''Menu...File...Restore Vocabulary'''
 
#When you are ready to remove this change from you database, Select '''Menu...File...Restore Vocabulary'''
 
#After a bit of machination, the dialog at right should appear verifying the data base was restored to its earlier state.
 
#After a bit of machination, the dialog at right should appear verifying the data base was restored to its earlier state.
Line 133: Line 188:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Delete change proposal file'''
 
#To delete your example Change Request, go to the '''ProposalView''' pane.  In that pane:
 
#To delete your example Change Request, go to the '''ProposalView''' pane.  In that pane:
 
##Select your example proposal in the '''Proposed Change Requests''' list ''(this step may be unnecessary)''
 
##Select your example proposal in the '''Proposed Change Requests''' list ''(this step may be unnecessary)''
Line 141: Line 197:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 +
'''Close the application'''
 
#Click '''OK''' ''(on previous screen)''
 
#Click '''OK''' ''(on previous screen)''
 
#Select '''Menu...File...Exit'''
 
#Select '''Menu...File...Exit'''
−
| style="text-align:center" |<big>'''HERE ENDETH THE EXERCISE'''</big>
+
| style="text-align:center" |<big>'''HERE ENDETH THE LESSON'''</big>
 
|}
 
|}
 +
:{{to-top}}

Latest revision as of 17:18, 3 October 2007

Introduction

This is a Do It Yourself - Step-by-Step exercise that leads you through the steps necessary to

Requirements

In order to do this exercise, you will need:

Tutorial layout

In this exercise:

  • Each step is defined by text on the left and a resulting "screen-shot" on the right
  • The text includes a short title followed by a numbered sequence of instructions or comments.
  • Where the instructions require text to be entered into a form, the text is usually shown on the screen shot rather than in the instructions.
  • The result of the step is the screen-shot shown to the immediate right of the instructions.
  • When you execute the step, your application (or a portion of it) should be similar but not identical to the screen shot.
  • because of the instructions-left/results/right pairing, several of the instruction sequences start with a phrase like "Press SomeButton (on previous screen)"
    That is, the button or control to be selected is shown on the previous screen shot.

Startup

Start the program

  1. Start the Harmonization Editor application
Newly started Harmonization Editor with notes

Load Vocabulary

  1. Select Menu...File...Load Vocabulary
  2. In the file system browser, select your design repository
  3. Click Open
Harmonization Editor with fresh vocabulary load

Populate Value Set Navigator pane

  1. Click on Concept Domain Tree tab
  2. Scroll down until you can see ActClass
  3. Click on ActClass to select it
Harmonization Editor with Domain selected
Jump to top of page

Create Header

Initiate change proposal

  1. Select Menu...File...Create New Vocabulary Change Request
  2. This is the panel in which you enter the primary proposal identification data
First Proposal Definition dialog

Add identifying data to form

  1. Use drop-downs and text entry to add text shown at right
  2. Note tool tips that appear when you hover over a box
Proposal data filled in, also showing tool tip

Add supporting text

  1. Click Next (on the previous screen)
  2. This is the first of four dialogs for entering supporting information as indicated in the text pane
  3. You do not need to enter anything in this box
Proposal Text dialog for Main Issue (and others)

Complete creation of proposal header

  1. Click Next (on the previous screen)
  2. Note that an entry for your proposal has been added in the Proposed Change Requests box of the Proposal View
  3. Note that your new request as automatically activated and thus is the Active Proposal
Proposal view frame with new proposal shown and activated

Display initial proposal in browser

  1. Click View (on the previous screen)
  2. This is an XML viewer that will allow you to review the content of your proposal as it currently stands. (The Edit button and Edit XML tab do not currently do anything.)
  3. If you wish to edit any of the meta-data about the proposal, the Edit Meta-data Wizard button would take you back to the screen three above here.
Change Request Browser showing new proposal
Jump to top of page

Add Code

  1. Click Close (on the previous screen)
  2. Look at the Value Set Navigator pane (lower left)
  3. Click on the +/- box to the left of the ActClass node in order to expand the branch
  4. Click on the +/- box to the left of the act node in order to expand the branch
  5. Click on the act node to select it.
  6. Right-click on the act node to see the value set operations menu as shown at right
Right-click menu for a Value Set node in Value Set Navigator tree

Begin to add code to selected value set

  1. Select the Add Codes to Value Set option on the value set operations menu (on previous figure)
  2. At right is the first of a set of dialogs used to add coded concepts to a value set
  3. The values set to which the codes will be added is shown in the upper half. This is the value set on which you right-clicked in the Value Set Navigator
  4. Select the radio button to Create a new Coded Concept...
  5. The other choice is used to (re-)assign existing codes to value sets.
Add coded concepts to value set (dialog)

Add new coded concept to Code System

  1. Click Next (on the previous screen)
  2. This is the panel used to add a new coded concept to a Code System
  3. Note that the Code System was automatically selected based on the code system whose codes make up the existing value set.
  4. Use the data on the figure at right to fill out your form
Add new code to Code System (dialog)

Verify concept to be added to value set

  1. Click Next (on the previous screen)
  2. This screen is a verification step showing the value set above and the code to be added below. If these were in error, the Back button would allow correction.
Verify Code to add to Value Set (Dialog)

Review value set addition(s)

  1. Click Next (on the previous screen)
  2. The screen at right summarizes the actions taken so far. The Value set being expanded is shown above, and the list of concepts (only one, here) being added is shown below.
  3. If you wished to add more codes, you could click the Next button here, which would return you to the "create/add" screen three above, but do not do this for this example exercise.
List of codes to be added to Value Set (dialog)
Jump to top of page

Review Proposal

Review proposal as an XML command file

  1. Click Finish (on the previous screen)
  2. This is an OPTIONAL REVIEW STEP
  3. The xml content of a change proposal file is shown at right. It should be pretty close to the change Request you just finished creating. To compare these do one of the following:
  4. Click the View button on the ProposalView pane to open the internal proposal reviewer, or
  5. Use a program like XML Spy to open the file:

C:\russ\projects\development\ HL7Tooling\HL7HarmonizationTooling\ resources\requestedProposals Modelling and Methodology-Trial Proosal For Editor Manual-2007-10-02.xml

XML file content for example code addition
Jump to top of page

Apply Changes

"Activate" proposal and apply changes to data base

  1. On the ProposalView pane:
    1. Click on your proposal file in the list of Proposed Change Requests to select it
    2. Click Activate and verify your proposal is shown as the Active Proposal
    3. Click Apply
  2. The Apply button should appear to remain depressed and after a bit of grinding, the pane at right should appear.
  3. This pane is a display of the process log that applied the selected change control against your data base
  4. If this panel does not appear after 30-60 seconds, or if the Apply button no longer appears depressed, your change proposal did not get processed. The most likely reason is that you did not fill in one of the fields on the proposal meta-data entry form. You can View your proposal and the select Edit Meta-data Wizard to verify this.
Start of log from Applying update showing steps

Verify successful completion of update

  1. Use the log scroll bar to scroll to the bottom of the log.
  2. The last line should read Successful load!
End of log from Applying update showing successful completion
Jump to top of page

Review Results

Note "prior state" of value set view

  1. Click Close (on the previous screen)
  2. Check your Value Set Navigator pane. It should still be showing the old data, as at right.
Value set tree before "refreshing" pane to see change

Refresh view to see change added

  1. Click on the ActClass line in the Concept Domain Tree (upper panel)
  2. After the Value Set Navigator contents refresh, click on the +/- box to the left of the ActClass node in order to expand the branch
  3. Click on the +/- box to the left of the act node in order to expand the branch
  4. Abra-ca-dabra the AAR (aardvark) has been added to your Act Class vocabulary. You should also see this if you use RoseTree to browse the same repository.
Value set tree after "refreshing" pane to see change
Jump to top of page

Remove Changes

Restore data base to prior state

  1. When you are ready to remove this change from you database, Select Menu...File...Restore Vocabulary
  2. After a bit of machination, the dialog at right should appear verifying the data base was restored to its earlier state.
Database restoration notice

Delete change proposal file

  1. To delete your example Change Request, go to the ProposalView pane. In that pane:
    1. Select your example proposal in the Proposed Change Requests list (this step may be unnecessary)
    2. Click on the Activate button (this step may be unnecessary)
    3. Click on the Delete button
  2. Verify that your example is the one to be deleted. If it is not, click Cancel and repet the selection steps above.
Dialog to verify change proposal deletion

Close the application

  1. Click OK (on previous screen)
  2. Select Menu...File...Exit
 HERE ENDETH THE LESSON
Jump to top of page
Retrieved from "https://wiki.hl7.org/w/index.php?title=VocApp-Tutorial&oldid=14799"