Now that we have our instance up and running, the next step is to understand how to communicate with it. Fortunately, Snow Owl provides very comprehensive and powerful APIs to interact with your instance.

REST API

Among the few things that can be done with the API are as follows:

• Check your instance health, status, and statistics

• Administer your instance data

• Perform CRUD (Create, Read, Update, and Delete) and search operations against your terminologies

• Execute advanced search operations such as paging, sorting, filtering, scripting, aggregations, and many others

Snow Owl® is a highly scalable, open source terminology server and collaborative authoring platform. It allows you to store, search and author high volumes of terminology artifacts quickly and efficiently.

Here are a few use-cases that Snow Owl could be used for:

• You work in the healthcare industry and are interested in using a terminology server for browsing, accessing and distributing components of various terminologies and classifications to third-party consumers. In this case, you can use Snow Owl to load the necessary terminologies and access them via FHIR and proprietary APIs.

Snow Owl requires Java 11 or newer version. Specifically as of this writing, it is recommended that you use JDK (Oracle of OpenJDK is preferred) version 11.0.2. Java installation varies from platform to platform so we won’t go into those details here. Oracle’s recommended installation documentation can be found on Oracle’s website. Suffice to say, before you install Snow Owl, please check your Java version first by running (and then install/upgrade accordingly if needed):

Once we have Java set up, we can then download and run Snow Owl. The binaries are available at the pages. For each release, you have a choice among a zip or tar archive, a DEB or RPM package.

Installation example with zip

There are a few concepts that are core to Snow Owl. Understanding these concepts from the outset will tremendously help ease the learning process.

Terminology / Code System

A terminology (also known as code system, classification and/or ontology) defines and encapsulates a set of terminology components (eg. set of codes with their meanings) and versions. A terminology is identified by a unique name and stored in a repository. Multiple code systems can exist in a single repository besides each other as long as their name is unique.

Terminology Component

A terminology component is a basic element in a code system with actual clinical meaning or use. For example in SNOMED CT, the Concept, Description, Relationship and Reference Set Member are terminology components.

Version

A version that refers to an important snapshot in time, consistent across many terminology components, also known as tag or label. It is often created when the state of the terminology is deemed to be ready to be published and distributed to downstream customers or for internal use. A version is identified by its version ID (or version tag) within a given code system.

Repository

A repository manages changes to a set of data over time in the form of revisions. Conceptually very similar to a source code repository (like a Git repository), but information stored in the repository must conform to a predefined schema (eg. SNOMED CT Concepts RF2 schema) as opposed to storing it in pure binary or textual format. This way a repository can support various full-text search functionalities, semantical queries and evaluations on the stored, revision-controlled terminology data.

A repository is identified by a name and this name is used to refer to the repository when performing create, read, update, delete and other operations against the revisions in it. Repositories organize revisions into branches and commits.

Revision

A revision is the basic unit of information stored in a repository about a terminology component or artifact. It contains two types of information:

• one is the actual data that you care about, for example a single code from a code system with its meaining and properties.

• the other is revision control information (aka revision metadata). Each revision is identified by a random Universally Unique IDentifier (UUID) that is assigned when performing a commit in the repository. Also, during a commit each revision is associated with a branch and timestamp. Revisions can be compared, restored, and merged.

Branch

A set of components under version control may be branched or forked at a point in time so that, from that time forward, two copies of those components may develop at different speeds or in different ways independently of each other. At later point in time the changes made on one of these branches can be merged into the other.

Branches are organized into hierarchies like directories in file systems. A child branch has access to all of the information that is stored on its parent branch up until its baseTimestamp, which is the time the branch was created. Each repository has a predefined root branch, called MAIN.

Commit

A commit represents a set of changes made against a branch in a repository. After a successful commit, the changes made by the commit are immediately available and searchable on the given branch.

Merge / Rebase

A merge/rebase is an operation in which two sets of changes are applied to set of components. A merge/rebase always happens between two branches, denoting one as the source and the other as the target of the operation.

Coming soon!

Snow Owl is both a simple and complex product. We’ve so far learned the basics of what it is, how to look inside of it, and how to work with it using some of the available APIs. Hopefully this tutorial has given you a better understanding of what Snow Owl is and more importantly, inspired you to further experiment with the rest of its great features!

Snow Owl uses SLF4J and Logback for logging.

The logging configuration file (serviceability.xml) can be used to configure Snow Owl logging. The logging configuration file location depends on your installation method, by default it is located in the ${SO_HOME}/configuration folder.

Extensive information on how to customize logging and all the supported appenders can be found on the Logback documentation.

Snow Owl uses a number of thread pools for different types of operations. It is important that it is able to create new threads whenever needed. Make sure that the number of threads that the Snow Owl user can create is at least 4096.

This can be done by setting ulimit -u 4096 as root before starting Snow Owl, or by setting nproc to 4096 in /etc/security/limits.conf.

The package distributions when run as services under systemd will configure the number of threads for the Snow Owl process automatically. No additional configuration is required.

Snow Owl uses a single data source, an Elasticsearch cluster (either embedded or external). To backup and restore the data, we highly recommend the official Snapshot and Restore feature from Elasticsearch. On top of that API, we highly recommend using tools, like Curator to ease the lifecycle management of your Elasticsearch cluster and your indices. See Curator here.

Below you can find a very simple guide on how to configure the backup and restore process for your Snow Owl Terminology Server using Curator.

Coming soon!

Coming soon!

Scheduler

# noop I/O scheduler, should be set in eg. /etc/rc.local for solid state disks:
echo noop > /sys/block/sdX/queue/scheduler

GET the ROOT concept:

curl 'http://localhost:8080/snowowl/snomedct/MAIN/concepts/138875005'

And the response:

{
  "id": "138875005",
  "released": true,
  "active": true,
  "effectiveTime": "20020131",
  "moduleId": "900000000000207008",
  "iconId": "138875005",
  "definitionStatus": "PRIMITIVE",
  "subclassDefinitionStatus": "NON_DISJOINT_SUBCLASSES"
}

Search by ECL:

curl 'http://localhost:8080/snowowl/snomedct/MAIN/concepts?active=true&ecl=%3C!138875005&limit=1'

And the response:

Snow Owl® is a highly scalable, open source terminology server with revision-control capabilities and collaborative authoring platform features. It allows you to store, search and author high volumes of terminology artifacts quickly and efficiently. If you’d like to see Snow Owl in action, the provides a managed terminology server and high-quality terminology content management from your web browser.

Let's import an RF2 release in SNAPSHOT mode so that we can further explore the available SNOMED CT APIs! To do so, use the appropriate request from the as follows (the second SNOMEDCT in the request path represents the code system identifier):

Curl will display the entire interaction between it and the server, including many request and response headers. We are interested in these two (response) rows in particular:

The first one indicates that the file was uploaded successfully and a resource has been created to track import progress, while the second row indicates the location of this resource.

Most operating systems try to use as much memory as possible for file system caches and eagerly swap out unused application memory. This can result in parts of the JVM heap or even its executable pages being swapped out to disk.

Swapping is very bad for performance, and should be avoided at all costs. It can cause garbage collections to last for minutes instead of milliseconds and can cause services to respond slowly or even time out.

There are two approaches to disabling swapping. The preferred option is to completely disable swap, but if this is not an option, you can minimize swappiness.

Snow Owl is provided in the following package formats:

You can manage and authenticate users with the built-in file realm. All the data about the users for the file realm is stored in the users file. The file is located in SO_PATH_CONF and is read on startup.

You need to explicitly select the file realm in the snowowl.yml configuration file in order to use it for authentication.

In the above configuration the file realm is using the users file to read your users from. Each row in the file represents a username and password delimited by : character. The passwords are BCrypt encrypted hashes. The default users file comes with a default

This section describes the use case scenarios present in the world of SNOMED CT and how Snow Owl can be used in those scenarios to maximize its full potential. Each scenario comes with a summary and a pros/cons section to help your decision making process when selecting the appropriate scenario for your use case.

An orderly shutdown of Snow Owl ensures that Snow Owl has a chance to cleanup and close outstanding resources. For example, an instance that is shutdown in an orderly fashion will initiate an orderly shutdown of the embedded Elasticsearch instance, gracefully close and disconnect connections and perform other related cleanup activities. You can help ensure an orderly shutdown by properly stopping Snow Owl.

If you’re running Snow Owl as a service, you can stop Snow Owl via the service management functionality provided by your installation.

If you’re running Snow Owl directly, you can stop Snow Owl by sending Ctrl-C if you’re running Snow Owl in the console, or by invoking the provided shutdown script as follows:

Snow Owl (with embedded Elasticsearch) uses a lot of file descriptors or file handles. Running out of file descriptors can be disastrous and will most probably lead to data loss. Make sure to increase the limit on the number of open files descriptors for the user running Snow Owl to 65,536 or higher.

For the .zip and .tar.gz packages, set ulimit -n 65536

When an Extension reaches the end of its current development cycle, it needs to be prepared for release and distribution.

Workflows and Authoring Branches

All planned content changes that are still on their dedicated branch either need to be integrated with the main development version or removed from the scope of the next release.

Multi Extension Authoring and Distribution

On top of single Edition/Extension distribution and authoring, Snow Owl provides full support for multi-SNOMED CT distribution and authoring even if the Extensions depend on different versions of the SNOMED CT International Edition.

To achieve a deployment like this you need to perform the same initialization steps for each desired SNOMED CT Extension as if it were a single extension scenario (see ). Development and maintenance of each managed extension can happen in parallel without affecting one or the other. Each of them can have their own release cycles, maintenance and upgrade schedules, and so on.

The following major differences, features and topics are worth mentioning when comparing features present in Snow Owl 7 and 8 and migrating an existing 7.x deployment to Snow Owl 8.x.

NOTE: It is highly recommended to keep the previous Snow Owl 7 deployment up and running until you have the data and all connected services migrated to the new version successfully. The new Snow Owl 8 system should get its own dedicated machine and deployment environment. Rolling back to the previous state should be available and must be executed when the upgrade cannot be performed successfully.

Database content

Code Systems maintained within Snow Owl are exposed (read-only) via the endpoints /CodeSystem and /CodeSystem/{codeSystemId}. Supported concept properties are handled and returned if requested. The currently exposed code systems are:

Snow Owl OSS:

• SNOMED CT

Snow Owl:

Detailed API documentation is coming soon! Until then we recommend to check out the official Swagger documentation available on your Snow Owl instance at .

This describes the resources that make up the official Snow Owl® CIS API.

This section includes information on how to setup Snow Owl and get it running, including:

• Downloading

• Installing

• Starting

• Configuring

Java (JVM) Version

Snow Owl is built using Java, and requires at least Java 11 in order to run. Only Oracle’s Java and the OpenJDK are supported. The same JVM version should be used on all Snow Owl nodes and clients.

We recommend installing Java version 11.0.x or a later version in the Java 11 release series. We recommend using a supported LTS version of Java.

The version of Java that Snow Owl will use can be configured by setting the JAVA_HOME environment variable.

You should rarely need to change Java Virtual Machine (JVM) options. If you do, the most likely change is setting the heap size.

The preferred method of setting JVM options (including system properties and JVM flags) is via the the SO_JAVA_OPTS environment variable. For instance:

export SO_JAVA_OPTS="$SO_JAVA_OPTS -Djava.io.tmpdir=/path/to/temp/dir"
./bin/startup

When using the RPM or Debian packages, SO_JAVA_OPTS can be specified in the system configuration file.

By default, Snow Owl is starting and connecting to an embedded Elasticsearch cluster available on http://localhost:9200. This cluster has only a single node and its discovery method is set to single-node, which means it is not able to connect to other Elasticsearch clusters and will be used exclusively by Snow Owl.

This single node Elasticsearch cluster can easily serve Snow Owl in testing, evaluation and small authoring environments, but it is recommended to customize how Snow Owl connects to an Elasticsearch cluster in larger environments (especially when planning to scale with user demand).

You have two options to configure Elasticsearch used by Snow Owl.

Configure the embedded instance

The first option is to configure the underlying Elasticsearch instance by editing the configuration file elasticsearch.yml, which depending on your installation is available in the configuration directory (you can create the file, if it is not available, Snow Owl will pick it up during the next startup).

Connect to a remote cluster

The second option is to configure Snow Owl to use a remote Elasticsearch cluster without the embedded instance. In order to use this feature you need to set the repository.index.clusterUrl configuration parameter to the remote address of your Elasticsearch cluster. When Snow Owl is configured to connect to a remote Elasticsearch cluster, it won't boot up the embedded instance, which reduces the memory requirements of Snow Owl slightly.

You can connect to self-hosted clusters or hosted solutions provided by and for example.

Two categories make up Snow Owl's Reference Set API:

1. Reference Sets category to get, search, create and modify reference sets

2. Reference Set Members category to get, search, create and modify reference set members

Basic operations like create, update, delete are supported for both category.

Actions API

On top of the basic operations, reference sets and members support actions. Actions have an action property to specify which action to execute, the rest of the JSON properties will be used as body for the Action.

Supported reference set actions are:

1. sync - synchronize all members of a query type reference set by executing their query and comparing the results with the current members of their referenced target reference set

Supported reference set member actions are:

1. create - create a reference set member (uses the same body as POST /members)

2. update - update a reference set member (uses the same body as PUT /members)

3. delete - delete a reference set member

For example the following will sync a query type reference set member's referenced component with the result of the reevaluated member's ESCG query

Bulk API

Members list of a single reference set can be modified by using the following bulk-like update endpoint:

Input

The request body should contain the commitComment property and a request array. The request array must contain actions (see Actions API) that are enabled for the given set of reference set members. Member create actions can omit the referenceSetId parameter, those will use the one defined as path parameter in the URL. For example by using this endpoint you can create, update and delete members of a reference set at once in one single commit.

ValueSet API

The endpoints /ValueSet and /ValueSet/{valueSetId} and corresponding operations expose all Value Set resources stored (or implict Value Sets if the corresponding Value Set plug-in supports it) in the server. CUD operations are not supported.

$expand

All value sets accessible via the /ValueSet endpoints can be expanded.

For SNOMED CT URIs, implicit value sets are supported:

• ?fhir_vs - all Concept IDs in the edition/version. If the base URI is http://snomed.info/sct, this means all possible SNOMED CT concepts

• ?fhir_vs=isa/[sctid] - all concept IDs that are subsumed by the specified Concept.

• ?fhir_vs=refset - all concept ids that correspond to real references sets defined in the specified SNOMED CT edition

The following in-parameters are supported:

• activeOnly - to return only active codes in the response

• filter - to filter the results lexically

• displayLanguage - to select the language for the returned display values

$validate-code

Codes can be validated against a given Value Set specified by the value set's logical id or canonical URL. In terms of Snow Owl terminology components, codes are validated against:

• SNOMED CT Simple Type Reference Sets with Concepts as referenced components.

• SNOMED CT Query Type Reference Sets with ECL expressions (each member is a Value Set)

• Snow Owl's generic Value Sets

Validation performs the following checks:

• The existence of the given Value Set (error if not found)

• The existence of the reference in the existing Value Set to the given code (error if not found)

• The existence of the given code in the system (error if not found)

Let’s start with a basic health check, which we can use to see how our instance is doing. We’ll be using curl to do this but you can use any tool that allows you to make HTTP/REST calls. Let’s assume that we are still on the same node where we started Snow Owl on and open another command shell window.

We will be using Snow Owl's to check its status. You can run the following command by clicking the "Copy" link on the right side and pasting it into a terminal.

And the response:

We can see the installed version along with available repositories, their overall health (eg. "snomed" with health "GREEN"), associated indices and status (eg. "snomed-relationship"

This describes the resources that make up the official Snow Owl® SNOMED CT Terminology API.

The method for starting Snow Owl varies depending on how you installed it.

Archive packages (.tar.gz, .zip)

If you installed Snow Owl with a .tar.gz or zip package, you can start Snow Owl from the command line.

Authoring is the process by which content is created in an extension in accordance with a set of authoring principles. These principles ensure the quality of content and referential integrity between content in the extension and content in the International Edition (the principles are set by SNOMED International, can be found ).

During the extension development process authors are:

• creating, modifying or inactivating content according to editorial principles and policies

Compare API

Comparison for current terminology changes committed to a source or target branch can be conducted by creating a compare resource.

A review identifier can be added to merge requests as an optional property. If the source or target branch state is different from the values captured when creating the review, the merge/rebase attempt will be rejected. This can happen, for example, when additional commits are added to the source or the target branch while a review is in progress; the review resource state becomes STALE in such cases.

Reviews and concept change sets have a limited lifetime. CURRENT reviews are kept for 15 minutes, while review objects in any other states are valid for 5 minutes by default. The values can be changed in the server's configuration file.

ConceptMap API

The endpoints /ConceptMap and /ConceptMap/{conceptMapId} and corresponding operations expose the following types of terminology resources:

Now that we have a code system, let's take a look at its content! We can list concepts using either the tailored to this tooling, or the for a representation that is uniform across different kinds of code systems. For the sake of simplicity, we will use the former in this example.

To list all available concepts in a code system, use the following command (just as with importing, the second SNOMEDCT in the request path represents the code system identifier):

The expected response is:

The concept list is empty, indicating that we haven't imported anything into Snow Owl - yet.

Snow Owl is a multi-purpose terminology server with a main focus on SNOMED CT International Edition and its Extensions. Whether you are a producer of a SNOMED CT Extension or a consumer of one, Snow Owl has you covered. As always, feel free to ask your questions regarding any of the content you read here (raise a ticket on GitHub Issues).

Snow Owl Concepts

Snow Owl uses the following basic concepts to provide authoring and maintenance support for SNOMED CT Extensions.

Code Systems

From the page, we've learned what is a Repository and how Code Systems are defined as part of a Repository.

SNOMED CT Extensions in Snow Owl are basically Code Systems with their own set of properties and characteristics. With Snow Owl's Code System API, a Code System can be created for each SNOMED CT Extension to easily identify the Code System and its components with a single unique identifer, called the Code System short name. The recommended naming approach when selecting the unique short name identifier is the following:

• SNOMED CT International Edition: SNOMEDCT - often included in other editions for distribution purposes

• National Release Center (single maintained extension) - SNOMEDCT-US - represents the SNOMED CT United States of America Extension

• National Release Center (multiple maintained extensions) -

The primary namespace identifer and set of modules and languages can be set during the creation of the Code System, and can be updated later on if required. These properties can be used when users are accessing the terminology server for authoring purposes to provide a seamless authoring experience for the user without them needing to worry about selecting the proper namespace, modules, language tags, etc. (NOTE: this feature is not available yet in the OSS version of Snow Owl)

Extension Of

A Snow Owl Code System can be marked as an extensionOf another Code System, which ties them together, forming a dependency between the two Code Systems. A Code System can have multiple Extension Code Systems, but a Code System can only be extensionOf a single Code System.

Branching

In Snow Owl, a Repository maintains a set of branches and Code Systems are always attached to a dedicated branch. For example, the default root Code Systems are always tied to the default branch, called MAIN. When creating a new Code System, the "working" branchPath can be specified and doing so assigns the branch to the Code System. A Code System cannot be attached to multiple branches at the same time, and a branch can only be assigned to a single Code System in a Repository. Snow Owl's branching infrastructure allows the use of isolated environments for both distribution and authoring workflows, therefore they play crucial role in SNOMED CT Extension managament as well. They also provide the support for seamless upgrade mechanism, which can be done whenever there is a new version available in one of your SNOMED CT Extension's dependent Code Systems.

Versions

As in real life, a Code System can have zero or more versions (or with another name, releases). A version is a special branch that is created during the versioning process and makes the currently available latest content accessible later in its current form. Since SNOMED CT Extensions can have releases as well, creating a Code System Version in Snow Owl is a must in order to produce the release packages.

Examples

The following image shows the repository content rendered from the available commits, after a successful International Edition import.

Dots represent commits made with the commit message on the right. Green boxes represent where the associated branch's HEAD is currently located. Blue tag labels represent versions created during the commit.

If your use case would be to import the SNOMED CT US Extension 2019-09-01 version into this repository, then ideally it would look like this:

The next section describes the use case scenarios in the world of SNOMED CT and the recommended approaches for deploying these scenarios in Snow Owl.

Now let's take a peek at our code systems:

curl http://localhost:8080/snowowl/codesystems?pretty

The response:

...it sure looks empty! This is expected, as Snow Owl does not contain any predefined code system metadata out of the box. We can create the first code system with the following request:

The request body includes:

• The code system identifier "SNOMEDCT"

• Various pieces of metadata offering a human-readable title, ownership and contact information, code system status, URL and OID for identification, etc.

• The tooling identifier "snomed" that points to the repository that will store content

If everything goes well, the command will run without any errors (the server returns a "204 No Content" response). We can double-check that code system metadata has been registered correctly with the following request:

The expected response is:

In addition to the submitted values, you will find that additional administrative properties also appear in the output. One example is branchPath which specifies the working branch of the code system within the repository.

The most common use case to consume a SNOMED CT Release Package is to import it directly into a Terminology Server (like Snow Owl) and make it available as read-only content for both human and machine access (via REST and FHIR APIs).

SNOMED CT International Edition

Since Snow Owl by default comes with a pre-initialized SNOMED CT Code System called SNOMEDCT, it is just a single call to import the official RF2 package using the SNOMED CT RF2 Import API The import by default creates a Code System Version for each SNOMED CT Effective Date available in the supplied RF2 package. After a successful import the content is immediately available via REST and FHIR APIs.

SNOMED CT Extension Edition

National Release Centers and other Care Providers provide their own SNOMED CT Edition distribution for third-party consumers in RF2 format. Importing their Edition distribution instead of the International Edition directly into the SNOMEDCT pre-initialized SNOMED CT Code System with the same makes both the International Edition (always included in Edition packages) and the National Extension available for read-only access.

Summary

The single edition scenario without much effort provides access to any SNOMED CT Edition directly on the pre-initialized SNOMEDCT Code System. It is easy to set up and maintain. Because of its flat structure, it is good for distribution and extension consumers. Although it can be used for authoring in certain scenarios, due to the missing distinction between the International Edition and the Extension, it is not the best choice for extension authoring and maintenance.

#

Pros:

• Good for maintaining the SNOMED CT International Edition

• Good for distribution

• Simple to set up and maintain

Cons:

• Not recommended for extension authoring and maintenance

• Not recommended for multi-extension distribution scenarios

While Snow Owl requires very little configuration, there are a number of settings which need to be considered before going into production.

The following settings must be considered before going to production:

Elasticsearch settings

By default, Snow Owl includes the OSS version of Elasticsearch and runs it in embedded mode to store terminology data and make it available for search. This is convenient for single node environments (eg. for evaluation, testing and development), but it might not be sufficient when you go into production.

To configure Snow Owl to connect to an Elasticsearch cluster, change the clusterUrl property in the snowowl.yml configuration file:

The value for this setting should be a valid HTTP URL point to the HTTP API of your Elasticsearch cluster, which by default runs on port 9200.

Path settings

If you are using the .zip or .tar.gz archives, the data and logs directories are sub-folders of $SO_HOME. If these important folders are left in their default locations, there is a high risk of them being deleted while upgrading Snow Owl to a new version.

In production use, you will almost certainly want to change the locations of the data and log folders.

The RPM and Debian distributions already use custom paths for data and logs.

Network settings

To allow clients to connect to Snow Owl, make sure you open access to the following ports:

• 8080/TCP:: Used by Snow Owl Server's REST API for HTTP access

• 8443/TCP:: Used by Snow Owl Server's REST API for HTTPS access

• 2036/TCP:: Used by the Net4J binary protocol connecting Snow Owl clients to the server

Setting the heap size

By default, Snow Owl tells the JVM to use a heap with a minimum and maximum size of 2 GB. When moving to production, it is important to configure heap size to ensure that Snow Owl has enough heap available.

To configure the heap size settings, change the -Xms and -Xmx settings in the SO_JAVA_OPTS environment variable.

The value for these setting depends on the amount of RAM available on your server and whether you are running Elasticsearch on the some node as Snow Owl (either embedded or as a service) or running it in its own cluster. Good rules of thumb are:

• Set the minimum heap size (Xms) and maximum heap size (Xmx) to be equal to each other.

• Too much heap can subject to long garbage collection pauses.

• Set Xmx

Snow Owl security features enable you to easily secure your terminology server. You can password-protect your data as well as implement more advanced security measures such as role-based access control and auditing.

Realms

By default Snow Owl comes without any security features enabled and all read and write operations are unprotected. To configure a security realm, you can choose from the following built-in identity providers:

Maintenance of a SNOMED CT Extension is essential to ensure that

• it incorporates changes requested by terminology consumers

• it remains aligned with the SNOMED CT International Edition

While both of these maintenance related tasks are potentially assigned to one of the upcoming Extension development cycles, there is a clear distinction between the two maintenance tasks.

Introduction

The Snow Owl Terminology Server is capable of managing multiple SNOMED CT extensions for both distribution and authoring purposes in a single deployment. This guide describes the typical scenarios, like creating, managing, releasing and upgrading SNOMED CT Extensions in great detail with images. If you are unfamiliar with SNOMED CT Extensions, the next section walks you through their logical model and basic characteristics, while the following pages describe distribution and authoring scenarios as well as how to use the Snow Owl Terminology Server for SNOMED CT Extensions.

Extensions and Snow Owl

What is a SNOMED CT Extension?

Common Structure

SNOMED CT is a multilingual clinical terminology that covers a broad scope. However, some users may need additional concepts, relationships, descriptions or reference sets to support national, local or organizational needs.

The extension mechanism allows SNOMED CT to be customized to address the terminology needs of a country or organization that are not met by the International Edition.

A SNOMED CT Extension may contain components and/or derivatives (e.g. reference sets used to represent subsets, maps or language preferences). Since the international edition and all extensions share a common structure, the same application software can be used to enter, store and process information from different extensions. Similarly, reference sets can be constructed to refer to content from both the international release and extensions. The common structure also makes it easier for content developed by an extension producer to be submitted for possible inclusion in a National Edition or the International Edition.

Therefore, a SNOMED CT Extension uses the same Release Format version 2 as the International Edition, they share a common structure and schema (see ).

Namespace

Extensions are managed by SNOMED International, and Members or Affiliate Licensees who have been issued a namespace identifier by SNOMED International. A namespace identifier is used to create globally unique SNOMED CT identifiers for each component (i.e. concept, description and relationship) within a Member or Affiliate extension. This ensures that references to extension concepts contained in health record data are unambiguous and can be clearly attributed to a specific issuing organization.

A national or local extension uses a namespace identifier issued by SNOMED International to ensure that all extension components can be uniquely identified (across all extensions).

Therefore, a SNOMED CT Extension uses a single namespace identifier to identify all core components in the SNOMED CT Extension (see ).

Modules

Every SNOMED CT Extension includes one or more modules, and each module contains either SNOMED CT components or reference sets (or both). Modules may be dependent on other modules. A SNOMED CT Edition includes the contents of a focus module together with the contents of all the modules on which it depends. This includes the modules in the International Edition and possibly other modules from a national and/or local extension.

An edition is defined based on a single focus module. This focus module must be the most dependent module, in that the focus module is dependent on all the other modules in the edition.

Therefore, a SNOMED CT Extension uses one or more modules to categorize the components into meaningful groups (see ).

Language

SNOMED CT extensions can support a variety of use cases, including:

Translating SNOMED CT, for example

• Adding terms used in a local language or dialect

• Adding terms used by a specific user group, such as patient-friendly terms

Representing language, dialect or specialty-specific term preferences is possible using a SNOMED CT extension. The logical design of SNOMED CT enables a single clinical idea to be associated with a range of terms or phrases from various languages, as depicted in Figure 3.1-1 below. In an extension, terms relevant for a particular country, speciality, hospital (or other organization) may be created, and different options for term preferences may be specified. Even within the same country, different regional dialects or specialty-specific languages exist may influence which synonyms are preferred. SNOMED CT supports this level of granularity for language preferences at the national or local level.

Therefore, an Extension can have its own language to support patient-friendly terms, local user groups, etc. (see ).

Dependency

A SNOMED CT extension is a set of components and reference set members that add to the SNOMED CT International Edition. An extension is created, structured, maintained and distributed in accordance with SNOMED CT specifications and guidelines. Unlike, the International Edition an extension is not a standalone terminology. The content in an extension depends on the SNOMED CT International Edition, and must be used together with the International Edition and any other extension module on which it depends.

Therefore, a SNOMED CT Extension depends on the SNOMED CT International Edition directly or indirectly through another SNOMED CT Extension (see ).

Versions

A specific version of an extension can be referred to using the date on which the extension was published.

There are many use cases that require a date specific version of an edition, including specifying the substrate of a SNOMED CT query, and specifying the version of SNOMED CT used to code a specific data element in a health record. A versioned edition includes the contents of the specified version of the focus module, plus the contents of all versioned modules on which the versioned focus module depends (as specified in the |Module dependency reference set|). The version of an edition is based on the date on which the edition was released. Many extension providers release their extensions as a versioned edition, using regular and predictable release cycles.

Therefore, a SNOMED CT Extension can be versioned and have a different release cycle than the SNOMED CT International Edition (see ).

Characteristics

To summarize, a SNOMED CT Extension has the following characteristics:

• Uses the same RF2 structure as the SNOMED CT International Edition

• Uses a single namespace identifer to globally identify its content

• Uses one or more modules to categorize the content into groups

Now that we have a clear understanding of what SNOMED CT Extensions are, let's take a look at how can we use them in Snow Owl.

The RPM for Snow Owl can be downloaded from the Downloads section. It can be used to install Snow Owl on any RPM-based system such as OpenSuSE, SLES, Centos, Red Hat, and Oracle Enterprise.

Download and install

Running Snow Owl with SysV init

Use the chkconfig command to configure Snow Owl to start automatically when the system boots up:

Snow Owl can be started and stopped using the service command:

If Snow Owl fails to start for any reason, it will print the reason for failure to STDOUT. Log files can be found in /var/log/snowowl/.

Running Snow Owl with systemd

To configure Snow Owl to start automatically when the system boots up, run the following commands:

Snow Owl can be started and stopped as follows:

These commands provide no feedback as to whether Snow Owl was started successfully or not. Instead, this information will be written in the log files located in /var/log/snowowl/.

Checking that Snow Owl is running

You can test that your Snow Owl instance is running by sending an HTTP request to:

which should give you a response something like this:

Configuring Snow Owl

Snow Owl defaults to using /etc/snowowl for runtime configuration. The ownership of this directory and all files in this directory are set to root:snowowl on package installation and the directory has the setgid flag set so that any files and subdirectories created under /etc/snowowl are created with this ownership as well (e.g., if a keystore is created using the keystore tool). It is expected that this be maintained so that the Snow Owl process can read the files under this directory via the group permissions.

Snow Owl loads its configuration from the /etc/snowowl/snowowl.yml file by default. The format of this config file is explained in .

Directory layout of RPM

The RPM places config files, logs, and the data directory in the appropriate locations for an RPM-based system:

Next steps

You now have a test Snow Owl environment set up. Before you start serious development or go into production with Snow Owl, you must do some additional setup:

• Learn how to .

• Configure .

• Configure .

Snow Owl is provided as a .zip and as a .tar.gz package. These packages can be used to install Snow Owl on any system and are the easiest package format to use when trying out Snow Owl.

The latest stable version of Snow Owl can be found on the Snow Owl Releases page.

Download and install the zip package

The .zip archive for Snow Owl can be downloaded and installed as follows:

Download and install the .tar.gz package

The .tar.gz archive for Snow Owl can be downloaded and installed as follows:

Running Snow Owl from the command line

Snow Owl can be started from the command line as follows:

By default, Snow Owl runs in the foreground, prints its logs to the standard output (stdout), and can be stopped by pressing Ctrl-C.

Checking that Snow Owl is running

You can test that your instance is running by sending an HTTP request to Snow Owl's status endpoint:

which should give you a response like this:

Running in the background

You can send the Snow Owl process to the background using the combination of nohup and the & character:

Log messages can be found in the $SO_HOME/serviceability/logs/ directory.

To shut down Snow Owl, you can kill the process ID directly:

or using the provided shutdown script:

Directory layout of .zip and .tar.gz archives:

The .zip and .tar.gz packages are entirely self-contained. All files and directories are, by default, contained within $SO_HOME — the directory created when unpacking the archive.

This is very convenient because you don’t have to create any directories to start using Snow Owl, and uninstalling Snow Owl is as easy as removing the $SO_HOME directory. However, it is advisable to change the default locations of the config directory, the data directory, and the logs directory so that you do not delete important data later on.

Next steps

You now have a test Snow Owl environment set up. Before you start serious development or go into production with Snow Owl, you must do some additional setup:

• Learn how to .

• Configure .

• Configure .

Snow Owl provides branching support for terminology repositories. In each repository there is an always existing and UP_TO_DATE branch called MAIN. The MAIN branch represents the latest working version of your terminology (similar to a master branch on GitHub).

You can create your own branches and create/edit/delete components and other resources on them. Branches are identified with their full path, which should always start with MAIN. For example the branch MAIN/a/b/c/d represents a branch under the parent MAIN/a/b/c with name d.

Later you can decide to either delete the branch or merge the branch back to its parent. To properly merge a branch back into its parent, sometimes it is required to rebase (synchronize) it first with its parent to get the latest changes. This can be decided via the state attribute of the branch, which represents the current state compared to its parent state.

Branch states

There are five different branch states available:

1. UP_TO_DATE - the branch is up-to-date with its parent there are no changes neither on the branch or on its parent

2. FORWARD - the branch has at least one commit while the parent is still unchanged. Merging a branch requires this state, otherwise it will return a HTTP 409 Conflict.

3. BEHIND - the parent of the branch has at least one commit while the branch is still unchanged. The branch can be safely rebased with its parent.

Basics

Get a branch

Response

Get all branches

Response

Create a branch

Input

Response

Delete a branch

Response

Merging

Perform a merge

Input

Response

Perform a rebase

Input

Response

Monitor progress of a merge or rebase

Response

Remove merge or rebase queue item

Response

The Debian package for Snow Owl can be downloaded from the Downloads section. It can be used to install Snow Owl on any Debian-based system such as Debian and Ubuntu.

Download and install

Running Snow Owl with SysV init

Use the update-rc.d command to configure Snow Owl to start automatically when the system boots up:

Snow Owl can be started and stopped using the service command:

If Snow Owl fails to start for any reason, it will print the reason for failure to STDOUT. Log files can be found in /var/log/snowowl/.

Running Snow Owl with systemd

To configure Snow Owl to start automatically when the system boots up, run the following commands:

Snow Owl can be started and stopped as follows:

These commands provide no feedback as to whether Snow Owl was started successfully or not. Instead, this information will be written in the log files located in /var/log/snowowl/.

Checking that Snow Owl is running

You can test that your Snow Owl instance is running by sending an HTTP request to:

which should give you a response something like this:

Configuring Snow Owl

Snow Owl defaults to using /etc/snowowl for runtime configuration. The ownership of this directory and all files in this directory are set to root:snowowl on package installation and the directory has the setgid flag set so that any files and subdirectories created under /etc/snowowl are created with this ownership as well (e.g., if a keystore is created using the keystore tool). It is expected that this be maintained so that the Snow Owl process can read the files under this directory via the group permissions.

Snow Owl loads its configuration from the /etc/snowowl/snowowl.yml file by default. The format of this config file is explained in .

Directory layout of Debian package

The Debian package places config files, logs, and the data directory in the appropriate locations for a Debian-based system:

Next steps

You now have a test Snow Owl environment set up. Before you start serious development or go into production with Snow Owl, you must do some additional setup:

• Learn how to .

• Configure .

• Configure .

Ideally, Snow Owl should run alone on a server and use all of the resources available to it. In order to do so, you need to configure your operating system to allow the user running Snow Owl to access more resources than allowed by default.

The following settings must be considered before going to production:

• Disable swapping

Configuring system settings

Where to configure systems settings depends on which package you have used to install Snow Owl, and which operating system you are using.

When using the .zip or .tar.gz packages, system settings can be configured:

• temporarily with , or

• permanently in .

When using the RPM or Debian packages, most system settings are set in the system configuration file. However, systems which use systemd require that system limits are specified in a systemd configuration file.

ulimit

On Linux systems, ulimit can be used to change resource limits on a temporary basis. Limits usually need to be set as root before switching to the user that will run Snow Owl. For example, to set the number of open file handles (ulimit -n) to 65,536, you can do the following:

The new limit is only applied during the current session.

You can consult all currently applied limits with ulimit -a.

/etc/security/limits.conf

On Linux systems, persistent limits can be set for a particular user by editing the /etc/security/limits.conf file. To set the maximum number of open files for the snowowl user to 65,536, add the following line to the limits.conf file:

This change will only take effect the next time the snowowl user opens a new session.

Sysconfig file

When using the RPM or Debian packages, system settings and environment variables can be specified in the system configuration file, which is located in:

However, for systems which uses systemd, system limits need to be specified via systemd.

Systemd configuration

When using the RPM or Debian packages on systems that use systemd, system limits must be specified via systemd.

The systemd service file (/usr/lib/systemd/system/snowowl.service) contains the limits that are applied by default.

To override them, add a file called /etc/systemd/system/snowowl.service.d/override.conf (alternatively, you may run sudo systemctl edit snowowl which opens the file automatically inside your default editor). Set any changes in this file, such as:

Once finished, run the following command to reload units:

Prerequisites

Please refer to the official Curator install guide on how to install it on various operating systems.

Configure Snapshot repository

In order to create backups for Snow Owl, you need a repository in your Elasticsearch cluster.

To create a repository (assuming shared file system repository, fs), execute the following command:

Elasticsearch requires that the specified /path/to/shared/mount is whitelisted in the path.repo configuration setting in the elasticsearch.yml configuration file. See section of the Elasticsearch reference for details.

Curator configuration file

Curator requires a single configuration file to be specified when running it. If you are using a default Elasticsearch cluster with default configurations then the default Curator recommended file should be sufficient. Any configuration changes you have made to your Elasticsearch cluster needs to be changed here as well in this config file so Curator can access your cluster without any issues.

Example curator.yml:

Snapshot Action

Curator is using action YML files to perform a set of actions sequentially. See the available steps here: https://www.elastic.co/guide/en/elasticsearch/client/curator/5.8/actions.html

A Snapshot Action that can be used to backup the content from a Snow Owl Terminology Server.

Example snowowl_snapshot.yml file:

To execute a Snapshot action manually, you can use the following command:

Restore Action

A Restore Action that can be used to restore the latest snapshot (aka backup) to the Snow Owl Terminology Server.

Example snowowl_restore.yml file:

To execute a Restore action manually, you can use the following command:

Taking scheduled backups

To schedule automated backups, you can use on Unix-style operating systems to automate the job. The back up interval depends on your use case and how you are accessing the data. If you have a write-heavy scenario, we recommend a hourly backup interval, otherwise some value between hourly - daily is preferable.

An example crontab entry that initiates a daily backup at 03:00, and captures Curator's output to /var/log/backup.log (both standard output and standard error) would look like this:

You can configure security to communicate with a Lightweight Directory Access Protocol (LDAP) server to authenticate and authorize users.

To integrate with LDAP, you configure an ldap realm in the snowowl.yml configuration file.

Configuration

The following configuration settings are supported:

The default configuration values are selected to support both OpenLDAP and Active Directory without needing to customize the default schema that comes with their default installation.

Configure Authentication

When users send their username and password with their request in the Authorization header, the LDAP security realm performs the following steps to authenticate the user:

1. Searches for a user entry in the configured baseDn to get the DN

2. Authenticates with the LDAP instance using the received DN and the provided password

If any of the above-mentioned steps fails for any reason, the user is not allowed to access the terminology server's content and the server will respond with HTTP 401 Unauthorized.

To configure authentication, you need to configure the uri, baseDn, bindDn, bindDnPassword, userObjectClass and userIdProperty configuration settings.

Adding a user

To add a user in the LDAP realm, create an entry under the specified baseDn using the configured userObjectClass as class and the userIdProperty as the property where the user's username/e-mail address is configured.

Example user entry:

Configure Authorization

On top of the authentication part, the LDAP realm provides configuration values to support full role-based access control and authorization.

When a user's request is successfully authenticated with the LDAP realm, Snow Owl authorizes the request using the user's currently set roles and permissions in the configured LDAP instance.

Adding a role

To add a role in the LDAP realm, create an entry under the specified baseDn using the configured roleObjectClass as class and the configured permissionProperty and memberProperty properties for permission and user mappings, respectively.

Example read-only role:

FHIR API

Fast Healthcare Interoperability Resources (FHIR) specifies resources, operations, coded data types and terminologies that are used for representing and communicating coded, structured data in the FHIR core specification within its Terminology Module.

Snow Owl's pluggable and extensible architecture allows modular development of the FHIR API both in terms of the supported functionality as well as the exposed terminologies. Additionally, Snow Owl's revision-based model allows the concurrent management of multiple versions.

Snow Owl uses a mmapfs directory by default to store its data. The default operating system limits on mmap counts is likely to be too low, which may result in out of memory exceptions.

On Linux, you can increase the limits by running the following command as root:

To set this value permanently, update the vm.max_map_count setting in /etc/sysctl.conf. To verify after rebooting, run sysctl vm.max_map_count.

The RPM and Debian packages will configure this setting automatically. No further configuration is required.