This screencast demonstrates importing and exporting local code systems into Snow Owl from Excel files.
This is the last video of a four-part series about local code systems. You can find the previos videos of this series at
- Video 1: Introduction to local code systems
- Video 2: Local code systems – creating and maintaining content
- Video 3: Using local codes in value sets and mapping sets
Once you’ve seen the video, you can find additional documentation at:
- Browsing and searching local code systems
- Creating and maintaining local code systems
- Importing and exporting local code systems
- Mapping sets
- Value sets
In the last video of this series about Local Code Systems. I would like to demonstrate how to import and export.
When you start out your Local Code System view is empty. You can either click this icon to create a new Local Code System – it also works when you click this link here -or, if you already have local codes in an Excel file, you might want to use the import feature.
To start an import go to File > Import, open the Snow Owl folder and go to “Local Code Systems from Excel file”, Next and now you can browse for your import file. There are three different options for import:
- You can either clear the existing Local Code Systems, this overwrites the existing content with imported content. You can also use this option when importing for the first time, this clears everything that’s in the Local Code System view and you start out from scratch.
- If you already have some content that you don’t want to delete, you would use the merge option. This adds new content to existing data without removing or changing existing content, for example, if you have a Local Code System it would add codes to this Local Code System or you could add a completely new Local Code System to the existing content.
- The third option is something that you would use if you import a new version of your Local Code System and you wanted to update the existing content, for example, by adding, modifying or removing codes. Existing content that is not part of the import is kept and not changed.
We will use the first option here and since we are about to overwrite the entire data there’s a warning just to make sure.
After the import we are presented with a summary. We can see what kind of component was imported, for example, we imported two Local Code Systems. These are the files for the Local Code Systems, and these here are the local codes that we imported. You can see the code ID and the term for the code.
Clicking on one of those items displays additional information down here, for example, we can see the main properties of the Local Code System for example what meta-data were imported. If you have different versions of a Local Code System, if you are updating a Local Code System, then you could see the different versions here and if you click on the version, you would see the history. So you could see what happened at each import.
The imported Local Code Systems are also registered in the terminology registry which is up here: Snow Owl > About Snow Owl and then there is a button here called “Installation Details”. And this is the terminology registry where you can see all terminologies and Local Code Systems that are available in Snow Owl.
We can see the two Local Code Systems that we just imported, this one and this one. We can see the system ID here. We just make this one a bit bigger.
Clicking on an item displays additional information, for example, here for SNOMED CT I could see a description and you can also see when there are different versions of a terminology here. So right now I just have the latest version of SNOMED CT, however, if you had older versions you could see this as well and the same applies to your Local Code System, but since we just imported it, it’s just one version that we have in here. So much about importing.
Let’s talk about exporting Local Code Systems as an Excel file. When you export data it’s like taking a snapshot of the current data that is in your system assuming that you saved all your changes. So all local codes in all Local Code Systems will be exported, so everything that is here in my view will be exported exactly the way that it is.
To start an export, we go to File > Export, open the Snow Owl folder and select “Local Code Systems to Excel file”, Next. Now we need to specify the path. I would like to export it to my desktop and enter a name for the export file, I’ll just call it “Export”, save and then you run the export. It’s already done. There’s a link to your export file that opens the Finder.
Let’s open the file and take a look at it. You can see there are two sheets because we exported two Local Code Systems. The information in the top part is what you could also find on the Overview page – let’s just close this window – of the editor of your Local Code System: So the name, the short name and the OID are also here. So this is this information and the codes are displayed in the bottom section in these columns here. Here are the code IDs, the terms. Alternative terms are here, if there is no alternative term, the cell is empty. If you have several alternative terms, they are all in one cell.
You can see if the code is active or inactive. This one is unpublished. This is why there is no effective time here. So if we go to this code system, we can see that all these codes are unpublished while those here are published and since they are published we have an effective time here in this column so you can see if our code system is published or unpublished.
And if it’s a hierarchy, you would find a parent code here and for a flat list this column is empty. So let me just show you what this looks like. You have this one as a flat list and this one is a hierarchy and in the export file you would find the parent code for each of these codes here in this column here.
So this is the file that you need if you want to import your local codes as well so it should be in this format if you want to import them into Snow Owl.
When you are making an export you are not modifying the content so you are just exporting exactly what you can see here on the user interface. If you want to create an export file, for an official release of your Local Code System, you would need to update unpublished components first. For example, you would have to update these components that are in this Local Code System and specify a publication date for it.
To do this you would go to Tools > Create version, and then – when you are creating a version of a Local Code System – you would have to enter a version name and a description and then you could also specify a publication date and once you create this version all these unpublished components would be updated and would have an effective time associated with it. Once you’ve done this then you can run an export which works exactly the same way as described and then you can use this export as a release file.
There’s also the option to switch between versions so if you created several versions of your Local Code System you could do this here and select one but since I just have one version I cannot do anything here right now. Then this would display an older version and since you are always exporting what is displayed here you could export an older version this way and have an Excel file of an older version but I will talk about versioning in detail in a later video I just wanted to show you that this export also works for official releases.
That’s all for today. Hope you enjoyed it. Thank you for attention.