In our second video about working with local code systems, we will focus on making modifications to existing codes and creating new content. We’ll also use the history view to see how a code changes over time.

This is the second video of a four-part series about local code systems. You can find the other videos of this series at

Once you’ve seen the video, you can find additional documentation at:



This is the second video of a series about working with Local Code Systems. Today we will focus on making modifications to existing codes and creating new content.

Local Code Systems can either be created directly in Snow Owl or they can be imported from an Excel sheet. I’ll demonstrate import and export in a future video. For this one, I’ve already imported two Local Code Systems, which you can see here in the view.

When I open the folder of a Local Code System by clicking this triangle, I can see the codes indicated by the green icons. Let’s start making modifications to the existing data. To make a modification, you need to bring up the editor because this is where you can make changes. You can do this by finding the code in the view either by using the filter search or by just opening the hierarchy and double-clicking it, or you can also use the quick search and pick the code from the list, for example “food” and this will open the editor.

I would like to make a few changes to this code here. First I would like to change the term. You can make a change in the editor simply by deleting and overwriting the information. So now I changed the term.

I would like to add another alternative term, which is this button here. You just click the button and it brings up a new text box where you can enter a new term. Let’s enter “Catering Supervisor.” To delete an alternative term just click the minus here. Let’s delete this one. Alternatively, I could have just overwritten the information here, but I wanted to show you these two buttons, how to use them.

If I wanted to inactivate this code, I would just uncheck the box but let’s not do this. Let’s save the changes. I can enter a commit comment: “Modified terms”.

The reason why we have these commit comments is that when using Snow Owl in the real world making modifications like this is regulated by workflow. So whenever you make a change you can enter a commit comment. The workflow ensures that authoring and reviewing business processes are followed so that changes are reviewed by different parties before publication. I’m logged in as an administrator, therefore, I can bypass this process without any restriction for this demonstration, but usually you would have several parties that are involved and it makes sense to leave a commit comment.

OK, now I’ve made several changes and if you’re curious to see what kind of changes were made you can now go to the History view, which is this one here. This view can also be linked to the active editor, just like you can link other views to the editor.

We can see now – since I’ve made some changes – that there are two versions of this local code: this is the first one, that’s what I started out with, that’s what I imported earlier and in the second version there were three changes you can see when the changes were made, who made the changes, and the comment that I entered is here. In the bottom section are change details displayed.

Now let’s make a change to a Local Code System. So we need the editor for the Local Code System, I just double click it and this brings up the editor, you see it looks different from the editor for local codes.

Let’s change the description of the Local Code System. Let’s call it “Occupational classification” and save: “Changed description of Local Code System”. OK. And now we see the history of the Local Code System. I need to refresh this here, this button, so now we have both versions. It shows that the attribute description changed to Occupational classification. So this is the first one, and this is the second one. Since this is linked, if I go to the other editor, I can see the history of the local code, and here the history changes.

The information that is displayed here is also information that I need to enter if I want to create a completely new Local Code System. It’s this button here in the toolbar. If you click it, the wizard comes up, which is exactly the same information. These fields here are mandatory so let’s create a new Local Code System called “Country codes”:

  • Short name: COCO.
  • I’ve already copied and pasted an OID. OIDs are registered at HL7 and this is the one for B2i, it’s pretty long this is why I just copied and pasted it.
  • Let’s call it 0.1 version, and
  • Description: Country codes system.
  • You see now I could already hit the “Finish” button, but let’s enter an address for the organization that is maintaining this, and “This is the B2i Healthcare country code system” as a comment.

If I click “Finish” the new Local Code System is here in the view and I can start adding local codes. This works with the context menu so you just go on the folder, right-click and select “Add new child code” and this already brings up a new editor where I can enter my terms. Let’s start with “Hungary” the code is HU, term is Hungary and a Hungarian alternative term would be the Hungarian word for Hungary: “Magyarország” and save. OK. You can see here that we already have the new code that was added.

If wanted to create a code in the same level, I right-click and go to “Add child code” again. If I wanted to a create subcode, I would go to this one and then add a child code from here. But we need a code in the same level. Let’s do it again, let’s add a code for Germany and German term “Deutschland.” Save. And one more time: Add child code: US, United States. I don’t need to add an alternative term so I can just save and hit OK.

So now we already have three codes in our code system and these codes are already searchable. So if I type “deut” for Deutschland, I can see the term Germany coming up so it also searches for alternative terms, but I could also enter the code ID here.

I want to show you how to create a sub-category, for example, for United States. So if you click the parent, right-click “Add new child”, it creates a sub-category for United States. Let’s create one for Arizona. Save. And here is the new sub-category. If you wanted to create another sub-category, you would start here, a sub-category of Arizona. You can create a hierarchical code system this way, always go to the parent code.

If you want to delete a code, it also works with the context menu. You right-click it, “Delete code” and then you’re presented it with a deletion plan, which shows the components that are affected. In this case it’s just one code. Click “Finish” and you can see now this one is gone.

If you delete an entire Local Code System you would click on the folder, right-click “Delete Local Code System” and there it also shows you that you not only deleting the Local Code System, but all the codes that are in the system as well. Click “Finish” and it’s gone.

There are restrictions to deleting local codes, for example, if you are trying to delete a component that is referenced in the value set or mapping, let me show you one for example, this one. If I’m trying to delete this, I’m prompted by message that says “The deleted component is referenced please remove, the references first”. So you cannot delete a code that is part of a value set or that is mapped in a mapping set. To prevent you from doing this you can’t delete until you remove those references.

OK, that’s all I want to show about Local Code System editing for now and in the next video we will talk about using Local Code Systems in value sets and mappings. I hope you enjoyed it. Thank you very much for your attention.