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

Difference between revisions of "VocApp-ValSetChanges/ValSetMenu"

From HL7Wiki
Jump to navigation Jump to search
Line 43: Line 43:
 
#The lower pane provides a field for the value set name.  This name:
 
#The lower pane provides a field for the value set name.  This name:
 
#*'''must have no spaces or punctuation''';
 
#*'''must have no spaces or punctuation''';
#*'''must be unique across all HL7 value sets; and
+
#*'''must be unique across all HL7 value sets'''; and
 
#*'''should''' be patterned after other value sets in the same code system.
 
#*'''should''' be patterned after other value sets in the same code system.
 
#The lower pane includes a field for the description of the value set. If the name has been entered, the wizard will show an error at the top until text has been added to the description field, as shown in the next figure.
 
#The lower pane includes a field for the description of the value set. If the name has been entered, the wizard will show an error at the top until text has been added to the description field, as shown in the next figure.
Line 55: Line 55:
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
#With the name and description fields both completed, the '''Create a new Child Value Set''' page shows and enabled '''Next''' button at the bottom.
+
#With the name and description fields both completed, the '''Create a new Child Value Set''' page enables the '''Next''' button (as at right-bottom).
 
#When you are satisfied with the entries, click '''Next'''
 
#When you are satisfied with the entries, click '''Next'''
 
|[[Image:VocAppVSCreate-040.gif|thumb|center|512px|Create New VS: New VS named and defined]]
 
|[[Image:VocAppVSCreate-040.gif|thumb|center|512px|Create New VS: New VS named and defined]]
Line 61: Line 61:
 
| valign="top"|
 
| valign="top"|
 
#The wizard presents the '''Select Value Set type''' page (as at right)
 
#The wizard presents the '''Select Value Set type''' page (as at right)
#This page offers a single selection from two radio buttons (circled) as two whether the value set reference to its parent (the node selected in the navigator) is to be '''''abstract''''' or '''''specializable'''''.
+
#This page offers a single selection from two radio buttons (circled) as to whether the value set reference to its parent (the node selected in the navigator) is to be '''''abstract''''' or '''''specializable'''''.
 
#Choose your preferred option and click '''Next'''
 
#Choose your preferred option and click '''Next'''
 
|[[Image:VocAppVSCreate-050.gif|thumb|center|512px|Create New VS: Select whether new VS is to be Abstract or Specializable]]
 
|[[Image:VocAppVSCreate-050.gif|thumb|center|512px|Create New VS: Select whether new VS is to be Abstract or Specializable]]
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 
+
#If the new value set is '''''abstract''', this step will not be displayed and the next location is the [[#Subprocess to Bind to domain|option to bind to a domain]]
 +
#If the new value set is '''''specializable''', the wizard presents the '''Assign Head Code to Value Set''' page (as at right)
 +
#This page has an option (circled) in the top pane,. and two entry panes below that.
 +
#The option is whether to assign an '''existing code''' or a '''new concept code''' as the head code for the new Value Set.  This figure demonstrates the entry of the first of these options, and the following figure shows the use of the second option.
 +
#The middle pane provides the ability to '''Search''' for concepts using either their print name ('''''Concept''''') or their '''''Code'''''
 +
#The '''Search Text''' is used to make a non-case-sensitive match against the opening sequence of characters.
 +
#Clicking '''Search''' populates the results pane in the middle.
 +
#From this list select the code to be used as the head code
 +
#When the correct selection is made, click '''Next'''.
 
|[[Image:VocAppVSCreate-060.gif|thumb|center|512px|Create New VS: For new Specializable VS, select to use existing or new code as head code; with existing, search on print name or code; and select a value from the list]]
 
|[[Image:VocAppVSCreate-060.gif|thumb|center|512px|Create New VS: For new Specializable VS, select to use existing or new code as head code; with existing, search on print name or code; and select a value from the list]]
 
|-
 
|-
 
| valign="top"|
 
| valign="top"|
 
+
#If the option in this pane is to '''Create New Concept''' the entries are made in the bottom pane.
 +
#Make an entry in each field as:
 +
#*print name in '''Coded Concept''' field;
 +
#*code in '''Concept Code''' field; and
 +
#*textual description in '''Concept Description'''field
 +
#When the entries are correct, click '''Next'''.
 
|[[Image:VocAppVSCreate-070.gif|thumb|center|512px|Create New VS: For new Specializable VS, select to use existing or new code as head code; with new head code, specify print name, code value and description.]]
 
|[[Image:VocAppVSCreate-070.gif|thumb|center|512px|Create New VS: For new Specializable VS, select to use existing or new code as head code; with new head code, specify print name, code value and description.]]
 
|-
 
|-

Revision as of 00:36, 10 October 2007

Changes from a Value Set Selection

The figure at right shows the various options that can be selected when a Value Set node is selected in the Value Set Navigator window, and the right mouse button is clicked. In each case, the menu selection starts a process to define changes to be applied to the selected value set. (NOTE: The first selection Create Value Set actually creates a value set as a child (sub-type) of the selected value set.)

These selections are intended to cover all possible operations on a value set node. In aggregate, the functions provided include:

  • Create or Delete a Value Set;
  • Add or Remove codes from a Value Set;
  • Bind, but not unbind the Value Set to a Concept Domain; and
  • Add or Remove references from the Value Set to child value sets

Further, in several cases, these operations are redundant or partially so. For example, both Create Value Set and Bind Concept Domain to Value Set allow a value set to be bound to a concept domain, but only in Create Value Set can one also define a new concept domain.

Menu selections from a value set node

Create Value Set

This action creates a new Value Set as a child of the Value set that was selected when the menu item was chosen. This is a multi-part operation that includes:

  1. Complete specification of the value set including:
    • Name, description and whether "abstract or "specializable";
    • Parent-child reference from the selected value set to the new one; and
    • Assignment of a head code (if specializable), including the option of defining a new concept to be the head code.
  2. Option of binding the new value set to a concept domain, which may be created if the target does not already exist.
  3. Option to add existing or new coded concepts to the value set
  4. Option to add parent-child value set references from the new value set to existing value sets

Operations 3 and 4, above, are identical to stand-alone operations described in other sections below. They will be discussed in general terms in this section and a hyper link to the detailed discussion will be provided.

Process sequence to Create Value Set
  1. Within the Value Set Navigator select the Value Set node that is to be the parent of the Value Set being created here
  2. Right click on the selected node
  3. Select Create Value Set (see menu at right)
Create New VS: menu (New VS will be created under the VS selected when the menu was activated)
Subprocess to specify Value Set
  1. The wizard opens the Create a new Child Value Set page (as at right)
  2. The top pane on this page identifies the parent value set selected when the menu option was chosen.
  3. The lower pane provides a field for the value set name. This name:
    • must have no spaces or punctuation;
    • must be unique across all HL7 value sets; and
    • should be patterned after other value sets in the same code system.
  4. The lower pane includes a field for the description of the value set. If the name has been entered, the wizard will show an error at the top until text has been added to the description field, as shown in the next figure.
Create New VS: Verify parent VS, enter new VS name (with no spaces or punctuation) and description
  1. The page at right is included to show how the wizard flags potential errors (circled at top) while an error exists in the entered content of the page. In this case it is the lack of a description.
  2. When such errors are present, the Next and Finish buttons at the bottom will be disabled.
  3. In this case, entering text in the description field will clear the error as in the following figure.
Create New VS: Note error flag is a description is not entered.
  1. With the name and description fields both completed, the Create a new Child Value Set page enables the Next button (as at right-bottom).
  2. When you are satisfied with the entries, click Next
Create New VS: New VS named and defined
  1. The wizard presents the Select Value Set type page (as at right)
  2. This page offers a single selection from two radio buttons (circled) as to whether the value set reference to its parent (the node selected in the navigator) is to be abstract or specializable.
  3. Choose your preferred option and click Next
Create New VS: Select whether new VS is to be Abstract or Specializable
  1. If the new value set is abstract, this step will not be displayed and the next location is the option to bind to a domain
  2. If the new value set is specializable, the wizard presents the Assign Head Code to Value Set page (as at right)
  3. This page has an option (circled) in the top pane,. and two entry panes below that.
  4. The option is whether to assign an existing code or a new concept code as the head code for the new Value Set. This figure demonstrates the entry of the first of these options, and the following figure shows the use of the second option.
  5. The middle pane provides the ability to Search for concepts using either their print name (Concept) or their Code
  6. The Search Text is used to make a non-case-sensitive match against the opening sequence of characters.
  7. Clicking Search populates the results pane in the middle.
  8. From this list select the code to be used as the head code
  9. When the correct selection is made, click Next.
Create New VS: For new Specializable VS, select to use existing or new code as head code; with existing, search on print name or code; and select a value from the list
  1. If the option in this pane is to Create New Concept the entries are made in the bottom pane.
  2. Make an entry in each field as:
    • print name in Coded Concept field;
    • code in Concept Code field; and
    • textual description in Concept Descriptionfield
  3. When the entries are correct, click Next.
Create New VS: For new Specializable VS, select to use existing or new code as head code; with new head code, specify print name, code value and description.
Subprocess to Bind to domain
Create New VS: Choose whether to bind VS to a concept domain, and if so whether to select an existing domain, or define a new one. If existing, pick from the list provided.
Create New VS: Choose whether to bind VS to a concept domain, and if so whether to select an existing domain, or define a new one. If new, enter Unique name (with no spaces or punctuation), description, and, if desired select an existing domain
Create New VS: Choose whether to bind VS to a concept domain, and if so whether to select an existing domain, or define a new one. If no binding, there is nothing else to specify on this form.
Subprocess to Add codes
Create New VS: Select whether to add additional codes to value set, and if so whether to select existing codes or create new ones.
Subprocess to Add child sets
Create New VS: Select whether or not to add references to existing value sets (make existing VS children of the new VS)
Subprocess to finish creation
Create New VS: Verify the final package with "Finish"

Delete Value Set

This selection is used to delete a Value Set from the data base.

CAUTION:

Since Value Sets may contain one or more leaf terms (coded concepts) and may reference one or more child value sets, this process leaves contained coded concepts and value sets in limbo. They remain as part of the Code System and Value Set tables, but will not be exposed because there is no longer a parent under which they will appear.

In general, if you wish to remove a value set, you should also plan the disposition of its children by, for example assigning them to one or more remaining value sets. To do this, you will need to prepare a multi-step change proposal that:

  1. Deletes the Value Set here;
  2. Adds the child coded concept(s) to a different value set; and/or
  3. Adds reference(s) from other value sets to the orphaned child value set(s).
Process sequence to Remove reference
  1. Within the Value Set Navigator select the Value Set node that is to be deleted.
  2. Right click on the selected node
  3. Select Delete Value Set (see menu at right)
Delete Value Set: Menu
  1. The wizard will open the Delete Value Set page (as at right)
  2. The top of the page identifies the value set selected in the Navigator
  3. The lower part of the pane includes a single check box to Delete Vocabulary Domain. The actions of this option are as follows:
    • If unchecked, only the Value Set will be deleted.
    • If checked, both the Value Set and any domain to which it is bound will be deleted
  4. When the appropriate selection is made, click Finish.
Delete Value Set: Determine whether to delete bound domain, too; and verify deletion with "Finish"

Add Codes to Value Set

Value Sets may contain one or more leaf terms (coded concepts) and one or more child value sets. This process allows one to add leaf terms that are directly within the value set.

This process has multiple layers, as it also implements the function to create coded concepts in the relevant Code System, which (currently) cannot be done as a direct operation on the Code System.

CAUTION:

A coded term cannot be added to a value set if it is already in that value set or if it is in one of the descendant value sets of that value set. If you desire to move a coded concept from a descendant value set to its parent or an ancestor, you will need to prepare a two-step change proposal that:

  1. Removes the coded concept from the child or descendant, and
  2. Adds a the coded concept to the parent or ancestor value set using this function.
Process sequence to Add codes
  1. Within the Value Set Navigator select the Value Set node to which coded concepts are to be added as leaf terms.
  2. Right click on the selected node
  3. Select Add Codes to Value Set (see menu at right)
Add Code to VS: menu
  1. The wizard presents the Add Coded Concepts To an Existing Value Set dialog (as at right)
  2. This pane identifies the selected value set at the top and then presents a mandatory selection of one of two "radio" buttons (circled at right).
  3. The selection provides two different paths for adding codes -- create new, or add existing. These options will be presented as two subprocesses below.
  4. Select the option you prefer ("add existing" is selected at right) and click Next
Add Code to VS: Select existing or new code (Existing, here)
Subprocess to Add Existing codes
  1. When Add existing is selected above, the wizard next presents the Search for Concept page (as at right)
  2. The upper pane provides the ability to Search for concepts using either their print name (Concept) or their Code
  3. The Search Text is used to make a non-case-sensitive match against the opening sequence of characters.
  4. The search will be made against the Code System listed in the middle pane. This is established based upon the code system used to populate the value set selected at the start.
  5. Clicking Search populates the results pane at the bottom.
  6. From this list you can select one or more codes to be added (using click along with shift or control, as needed)
  7. When the correct selections are made, click Next, not Finish.
Add Code to VS: Search on code or print name; select one or more from result
  1. The wizard presents the Concept Code(s) to be added to Value Set page (as at right)
  2. This page displays the list of codes selected immediately above.
  3. If there are errors in this list (extra or missing elements) you may go Back one page to re-do the search and selection, but doing so runs the risk of creating duplicate entries in the final list and such duplicates cannot be removed, except by editing the change proposal in XML.
  4. Once you progress past this page, however, you may add more terms, but you will not be able to remove terms.
  5. If the list is what you desired, click Next, not Finish
Add Code to VS: Verify selection of existing codes
  1. The wizard presents the page Coded Concepts to be added to the Value Set (as at right)
  2. Although the name is similar to the page above, the page is different. In the lower pane it displays the master list of codes to be added and indicates whether the codes are NEW or EXISTING (circled at right).
  3. This is the master list that is being built for final application to the Value Set.
  4. If you need to remove any entries or if any entry is repeated more than once, click Cancel as there is no way to correct this, except to edit the change proposal in XML, once this change is complete.
  5. If the list is correct (except for needed additions which can be added later):
    1. Click Next to add further terms, either new or existing
    2. Click Finish if the list is complete and correct
Add Code to VS: Note current list of additions
  1. If Next was selected in the preceding page, the wizard again presents the Add Coded Concepts To an Existing Value Set dialog (as at right)
  2. This pane identifies the selected value set at the top and presents a mandatory selection of one of two "radio" buttons (circled at right).
  3. The selection provides two different paths for adding codes -- create new, or add existing. These options are presented as subprocesses.
  4. Select the option you prefer ("create new" is selected at right) and click Next
Add Code to VS: Again select to add existing vs new code (new, here)
Subprocess to Create new codes
  1. When create new concepts is selected above, the wizard presents the "Add Coded Concepts to an Existing Code System page (as at right)
  2. The page at right was pre-filled to demonstrate a common error. In this case, the code entered for the new term already exists in the Code System. This is high-lighted with an error message (circled at top), and the Next and Finish buttons are disabled.
  3. Making a non-conflicting code entry resolves this, as in the next figure.
Add Code to VS: Adding new code, note error when attempt to enter a code that is already in the code system.
  1. When non-conflicting data are entered in the Add Coded Concepts to an Existing Code System page (as at right), all buttons are enabled.
  2. When the correct print name (Coded Concept), code (Concept Code) and description are entered, click Next not Finish.
Add Code to VS: Adding new print name, code, and description.
  1. The wizard again presents the Coded Concept to be added to Value Set page (as at right)
  2. This is a verification page, but you should not select Back to correct these. Doing so will cause duplicate entries in the master list.
  3. Click Next, not Finish
Add Code to VS: Verify new code to add
Subprocess to Complete addition
  1. Once again, the wizard presents the page Coded Concepts to be added to the Value Set (as at right)
  2. The lower pane displays the master list of codes to be added and indicates whether the codes are NEW or EXISTING (circled at right).
  3. If you need to remove any entries or if any entry is repeated more than once, click Cancel as there is no way to correct this, except to edit the change proposal in XML, once this change is complete.
  4. If the list is correct (except for needed additions which can be added later):
    1. Click Next to add further terms, either new or existing
    2. Click Finish if the list is complete and correct
Add Code to VS: Review and accept list of new and existing codes to be added

Remove Codes from a Value Set

Value Sets may contain one or more leaf terms (coded concepts) and one or more child value sets. This process allows one to remove leaf terms that are directly within the value set. It will not allow removal of the "head codes" of child value sets, nor the leaf terms that are members of the child value sets.

CAUTION:

Removing a coded term from a value set leaves the coded concept in limbo. It remains part of the Code System, but will not be exposed because there is no longer a parent under which it will appear.

In general, a code should only be removed from a value set in one of two circumstances:

  1. Where the coded concept is already listed under two or more value sets and the objective is to remove it from one of these; or
  2. Where the goal is to move the coded term to a different value set. In this case, you will need to prepare a two-step change proposal that:
    1. Removes the coded concept here, and
    2. Adds a the coded concept to a different value set.

For other purposes, the Retire Code function is probably more appropriate.

Process sequence to Remove codes
  1. Within the Value Set Navigator select the Value Set node from which coded terms are to be removed.
  2. Right click on the selected node
  3. Select Remove Codes from a Value Set (see menu at right)
Remove codes from VS: Menu
  1. The wizard displays the Codes Within the selected Value Set pane (as at right)
  2. The upper part of the pane identifies the selected value set.
  3. The lower portion is a list of all of the coded concepts that are direct children of the value set, showing their code, print name and partial description.
  4. Select the code(s) to be removed, using Click, Control-click, and Shift-click as necessary.
  5. When the selections are complete, click Finish
Delete Value Set: Select code(s) to delete from list and verify deletion with "Finish"

Update Value Set Description

Each Value Set has a description that defines what the value set represents and/or contains. These definitions may include sections for the definition, discussion of the rationale underlying the value set. and examples of coded terms it may contain.

Process sequence to Update description
  1. Within the Value Set Navigator select the Value Set node whose description is to be updated.
  2. Right click on the selected node
  3. Select Update Value Set Description (see menu at right)
Update VS Description: Menu
  1. The wizard opens with the WRONG TITLE of Codes within the Selected Value Set (as at right)
  2. Fortunately the wizard functions correctly. The upper portion shows the selected Value Set and its current description.
  3. The lower pane provides three text boxes in which to create the definition, discussion and examples for the new description.
  4. When the lower panes are correctly updated, click Finish
Update VS Description: Enter revised description and confirm with "Finish"

Bind Concept Domain to Value Set

Each Concept Domain in the terminology may be bound to one or more value sets. Where there are multiple bindings, each binding is in a particular context or binding realm. This function allows a predefined value set (the one selected to start the process) to be bound to a predefined concept domain. It uses the "default" context (no value) meaning that it will be bound in the universal (UV) realm.

Data definition for Binding Concept Domain to Value Set

CAUTIONS:
  1. This wizard does not include the context attribute whereby a binding is made in the context of a binding realm, Thus it creates all bindings in the universal (UV) realm. Although these can be stored in the data base, in general multiple bindings to a single concept domain within a single context are invalid.
  2. This wizard only binds to predefined Concept Domains. The only place that the application allows the definition of new Concept Domains is within the Create Value Set function.
Process sequence to Bind Concept Domain
  1. Within the Value Set Navigator select the Value Set node that is to be bound to a Concept Domain.
  2. Right click on the selected node
  3. Select Bind Concept Domain to Value Set (see menu at right)
Bind Concept Domain to VS: menu
  1. The iwzard presents the Bind Value Set to Concept Domain pane as at right
  2. The bottom portion of the screen is an alphabetic list of all concept domains defined in HL7. The list is extensive. It can be made to hop to a particular entry by quickly typing the initial characters of the name. (See Alphabetic skipping in a list.)
  3. Find (hop and/or scroll to) the domain to which the binding is to be made, and select that entry.
  4. When the selection is correct, click Finish
Bind Concept Domain to VS: Select domain from list of existing domains.

Add Value Set References

Although "reference" is a generic term, the only kind of value set reference included in the Vocabulary Maintenance Language, and in the underlying Access data base tables, is a parent-child relationship wherein the reference is from the parent to the child. This action will allow the user to select one or more value sets to be added as children to the parent Value Set selected in the Value Set Navigator.

  1. Within the Value Set Navigator select the Value Set node that is to be the parent of the Value Set references you wish to establish.
  2. Right click on the selected node
  3. Select Add Value Set References (see menu at right)
Add VS References: Menu
  1. The wizard will present a Search for Value Set page (as at right) which includes the propsective parent value set listed in the middle of the pane.
  2. A Search box is presented at the top. The search is made on the Value Set names for the current code system, and will search for all value sets whose names begin with the string in the 'Search Text'. (The search is not case sensitive.)
  3. Enter a Search Text and click the Search button to populate the Value Set list at the bottom of the page.
  4. Select the child node(s) whose reference(s) you wish to add. Multiple selections may be made by judicious use of Shift-click and Control-click in addition to just Click.
  5. When the selection list is complete for this search sttring, click Next (not Finish).

If you need the results of more than one search string, you can click Next to move the current selections to the prospective list, and then Back (see note below) to return here to find and select other value sets.
Add VS References: Search on start of VS name and select one or more from list
  1. The next pane presented is the Abstract or Specilizable page on which each of the selected child value sets is listed.
  2. If you need to make additions to this list, you can click Back and you will be returned to the selection page where you can use different search strings or add selections from the previous search.
  3. There is no way to remove a value set from this list. To do that, you should click Cancel and restart this step.
  4. To the left of each entry in the list is a check box. The boxes can be marked with a check by clicking the box. (A second click will undo the first.)
  5. Put a check mark next to all value sets that will be added to the parent as 'specializable -- where the head code of the value set is to be included in the parent value set.
  6. Leave unchecked all value sets that will be added to the parent as 'abstract -- where the head code of the value set will not be included in the parent value set.
  7. When the list is complete and correct, click Next, not Finish.
Add VS References: List of Value Sets to be added as children; for each select to add as Abstract or Specializable
  1. The wizard presents the Value Set List page as at right. This page lists all of the selections made in the steps above.
  2. Verify that this list is correct.
  3. If you need to make changes, you can click Back and return to the previous panes to change or add to your selections. You will not be able to remove items.
  4. The Cancel button will stop the change wizard, with no entries added to the proposal file.
  5. When the listed elements meet your expectations, conclude the removal steps by clicking Finish.
Add VS References: Review current list of references to add and confirm with "Finish"

Remove Value Set References

Although "reference" is a generic term, the only kind of value set reference included in the Vocabulary Maintenance Language, and in the underlying Access data base tables, is a parent-child relationship wherein the reference is from the parent to the child. This action will remove one or more parent-to-child references from the parent Value Set selected in the Value Set Navigator.

CAUTIONS:

Removing a value set reference leaves the value set and its code content in limbo. They remain part of the Code System and part of the Value Set definitions, but will not be exposed because there is no longer a parent under which they will appear.

In general, a code system reference should only be removed in one of two circumstances:

  1. Where the child value set is already listed under two or more parents and the objective is to remove and not replace one of the references; or
  2. Where the goal is to move the child value set to a different parent. In this case, you will need to prepare a two-step change proposal that:
    1. Removes the parent child reference here, and
    2. Adds a value set reference from a new parent to the same child.

For any other purpose, the Delete Value Set function is probably more appropriate.

Process sequence to Remove reference
  1. Within the Value Set Navigator select the Value Set node that is the parent of the Value Set reference you wish to remove.
  2. Right click on the selected node
  3. Select Remove Value Set References (see menu at right)
Remove VS References: Menu
  1. The wizard will present a Value Set References page (as at right) listing all of the child references held by the parent value set node you selected in the navigator.
  2. Select the child node(s) whose reference(s) you wish to remove. Multiple selections may be made by judicious use of Shift-click and Control-click in addition to just Click.
  3. When the selection list is complete, click Next (not Finish).
Remove VS References: Select child reference(s) to remove from list
  1. The wizard presents the Value Set References to Remove page as at right. This page lists all of the selections made in the step above.
  2. Verify that this list is correct.
  3. If you need to make changes, you can click Back and you will be returned to the selection page with the previous selection showing. You can then use Control-click to add to or remove from the previous selection(s).
  4. The Cancel button will stop the change wizard, with no entries added to the proposal file.
  5. When the listed elements meet your expectations, conclude the removal steps by clicking Finish.
Remove VS References: Review list to be removed, and verify with "Finish"