Editing a Code System

Existing Code Systems are managed by the Code Systems table.

🚧To edit an existing Code System, please follow the steps below:

1

Navigate to the Code Systems View

The Code Systems View displays and manages the Code Systems table

🚧To navigate to the Code Systems View:

  • Go to the Concept Dictionary -> Code Systems view via the Navigation Menu

2

Locate the Code System Record

The Code Systems will be displayed and managed by the Code Systems table

Search for a desired Code System to edit.

Searching for a Code System

To locate the Code System, search the Code Systems table by:

  • 👀Manually searching for the desired Code System

  • 🔍Filtering the Code Systems by entering the Code System Name into the Search input.

3

Open the Edit Code System View

Editing Code Systems are managed by the View Code System

🚧To open the View Code System view

  • Click the View button in the Actions Column of the Code System table

After, the View Code System view will display

Downloading the Code System

The Code System can be downloaded as a dataset file and can be imported at a later time

🚧To download/export the Code System, please follow the steps below:

1

Click the Download Button

Downloading a Code System is handled by the Download button in the header panel of the Edit Code System view

🚧To download the Code System export:

  • Click the Download button

After, the dataset file should be downloaded to your device

Core Properties Panel

The Core Properties panel displays and manages core properties of a Code System

Property
Description

Name

A short, descriptive, human readable, unambiguous name for the code system

Domain

a unique short name for the code system.

OID

A universally unique identifier for the code system.

URL

A unique resource locator to the definition of the terminology.

Version

The exact version of the terminology being imported or expressed by the code system.

Description

A description the what the Code System is and its intended use case — or any other relevant information about it

Created By

The user who created this Code System + the date and time this Code System was created

✏️Editing Core Properties

Editing Core Properties are managed by the Core Properties panel

🚧To edit Core Properties of a Code System, please follow the steps below:

1

⭐Update the Name (Optional)

The Name is a short, descriptive, human readable name for the code system.

🚧To define the Name for the Code System:

  • Enter a Name into the Name input

Examples

  • ISO3166-2 Alpha Country Codes would be a good name for the domain ISO3166-2

  • LOINC would be a good name for the domain LN

  • HL7v2 Administrative Sex would be a good name for the domain V2AdministrativeGender

2

⭐Update the Domain (Optional)

The Domain is a unique short name for the code system.

In HL7v2, this is the CX.4 portion of the code — example: CODE^^^DOMAIN.

It is also the short name that appears within internal HDSI view model payloads.

🚧To define the Domain for the Code System:

  • Enter a Domain into the Domain input

Examples

  • ISO3166-2 would be a domain for the name ISO3166-2 Alpha Country Codes

  • LN would be a good domain for the name LOINC

  • V2AdministrativeGender would be a good domain for the name HL7v2 Administrative Sex

3

⭐Update the OID (Optional)

An OID is a universally unique identifier for the code system.

This is used in HL7v2 in the CX.4.3 portion of a code such as CODE^^^&2.25.XXXXXX&ISO and in HL7v3/CDA based transactions.

This should be one of:

  • An IANA Private Enterprise Number based OID

  • An HL7 Registered OID

  • A UUID expressed as 2.25.XXXXXXX

🚧To define the OID for the Code System:

  • Enter a OID into the OID input

4

⭐Update the URL (Optional)

The URL is a unique resource locator to the definition of the terminology.

This is typically used on HL7 FHIR interfaces

🚧To define the URL for the Code System:

  • Enter a URL into the URL input

5

⭐Update the Version (Optional)

The Version is the exact version of the terminology being imported or expressed by the code system.

🚧To define the Version for the Code System:

  • Enter a Version into the Version input

6

⭐Update the Description (Optional)

The Description is a description the what the Code System is and its intended use case — or any other relevant information about it

🚧To define the Description for the Code System:

  • Enter a Description into the Description input

7

Save

Once the administrator has completed the necessary fields, this step will commit the changes to the Code System properties.

🚧To save the new Code System in the application:

  • Click the Save button

Reference Terms Panel

The Reference Terms panel displays and manages codes and mappings used by the particular Code System

➕Adding Reference Terms

Adding Reference Terms are managed through the Add Reference Term view

🚧To add a new Reference Term to a Code System, please follow the steps below:

1

Open the Add Reference Term View

The Add Reference Term view will allow capturing information for a new Reference Term for a Code System

🚧To open the Add Reference Term view:

  • Click the Add button

2

Define the Mnemonic

The Mnemonic is the unique mapping value within the scope of the code system

Naming the Mnemonic

It is highly recommended that users do not use the wire-level reference term mnemonic as the mnemonic for the concept being created.

Internal concept mnemonics are like labels or variable names — they should be globally unique within the application and should be descriptive in their nature.

🚧To define the Mnemonic for the Reference Term:

  • Enter the Mnemonic into the Mnemonic input

3

Add Names

Names are one or more names which can be added to the reference term.

These should be the official translation of the code as they are expected to appear in HL7 messages.

🚧To add a Name for the Reference Term:

  • Enter the Name into the Name Value input

  • Select the appropriate language in the Language input

Adding More Names

Adding More Names is handled by the Add button

🚧To add another Name for the Reference Term:

  • Click the Add button

  • Enter the Name into the Name Value input

  • Select the appropriate language in the Language input

Removing a Name

Removing a Name is handled by the Remove button

🚧To remove a Name from the Reference Term:

  • Click the Remove button

4

Define the Concept(s) Mapping

One or more internal Concepts in the Concept Dictionary needs to be mapped to the reference term.

🚧To define the initial Concept(s) Mapping for the Reference Term:

Select a Mapping

The Mapping defines the comparison between a Reference Term and a Concept

  • Click the Mapping input

After, a dropdown should appear with a collection of Mapping options

  • Search and select an appropriate Mapping option

Different Mappings

The mapping should be selected keeping the following options in mind:

  • SAME_AS — The Reference Term has an identical semantic meaning as the concept

  • INVERSE_OF — The Reference Term has the opposite meaning as the concept

  • NEGATION_OF — The Reference Term indicates a negation of the concept (e.g. a code indicating a negative diagnosis)

  • NARROWER_THAN — The Reference Term has a definition that is narrower in meaning to the concept

  • WIDER_THAN — The Reference Term has a meaning that is more broad in meaning to the concept

Select a Concept

The Concept defines the relationship for comparison between a Reference Term and a Concept

  • Click on the Concept input

After, a dropdown should appear with a collection of Concept options

  • Search and select an appropriate Concept option

➕Adding More Concept Mappings

Adding More Concept Mappings is handled by the Add button

🚧To add more Concept(s) Mappings:

  • Click the Add button

  • Select a Mapping

  • Select a Concept

🆕Creating a Concept before Mapping to Reference Term

Selecting the Magic Wand button 🪄 will allow the user to create a brand new concept (with the same names as entered on the reference term).

After, the Add Reference Term window should look similar to below

If you name the Mnemonic and the Concept to create the same value, you will be presented with a Uniqueness warning.

This just re-iterates the idea that Mnemonics are intended to be globally unique — therefore, the Mnemonic and Concepts should be different

❌Removing a Concept Mapping

Removing a Concept Mapping is handled by the Remove button

🚧To remove Concept(s) Mappings:

  • Click the Remove button

5

Add the Reference Term

After the necessary information is entered into the form, the new Reference Term will need to be added

🚧To officially add the new Reference Term to the Code System:

  • Click the Add button

Add & Create Another

Additionally, users may use the Add and Create Another option to enter multiple codes.

This will:

  1. Create the new Reference Term

  2. Clear the window and allow you to enter a new Reference Term for this selected Code System

🔃Importing Code System Terms

For larger terminologies with thousands of codes, it may be easier to adapt a flat file such as Excel spread sheet of the terms to a comma-separated-value (CSV) file with columns:

🚧To import a batch of Reference Terms for a Code System, please follow the steps below:

1

Open the Upload Reference Terms View

The Upload Reference Terms view handles importing Reference Terms into the system

🚧To open the Upload Reference Terms view

  • Click the Upload button above the Reference Terms Table

After, the Upload Reference Terms window

2

⭐Download the Template (Optional)

If not done prior, this step will download the CSV Template

The Upload Reference Terms view contains a feature for downloading the Reference Terms CSV Template

🚧To download the Reference Terms Template:

  • Click the Download Template link

After, a download should begin — transferring the CSV Template to your machine

3

⭐Populate the Reference Terms Template (Optional)

If not done prior, this step will populate the batch of Reference Terms using the CSV Template from the previous step.

The CSV columns can be populated based upon the descriptions below:

Column
Description
Required

Mnemonic

Contianing the wire level code Containing the mnemonic of the refernece term (how it appears on the wire)

✅

Name

Containing the official translation in the desired language The default display name for the concept

✅

Concept

Containing the Mnemonic of an existing (or new) concept to be created The mnemonic of the concept in SanteDB's internal concept dictionary which should be mapped (if it exists) or created (if it does not)

❌

Mapping

Containing the nature of the mapping between Concept and Reference Term (SameAs,NarrowerThan, etc.)

❌

Comments/Notes

Extra details describing the Reference Term

❌

Example of a Populated CSV

An example of how to populate the CSV can be illustrated below using the ExampleMoodCodeSystem.

‼️Note:

  • each Reference Term should appear on a new line,

  • all columns should be separated by a Comma

  • each value should be enclosed within a string (i.e. begin and end with a " character)

4

Upload the Populated CSV Template

This step will upload the populated CSV template to the central server

🚧To upload the Populated CSV Template:

  • Click the Choose File button

After, a File Explorer Window will display.

  • Select the file using the folder path where the populated CSV templated is located

  • Click the Open button

After, the File input will populate with your selected File

5

Select the File Language

Each CSV File should be listed per language specified

🚧To select the File Language:

  • Click the File Language input

After, a dropdown should display with a collection of available Language options

  • Select the appropriate language option

6

Upload the CSV

This step will send the Populated CSV to the Central Server to be imported

To upload the Populated CSV:

  • Click the Upload button

After, the Upload button should display Please Wait...

After, a confirmation dialog will appear confirming whether you would like to run the import now?

  • Click the Ok button to import the CSV now

Clicking Cancel

Selecting No (i.e. clicking Cancel) will import the CSV when there are less users on the server

After, the Upload Reference Terms view should close

7

⭐Verify the Import was Successful (Optional)

This step will ensure that the new Reference Terms were imported successfully

🚧To verify the Reference Terms were imported successfully

  • Click the Reload button above the Reference Terms Table

After, the Reference Terms Table should reload with the latest Reference Terms for that Code System

  • Verify the Reference Terms imported are displayed in the Reference Terms Table

✏️Editing a Reference Term

Editing Reference Terms are handled through the Reference Terms Table

🚧To edit a Reference Term for a Code System, please follow the steps below:

1

Locate the Reference Term

This step involves locating the Reference Term in the Code System to edit

To locate a Reference Term:

  • Search for a Reference Term in the Reference Table

Searching

Reference Terms can be searched by:

  • 👀Manually searching for the desired Reference Term

  • 🔍Filtering the Reference Terms by entering the Reference Term Name into the Search input.

2

Open the Edit Reference Term View

Editing the Reference Term properties are handled by the Edit Reference Term view

To open the Edit Reference Term view:

  • Click the Edit button in the Actions Column in the Reference Terms Table

After, the Edit Reference Term view should display

3

⭐Edit the Mnemonic (Optional)

Editing the Mnemonic for the Reference Term is handled by the Mnemonic input

🚧To update the Mnemonic:

  • Enter a new Mnemonic into the Mnemonic input

4

⭐Edit, Add, or Remove Names (Optional)

Editing the Names of a Reference Term is handled by the Names control

These should be the official translation of the code as they are expected to appear in HL7 messages.

🚧To edit a Name for the Reference Term:

  • Enter the Name into the Name Value input

  • Select the appropriate language in the Language input

Adding More Names

Adding More Names is handled by the Add button

🚧To add another Name for the Reference Term:

  • Click the Add button

  • Enter the Name into the Name Value input

  • Select the appropriate language in the Language input

Removing a Name

Removing a Name is handled by the Remove button

🚧To remove a Name from the Reference Term:

  • Click the Remove button

5

⭐Edit the Concept(s) Mapping (Optional)

One or more internal Concepts in the Concept Dictionary needs to be mapped to the reference term.

🚧To edit the initial Concept(s) Mapping for the Reference Term:

Select a Mapping

The Mapping defines the comparison between a Reference Term and a Concept

  • Click the Mapping input

After, a dropdown should appear with a collection of Mapping options

  • Search and select an appropriate Mapping option

Different Mappings

The mapping should be selected keeping the following options in mind:

  • SAME_AS — The Reference Term has an identical semantic meaning as the concept

  • INVERSE_OF — The Reference Term has the opposite meaning as the concept

  • NEGATION_OF — The Reference Term indicates a negation of the concept (e.g. a code indicating a negative diagnosis)

  • NARROWER_THAN — The Reference Term has a definition that is narrower in meaning to the concept

  • WIDER_THAN — The Reference Term has a meaning that is more broad in meaning to the concept

Select a Concept

The Concept defines the relationship for comparison between a Reference Term and a Concept

  • Click on the Concept input

After, a dropdown should appear with a collection of Concept options

  • Search and select an appropriate Concept option

➕Adding More Concept Mappings

Adding More Concept Mappings is handled by the Add button

🚧To add more Concept(s) Mappings:

  • Click the Add button

  • Select a Mapping

  • Select a Concept

🆕Creating a Concept before Mapping to Reference Term

Selecting the Magic Wand button 🪄 will allow the user to create a brand new concept (with the same names as entered on the reference term).

After, the Add Reference Term window should look similar to below

If you name the Mnemonic and the Concept to create the same value, you will be presented with a Uniqueness warning.

This just re-iterates the idea that Mnemonics are intended to be globally unique — therefore, the Mnemonic and Concepts should be different

❌Removing a Concept Mapping

Removing a Concept Mapping is handled by the Remove button

🚧To remove Concept(s) Mappings:

  • Click the Remove button

6

Saving the Reference Term

This step will save any changes to the Reference Term and send it to the Central Server

🚧To save any changes to the Reference Term:

  • Click the Save button

After, the Edit Reference Term view should close and the Reference Term should be updated

❌Removing a Reference Term

Removing Reference Terms are handled through the Reference Terms Table

🚧To remove a Reference Term for a Code System, please follow the steps below:

1

Locate the Reference Term

This step involves locating the Reference Term in the Code System to edit

To locate a Reference Term:

  • Search for a Reference Term in the Reference Table

Searching

Reference Terms can be searched by:

  • 👀Manually searching for the desired Reference Term

  • 🔍Filtering the Reference Terms by entering the Reference Term Name into the Search input.

2

Remove the Reference Term

Removing a Reference Term is handled by the Remove button in the Actions Column

🚧To remove a Reference Term:

  • Click the Remove button in the Actions Column of the Reference Terms Table

After, a confirmation dialog should display

  • Click the Ok button to remove the Reference Term

After, a Success notification should appear in the top right-hand corner of the screen

3

Verify the Reference Term is Removed

This step will display the removed Reference Terms in the Reference Terms Table

🚧To verify the Reference Terms have been successfully removed:

  • Click the Reload button above the Reference Terms Table

After, the Reference Terms Table should refresh and redisplay

  • Verify that the records removed are no longer present within the Reference Terms Table

PreviousCreating a Code SystemNextRemoving a Code System

Last updated