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

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.

To check the instance status/health, we will be using the Admin API. You can run the command by clicking the "Copy" link on the right side and pasting it into a terminal.

curl http://localhost:8080/snowowl/admin/info

And the response:

{
  "version": "<version>",
  "description": "You Know, for Terminologies",
  "repositories": {
    "items": [
      {
        "id": "snomedStore",
        "health": "GREEN"
      }
    ]
  }
}

In the response, we can see the version of our instance along with the available repositories and their health status (eg. SNOMED CT with status GREEN).

Whenever we ask for the status, we either get GREEN, YELLOW, or RED and an optional diagnosis message.

• Green - everything is good (repository is fully functional)

• Yellow - some data or functionality is not available, or diagnostic operation is in progress (repository is partially functional)

• Red - diagnostic operation required in order to continue (repository is not functional)

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.

• You are responsible for maintaining and publishing new versions of a particular terminology. In this case, you can use Snow Owl to collaboratively access and author the terminology content and at the end of your release schedule publish it with confidence and zero errors.

• You have an Electronic Health Record system and would like to capture, maintain and query clinical information in a structured and standardized manner. Your Snow Owl terminology server can integrate with your EHR server via standard APIs to provide the necessary access for both terminology binding and data processing and analytics.

In this tutorial, you will be guided through the process of getting Snow Owl up and running, taking a peek inside it, and performing basic operations like importing SNOMED CT RF2 content, searching, and modifying your data. At the end of this tutorial, you should have a good idea of what Snow Owl is, how it works, and hopefully be inspired to see how you can use it for your needs.

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

curl http://localhost:8080/snowowl/admin/codesystems

And the response:

{
  "items": [
    {
      "oid": "2.16.840.1.113883.6.96",
      "name": "SNOMED CT",
      "shortName": "SNOMEDCT",
      "organizationLink": "http://www.snomed.org",
      "primaryLanguage": "ENG",
      "citation": "SNOMED CT contributes to the improvement of patient care by underpinning the development of Electronic Health Records that record clinical information in ways that enable meaning-based retrieval. This provides effective access to information required for decision support and consistent reporting and analysis. Patients benefit from the use of SNOMED CT because it improves the recording of EHR information and facilitates better communication, leading to improvements in the quality of care.",
      "branchPath": "MAIN",
      "iconPath": "icons/snomed.png",
      "terminologyId": "com.b2international.snowowl.terminology.snomed",
      "repositoryUuid": "snomedStore"
    }
  ]
}

Which means, we have a single Code System in Snow Owl, called SNOMED CT. It has been created by the SNOMED CT module by default on the first startup of your instance. A Code System lives in a repository and its working branchPath is currently associated with the default MAIN branch in the snomedStore repository.

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.

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):

java -version
echo $JAVA_HOME

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

Installation example with zip

For simplicity, let's use a zip file.

Let's download the most recent Snow Owl release as follows:

curl -L -O https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.zip

Then extract it as follows:

unzip snow-owl-oss-<version>.zip

It will then create a bunch of files and folders in your current directory. We then go into the bin directory as follows:

cd snow-owl-oss-<version>/bin

And now we are ready to start the instance:

./startup

Successfully running instance

If everything goes well with the installation, you should see a bunch of log messages that look like below:

TODO example output

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!

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.

GET the ROOT concept:

curl 'http://localhost:8080/snowowl/snomed-ct/v3/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/snomed-ct/v3/MAIN/concepts?active=true&ecl=%3C!138875005&limit=1'

And the response:

{
  "items": [
    {
      "id": "308916002",
      "released": true,
      "active": true,
      "effectiveTime": "20020131",
      "moduleId": "900000000000207008",
      "iconId": "138875005",
      "definitionStatus": "PRIMITIVE",
      "subclassDefinitionStatus": "NON_DISJOINT_SUBCLASSES"
    }
  ],
  "searchAfter": "AoE_BWVlYzI3Mjc0LTYyZTctNDg3NS05NmVlLThhNTk3OTcxOTJiNw==",
  "limit": 1,
  "total": 19
}

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.

Introduction

Features include:

• Revision-controlled authoring

  • Maintains multiple versions (including unpublished and published) for each terminology artifact and provides APIs to access them all

  • Independent work branches offer work-in-process isolation, external business workflow integration and team collaboration

• SNOMED CT and others

  • Full SNOMED CT terminology support (full RF2 support, ECL v1.3, SCG 2.3.1, ETL 1.0, Reference Sets, OWL Axioms, OWL 2 EL/DL support, experimental Query Language)

  • With its modular design, the server can maintain multiple terminologies (including local codes, mapping sets, value sets)

• Various set of APIs

  • SNOMED CT API (RESTful and native Java API)

  • FHIR API

  • CIS API

• Highly extensible and configurable

  • Simple to use plug-in system makes it easy to develop and add new terminology tooling/API or any other functionality

• Built on top of Elasticsearch (highly scalable, distributed, open source search engine)

  • Connect to your existing cluster or use the embedded instance

  • All the power of Elasticsearch is available (full-text search support, monitoring, analytics and many more)

Download

• WINDOWS - sha

• MACOS/LINUX - sha

• RPM - sha

• DEB - sha

View the detailed release notes here.

Not the version you're looking for? View past releases.

Install and Run

NOTE: You need to have a recent version of Java installed (Java 11+, https://jdk.java.net/archive/).

Once you have downloaded the appropriate package:

• Run bin/snowowl.sh on unix, or bin/snowowl.bat on windows

• Run curl http://localhost:8080/snowowl/admin/info

• Navigate to http://localhost:8080/snowowl

• See SNOMED CT API docs, FHIR API docs

Learn Snow Owl

• Getting Started

• Set up Snow Owl

• Configuring Snow Owl

• FHIR API

• SNOMED CT API

• Admin API

Building from source

Snow Owl uses Maven for its build system. In order to create a distribution, simply run the following command in the cloned directory.

mvn clean package

The distribution packages can be found in the releng/com.b2international.snowowl.server.update/target folder, when the build is complete.

To run the test cases, use the following command:

mvn clean verify

Development

These instructions will get Snow Owl up and running on your local machine for development and testing purposes.

Prerequisites

Snow Owl is an Equinox-OSGi based server. To develop plug-ins for Snow Owl you need to use Eclipse as IDE:

• Use latest Eclipse IDE for Eclipse Committers package: http://www.eclipse.org/downloads/eclipse-packages/

Required Eclipse plug-ins (install the listed features via Help -> Install New Software...):

Note: you may have to untick the Show only the latest versions of the available software checkbox to get older versions of a feature. Please use the exact version specified below, not the latest point release.

• Xtext/Xtend (http://download.eclipse.org/modeling/tmf/xtext/updates/composite/releases/)

  • MWE 2 language SDK 2.10.0 (MWE)

  • Xtend IDE 2.18.0 (Xtext)

  • Xtext Complete SDK 2.18.0 (Xtext)

• Maven integration (http://download.eclipse.org/technology/m2e/releases)

Eclipse Preferences

Make sure you have the following preferences enabled/disabled.

• Plug-in development API baseline errors is set to Ignored (Preferences > Plug-in Development > API Baselines)

• The Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-clean-plugin:2.5:clean type of errors can be ignored or changed to Warnings in Preferences->Maven->Errors/Warnings.

• Set the workspace encoding to UTF-8 (Preferences->General->Workspace)

• Set the line endings to Unix style (Preferences->General->Workspace)

Git configuration

• Make sure the Git line endings are set to input (Preferences->Team->Git->Configuration - add key if missing core.autocrlf = input)

First steps

1. Import all projects into your Eclipse workspace and wait for the build to complete

2. Select all projects and hit Alt + F5 and trigger an update to all Maven projects manually (to download dependencies from Maven)

3. Open the target-platform/target-platform-local.target file

4. Wait until Eclipse resolves the target platform (click on the Resolve button if it refuses to do so) and then click on Set as Active Target platform

5. Wait until the build is complete and you have no compile errors

6. Launch snow-owl-oss launch configuration in the Run Configurations menu

7. Navigate to http://localhost:8080/snowowl

Contributing

Please see CONTRIBUTING.md for details.

Versioning

Our releases use semantic versioning. You can find a chronologically ordered list of notable changes in CHANGELOG.md.

License

This project is licensed under the Apache 2.0 License. See LICENSE for details and refer to NOTICE for additional licensing notes and uses of third-party components.

Acknowledgements

In March 2015, SNOMED International generously licensed the Snow Owl Terminology Server components supporting SNOMED CT. They subsequently made the licensed code available to their members and the global community under an open-source license.

In March 2017, NHS Digital licensed the Snow Owl Terminology Server to support the mandatory adoption of SNOMED CT throughout all care settings in the United Kingdom by April 2020. In addition to driving the UK’s clinical terminology efforts by providing a platform to author national clinical codes, Snow Owl will support the maintenance and improvement of the dm+d drug extension which alone is used in over 156 million electronic prescriptions per month. Improvements to the terminology server made under this agreement will be made available to the global community.

Many other organizations have directly and indirectly contributed to Snow Owl, including: Singapore Ministry of Health; American Dental Association; University of Nebraska Medical Center (USA); Federal Public Service of Public Health (Belgium); Danish Health Data Authority; Health and Welfare Information Systems Centre (Estonia); Department of Health (Ireland); New Zealand Ministry of Health; Norwegian Directorate of eHealth; Integrated Health Information Systems (Singapore); National Board of Health and Welfare (Sweden); eHealth Suisse (Switzerland); and the National Library of Medicine (USA).

Now that we have a SNOMED CT Code System, let's take a look at its content. We can query its content using either the or the .

For sake of simplicity, let's search for the available concepts using the . For that we will need the branch we would like to query, but fortunately we already know the value from our previous call to the Code Systems API, it was MAIN. To list all available concepts in a SNOMED CT Code System, use the following command:

curl http://localhost:8080/snowowl/snomed-ct/v3/MAIN/concepts

And the response is:

{
  "items": [],
  "limit": 50,
  "total": 0
}

Which simply means we have no SNOMED CT concepts yet in our instance.

Now let's import an official SNOMED CT RF2 SNAPSHOT distribution archive so that we can further explore the available SNOMED CT APIs.

To import an RF2 archive you must first create an import configuration using the as follows:

curl -X POST http://localhost:8080/snowowl/snomed-ct/v3/imports -d
{
  "type": "SNAPSHOT",
  "branchPath": "MAIN"
}

And the response:

HTTP 204 No Content
Location: "http://localhost:8080/snowowl/snomed-ct/v3/imports/96406e91-84a0-49d3-9e6a-c5c652a36eba"

The import configuration specifies the type of the RF2 release (in this case SNAPSHOT) and the target branchPath where the content should imported. The response returns an empty body along with a Location header with a URL pointing to the created import configuration. You can extract the last part of the URL to get the import configuration ID which can be used to retrieve the configuration and to upload the actual archive and start the import.

The import will start automatically when you upload the archive to the /imports/:id/archive endpoint:

curl -X POST -F file=@SnomedCT_RF2Release_INT_20170731.zip 'http://localhost:8080/snowowl/snomed-ct/v3/imports/96406e91-84a0-49d3-9e6a-c5c652a36eba/archive'

The import process is asynchronous and its status can be checked by sending a GET request to the /imports/:id endpoint with the extracted import identifier as follows:

curl TODO

And the response:

{
  "type": "SNAPSHOT",
  "branchPath": "MAIN",
  "createVersions": false,
  "codeSystemShortName": "SNOMEDCT",
  "id": "ec702c17-88b7-454b-9ebc-d2d1e338658e",
  "status": "RUNNING",
  "startDate": "2018-10-10T10:01:08Z"
}

The status field describes the current state of the import, while the startDate and completionDate fields specify start and completion timestamps.

Snow Owl is provided in the following package formats:

Snow Owl ships with good defaults and requires very little configuration.

Config files location

Snow Owl has three configuration files:

• snowowl.yml for configuring Snow Owl

• serviceability.xml for configuring Snow Owl logging

• elasticsearch.yml for configuring the underlying Elasticsearch instance in case of embedded deployments

These files are located in the config directory, whose default location depends on whether or not the installation is from an archive distribution (tar.gz or zip) or a package distribution (Debian or RPM packages).

For the archive distributions, the config directory location defaults to $SO_PATH_HOME/configuration. The location of the config directory can be changed via the SO_PATH_CONF environment variable as follows:

SO_PATH_CONF=/path/to/my/config ./bin/startup

Alternatively, you can export the SO_PATH_CONF environment variable via the command line or via your shell profile.

For the package distributions, the config directory location defaults to /etc/snowowl. The location of the config directory can also be changed via the SO_PATH_CONF environment variable, but note that setting this in your shell is not sufficient. Instead, this variable is sourced from /etc/default/snowowl (for the Debian package) and /etc/sysconfig/snowowl (for the RPM package). You will need to edit the SO_PATH_CONF=/etc/snowowl entry in one of these files accordingly to change the config directory location.

Config file format

The configuration format is . Here is an example of changing the path of the data directory:

path:
    data: /var/lib/snowowl

Settings can also be flattened as follows:

path.data: /var/lib/snowowl

Environment variable substitution

Environment variables referenced with the ${...} notation within the configuration file will be replaced with the value of the environment variable, for instance:

repository.host: ${HOSTNAME}
repository.port: ${SO_REPOSITORY_PORT}

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.

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

wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.rpm
wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.rpm.sha512
shasum -a 512 -c snow-owl-oss-<version>.rpm.sha512 # Compares the SHA of the downloaded RPM and the published checksum, which should output `snow-owl-oss-<version>.rpm: OK`.
sudo rpm --install snow-owl-oss-<version>.rpm

Running Snow Owl with SysV init

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

sudo chkconfig --add snowowl

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

sudo -i service snowowl start
sudo -i service snowowl stop

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:

sudo /bin/systemctl daemon-reload
sudo /bin/systemctl enable snowowl.service

Snow Owl can be started and stopped as follows:

sudo systemctl start snowowl.service
sudo systemctl stop snowowl.service

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:

curl http://localhost:8080/snowowl/admin/info

which should give you a response something like this:

{
  "version": "7.2.0",
  "description": "You Know, for Terminologies",
  "repositories": {
    "items": [
      {
        "id": "snomedStore",
        "health": "GREEN"
      }
    ]
  }
}

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 Configuring Snow Owl.

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 Snow Owl.

• Configure important Snow Owl settings.

• Configure important system settings.

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.

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:

wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.zip
wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.zip.sha512
shasum -a 512 -c snowowl-oss-<version>.zip.sha512 # compares the SHA of the downloaded archive, should output: `snowowl-oss-<version>.zip: OK.`
unzip snowowl-oss-<version>.zip
cd snowowl-oss-<version>/ # This directory is known as `$SO_HOME`

Download and install the .tar.gz package

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

wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.tar.gz
wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.tar.gz.sha512
shasum -a 512 -c snowowl-oss-<version>.tar.gz.sha512 # compares the SHA of the downloaded archive, should output: `snowowl-oss-<version>.tar.gz: OK.` 
tar -xzf snowowl-oss-<version>.tar.gz
cd snowowl-oss-<version>/ # This directory is known as `$SO_HOME`

Running Snow Owl from the command line

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

./bin/startup

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:

curl http://localhost:8080/snowowl/admin/info

which should give you a response like this:

{
  "version": "7.0.0",
  "description": "You Know, for Terminologies",
  "repositories": {
    "items": [
      {
        "id": "snomedStore",
        "health": "GREEN"
      }
    ]
  }
}

Running in the background

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

nohup ./bin/startup > /dev/null &

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

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

kill <pid>

or using the provided shutdown script:

./bin/shutdown

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 Snow Owl.

• Configure important Snow Owl settings.

• Configure important system settings.

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

wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.deb
wget https://github.com/b2ihealthcare/snow-owl/releases/download/<version>/snow-owl-oss-<version>.deb.sha512
shasum -a 512 -c snow-owl-oss-<version>.deb.sha512 # Compares the SHA of the downloaded Debian package and the published checksum, which should output `snow-owl-oss-<version>.deb: OK`.
sudo dpkg -i snow-owl-oss-<version>.deb

Running Snow Owl with SysV init

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

sudo update-rc.d snowowl defaults 95 10

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

sudo -i service snowowl start
sudo -i service snowowl stop

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:

sudo /bin/systemctl daemon-reload
sudo /bin/systemctl enable snowowl.service

Snow Owl can be started and stopped as follows:

sudo systemctl start snowowl.service
sudo systemctl stop snowowl.service

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:

curl http://localhost:8080/snowowl/admin/info

which should give you a response something like this:

{
  "version": "7.2.0",
  "description": "You Know, for Terminologies",
  "repositories": {
    "items": [
      {
        "id": "snomedStore",
        "health": "GREEN"
      }
    ]
  }
}

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.

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:

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:

repository:
  index:
    clusterUrl: http://your.es.cluster:9200 # the ES cluster URL
    clusterUsername: snowowl # Optional username to connect to a protected ES cluster
    clusterPassword: snowowl_password # Optional password to connect to a protected ES cluster

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.

path:
  data: /var/data/snowowl

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.

# Set the minimum and maximum heap size to 12 GB.
SO_JAVA_OPTS="-Xms12g -Xmx12g" ./bin/startup

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 to no more than 50% of your physical RAM, to ensure that there is enough physical RAM left for kernel file system caches.

• Snow Owl connecting to a remote Elasticsearch cluster requires less memory, but make sure you still allocate enough for your use cases (classification, batch processing, etc.).

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 AWS and Elastic.co for example.

Snow Owl is also available as Docker images. The images use centos:7 as the base image.

A list of all published Docker images and tags is available at Docker Hub.

These images are free to use under the Apache 2.0 license. They contain open source features only.

Pulling the image

Obtaining Snow Owl for Docker is as simple as issuing a docker pull command against the Docker Hub registry.

docker pull snow-owl-oss:latest

Running Snow Owl from the command line

Development mode

Snow Owl can be quickly started for development or testing use with the following command:

docker run -p 8080:8080 snow-owl-oss:latest

Production mode

The following example brings up Snow Owl instance with its dedicated Elasticsearch node. To bring up the cluster, use the docker-compose.yml and just type:

docker-compose up

The node snowowl listens on localhost:8080 while it talks to the elasticsearch node over a Docker network.

To stop the cluster, type docker-compose down. Data volumes/mounts will persist, so it's possible to start the stack again with the same data using docker-compose up`.

Configuring Snow Owl with Docker

Snow Owl loads its configuration from files under /usr/share/snowowl/config/. These configuration files are documented in the Configure Snow Owl pages.

The image offers several methods for configuring Snow Owl settings with the conventional approach being to provide customized files, that is to say, snowowl.yml. It's also possible to use environment variables to set options:

• A. Bind-mounted configuration

  Create your custom config file and mount this over the image's corresponding file.

  For example, bind-mounting a custom_snowowl.yml with docker run can be

  accomplished with the parameter:

-v full_path_to/custom_snowowl.yml:/usr/share/snowowl/configuration/snowowl.yml

• B. Customized image

  In some environments, it may make more sense to prepare a custom image containing

  your configuration. A Dockerfile to achieve this may be as simple as:

FROM snow-owl-oss:{version}
COPY --chown=snowowl:snowowl snowowl.yml /usr/share/snowowl/configuration/

You could then build and try the image with something like:

docker build --tag=snow-owl-oss-custom .
docker run -ti -v /usr/share/snowowl/resources snow-owl-oss-custom

Notes for production use and defaults

We have collected a number of best practices for production use. Any Docker parameters mentioned below assume the use of docker run.

By default, Snow Owl runs inside the container as user snowowl using uid:gid 1000:1000.

• If you are bind-mounting a local directory or file, ensure it is readable by

  this user, while the <> additionally require

  write access. A good strategy is to grant group access to gid 1000 or 0 for

  the local directory. As an example, to prepare a local directory for storing

  data through a bind-mount:

  mkdir sodatadir
  chmod g+rwx sodatadir
  chgrp 1000 sodatadir

• It is important to ensure increased ulimits for nofile

  and nproc are available for the Snow Owl containers.

  Verify the init system

  for the Docker daemon is already setting those to acceptable values and, if

  needed, adjust them in the Daemon, or override them per container, for example

  using docker run:

  --ulimit nofile=65535:65535

NOTE: One way of checking the Docker daemon defaults for the aforementioned ulimits is by running:

  docker run --rm centos:7 /bin/bash -c 'ulimit -Hn && ulimit -Sn && ulimit -Hu && ulimit -Su'

• Swapping needs to be disabled for performance and stability. This can be achieved through any of the methods mentioned in the system settings.

• The image exposes TCP ports 8080 and 2036.

• Use the SO_JAVA_OPTS environment variable to set heap size. For example, to use 16GB use SO_JAVA_OPTS="-Xms16g -Xmx16g" with docker run.

• Pin your deployments to a specific version of the Snow Owl OSS Docker image. For example, snow-owl-oss:7.2.0.

• Consider centralizing your logs by using a different https://docs.docker.com/engine/admin/logging/overview/[logging driver]. Also note that the default json-file logging driver is not ideally suited for production use.

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:

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:

sudo su # Become `root`
ulimit -n 65536 # Change the max number of open files
su snowowl # Become the `snowowl` user in order to start Snow Owl

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:

snowowl  -  nofile  65536

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

# session    required   pam_limits.so

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:

[Service]
LimitMEMLOCK=infinity

Once finished, run the following command to reload units:

sudo systemctl daemon-reload

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:

$ ./bin/shutdown

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:

sysctl -w vm.max_map_count=262144

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.

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.

Scheduler

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

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 as root before starting Snow Owl, or set nofile to 65536 in /etc/security/limits.conf.

RPM and Debian packages already default the maximum number of file descriptors to 65536 and do not require further configuration.

Coming soon!

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.

4. DIVERGED - both parent and branch have at least one commit. The branch must be rebased first before it can be safely merged back to its parent.

5. STALE - the branch is no longer in relation with its former parent, and should be deleted.

Basics

Get a branch

GET /branches/:path

Response

Status: 200 OK
{
  "name": "MAIN",
  "baseTimestamp": 1431957421204,
  "headTimestamp": 1431957421204,
  "deleted": false,
  "path": "MAIN",
  "state": "UP_TO_DATE"
}

Get all branches

GET /branches

Response

Status: 200 OK
{
  "items": [
    {
      "name": "MAIN",
      "baseTimestamp": 1431957421204,
      "headTimestamp": 1431957421204,
      "deleted": false,
      "path": "MAIN",
      "state": "UP_TO_DATE"
    }
  ]
}

Create a branch

POST /branches

Input

{
  "parent" : "MAIN",
  "name" : "branchName",
  "metadata": {}
}

Response

Status: 201 Created
Location: http://localhost:8080/snowowl/snomed-ct/v3/branches/MAIN/branchName

Delete a branch

DELETE /branches/:path

Response

Status: 204 No content

Merging

Perform a merge

POST /merges

Input

{
  "source" : "MAIN/branchName",
  "target" : "MAIN"
}

Response

Status: 202 Accepted
Location: http://localhost:8080/snowowl/snomed-ct/v3/merges/2f4d3b5b-3020-4e8e-b046-b8266967d7dc

Perform a rebase

POST /merges

Input

{
  "source" : "MAIN",
  "target" : "MAIN/branchName"
}

Response

Status: 202 Accepted
Location: http://localhost:8080/snowowl/snomed-ct/v3/merges/c82c443d-f3f4-4409-9cdb-a744da336936

Monitor progress of a merge or rebase

GET /merges/c82c443d-f3f4-4409-9cdb-a744da336936

Response

{
  "id": "c82c443d-f3f4-4409-9cdb-a744da336936",
  "source": "MAIN",
  "target": "MAIN/branchName",
  "status": "COMPLETED",
  "scheduledDate": "2016-02-29T13:52:45Z",
  "startDate": "2016-02-29T13:52:45Z",
  "endDate": "2016-02-29T13:53:06Z"
}

Remove merge or rebase queue item

DELETE /merges/c82c443d-f3f4-4409-9cdb-a744da336936

Response

Status: 204 No content

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.

Running Snow Owl from the command line

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

./bin/startup

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

Running as a daemon

To run Snow Owl as a daemon, use the following command:

nohup ./bin/startup > /dev/null &

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

RPM packages

Snow Owl is not started automatically after installation. How to start and stop Snow Owl depends on whether your system uses SysV init or systemd (used by newer distributions). You can tell which is being used by running this command:

ps -p 1

Running Snow Owl with SysV init

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

sudo chkconfig --add snowowl

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

sudo -i service snowowl start
sudo -i service snowowl stop

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:

sudo /bin/systemctl daemon-reload
sudo /bin/systemctl enable snowowl.service

Snow Owl can be started and stopped as follows:

sudo systemctl start snowowl.service
sudo systemctl stop snowowl.service

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/.

Debian packages (Coming Soon)

Docker images (Coming Soon)

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

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

• Internal (FHIR) Code Systems (terminology subset)

Snow Owl Pro:

• ATC

• ICD-10

• LOINC

• OPCS

SNOMED CT

All standard and default SNOMED CT properties are supported, including the relationship type properties. In addition to the FHIR SNOMED CT properties, Snow Owl can return the effective time property, with the URI http://snomed.info/field/Concept.effectiveTime.

$lookup

Both GET as well as POST HTTP methods are supported. Concepts are queried based on code, version, system or Coding. Designations are included as part of the response as well as supported concept properties when requested. No date parameter is supported.

For SNOMED CT, all common and SNOMED CT properties are supported, including all active relationship types.

$subsumes

Both GET as well as POST HTTP methods are supported. Subsumption testing is supported for ICD-10 and SNOMED CT terminologies.

Snow Owl security features enables 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.

You can choose the following security realms/identity providers to authenticate your users:

• Configure a file realm

• Configure an LDAP realm

You can configure security to communicate with a Lightweight Directory Access Protocol (LDAP) server to authenticate users. To integrate with LDAP, you configure an ldap realm in the snowowl.yml configuration file.

identity:
  providers:
    - ldap:
        uri: <ldap_uri>
        baseDn: dc=snowowl,dc=b2international,dc=com
        rootDn: cn=admin,dc=snowowl,dc=b2international,dc=com
        rootDnPassword: <adminpwd>
        userIdProperty: uid
        usePool: false

At a minimum, you must set the realm type to ldap, specify the url of the LDAP server and set the rootDnPassword in the snowowl.yml configuration file. Your users should be available under the specified baseDn entry, and also there should be an cn=admin entry to allow access for Snow Owl to read user data. By default Snow Owl expects that the username of a user is present in the uid property. You can change this in the userIdProperty setting.

You can manage and authenticate users with the built-in file internal 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 are read on startup.

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

identity:
  providers:
    - file:
        name: users

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 snowowl user with the default snowowl password.

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

Media Types

Custom media types are used in the API to let consumers choose the format of the data they wish to receive. This is done by adding one of the following types to the Accept header when you make a request. Media types are specific to resources, allowing them to change independently and support formats that other resources don’t.

The most basic media types the API supports are:

1. application/json;charset=UTF-8 (default)

2. text/plain;charset=UTF-8

3. text/csv;charset=UTF-8

4. application/octet-stream (for file downloads)

5. multipart/form-data (for file uploads)

The generic JSON media type (application/json) is available as well, but we encourage you to explicitly set the accepted content type before sending your request.

Schema

All data is sent and received as JSON. Blank fields are omitted instead of being included as null.

All non-effective time timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Effective Time values are sent and received in short format:

yyyyMMdd

Hypermedia

All POST requests return Location headers pointing to the created resource instead of including either the identifier or the entire created resource in the response body. These are meant to provide explicit URLs so that proper API clients don’t need to construct URLs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for developers. All URLs are expected to be proper RFC 6570 URI templates.

Example Location Header:

http://example.com/snowowl/snomed-ct/v3/MAIN/concepts/123456789

Pagination

Requests that return multiple items will be paginated to 50 items by default. You can request further pages with the searchAfter query parameter.

Link/Resource expansion

Where applicable, the expand query parameter will include nested objects in the response, to avoid having to issue multiple requests to the server.

Expanded properties should be followed by parentheses and separated by commas; any options for the expanded property should be given within the parentheses, including properties to expand. Typical values for parameters are given in the "Implementation Notes" section of each endpoint.

GET /snowowl/snomed-ct/v3/MAIN/concepts?offset=0&limit=50&expand=fsn(),descriptions()

Response:

{
  "items": [
    {
      "id": "100005",
      "released": true,
      ...
      "fsn": {
        "id": "2709997016",
        "term": "SNOMED RT Concept (special concept)",
        ...
      },
      "descriptions": {
        "items": [
          {
            "id": "208187016",
            "released": true,
            ...
          },
        ],
        "offset": 0,
        "limit": 5,
        "total": 5
      }
    },
    ...
  ],
  "offset": 0,
  "limit": 50,
  "total": 421657
}

Client Errors

There are three possible types of client errors on API calls that receive request bodies:

Invalid JSON

Status: 400 Bad Request
{
  "status" : "400",
  "message" : "Invalid JSON representation",
  "developerMessage" : "detailed information about the error for developers"
}

Valid JSON but invalid representation

Status: 400 Bad Request 
{
  "status" : "400",
  "message" : "2 Validation errors",
  "developerMessage" : "Input representation syntax or validation errors. Check input values.",
  "violations" : ["violation_message_1", "violation_message_2"]
}

Conflicts

Status: 409 Conflict 
{
  "status" : "409",
  "message" : "Cannot merge source 'branch1' into target 'MAIN'."
}

Server Errors

In certain circumstances, Snow Owl might fail to process and respond to a request and responds with a 500 Internal Server Error.

Status: 500 Internal Server Error 
{
  "status" : "500",
  "message" : "Something went wrong during the processing of your request.",
  "developerMessage" : "detailed information about the error for developers"
}

To troubleshoot these please examine the log files at {SERVER_HOME}/serviceability/logs/log.log and/or raise an issue on GitHub.

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

4. sync - synchronize a single member by executing the query and comparing the results with the current members of the referenced target reference set

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

POST /members/:id/actions
{
  "commitComment": "Sync member's target reference set",
  "action": "sync"
}

Bulk API

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

PUT /:path/refsets/:id/members

Input

{
  "commitComment": "Updating members of my simple type reference set",
  "requests": [
      {
        "action": "create|update|delete|sync",
        "action-specific-props": ...
      }
  ]
}

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.

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.

Disable all swap files

Usually Snow Owl is the only service running on a box, and its memory usage is controlled by the JVM options. There should be no need to have swap enabled.

On Linux systems, you can disable swap temporarily by running:

sudo swapoff -a

To disable it permanently, you will need to edit the /etc/fstab file and comment out any lines that contain the word swap.

Configure swappiness

Another option available on Linux systems is to ensure that the sysctl value vm.swappiness is set to 1. This reduces the kernel’s tendency to swap and should not lead to swapping under normal circumstances, while still allowing the whole system to swap in emergency conditions.

# sysctl settings, to be added to /etc/sysctl.conf or equivalent
vm.swappiness = 1
vm.max_map_count = 262144

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

Current Version

SNOMED CT API endpoints currently have version v3. You have to explicitly set the version of the API via path parameter. For example:

GET /snomed-ct/v3/branches

Available resources and services

• Branching

• Compare

• Commits

• Concepts

• Descriptions

• Relationships

• RefSets

• Classification

• Import

• Export

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.

Compare two branches

POST /compare 
{
  "baseBranch": "MAIN",
  "compareBranch": "MAIN/a",
  "limit": 100
}

Response

Status: 200 OK
{
  "baseBranch": "MAIN",
  "compareBranch": "MAIN/a",
  "compareHeadTimestamp": 1567282434400,
  "newComponents": [],
  "changedComponents": ["138875005"],
  "deletedComponents": [],
  "totalNew": 0,
  "totalChanged": 1,
  "totalDeleted": 0
}

Read component state from comparison

Terminology components (and in fact any content) can be read from any point in time by using the special path expression: {branch}@{timestamp}. To get the state of a SNOMED CT Concept from the previous comparison on the compareBranch at the returned compareHeadTimestamp, you can use the following request:

Request

GET /snomed-ct/v3/MAIN@1567282434400/concepts/138875005

Response

Status: 200 OK
{
  "id": "138875005",
  ...
}

To get the state of the same SNOMED CT Concept but on the base branch, you can use the following request:

Request

GET /snomed-ct/v3/MAIN/concepts/138875005

Response

Status: 200 OK
{
  "id": "138875005",
  ...
}

Additionally, if required to compute what's changed on the component since the creation of the task, it is possible to get back the base version of the changed component by using another special path expression: {branch}^.

Request

GET /snomed-ct/v3/MAIN/a^/concepts/138875005

Response

Status: 200 OK
{
  "id": "138875005",
  ...
}

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.

Resources

The Snow Owl terminology server's FHIR API release includes support for the following resources:

• CodeSystem API

• ValueSet API

• ConceptMap API

Implementation

Versions

Snow Owl's repository is a fully-fledged revision control system with branches, versions and revisions. Snow Owl's terminology artefact versions are exposed as FHIR versions for every supported code system with the exception of SNOMED CT where the standard SNOMED CT URI specification governs the format (short date) of the version. If there is no version specified in a request, the last version is assumed. If there is no version in the system, the last state (head of MAIN) is considered.

Search

The supported search result filters:

• _summary

• _elements

The supported search parameters:

• _id

Sorting and paging

Sorting and paging are not yet supported.

URIs

Globally unique logical URIs that represent a terminology resource. For code systems these are:

SNOMED CT

For SNOMED CT, Snow Owl's FHIR implementation follows the SNOMED CT URI Standard.

ICD-10

For ICD-10, Snow Owl's FHIR implementation follows the HL7 FHIR Specification.

Local Code System

Snow Owl's Local Code Systems (LCS) identified by the URI that is based on the Organization Link property stored within Snow Owl's Terminology Registry and the Short Name of the LCS e.g.: https://b2i.sg/MyLocalCodeSystem.

IDs

The id field of each terminology resource is assigned by our terminology server and is unique within Snow Owl. Once is has been assigned, the id never changes. For this logical identifier, Snow Owl follows the pattern:

repository:{branchPath}:{code}[|{member}]

For example to identify a particular LOINC code system with the version tag 20180131:

loincStore:MAIN/20180131

For example to address a particular SNOMED CT concept (Blood bank procedure):

snomedStore:MAIN/201101031/DK/20140203:59524001

where

• 59524001 represents the concept id

• 20140203 represents the extension version

• DK represents the extension branch

• 20110131 represents the version of the International Edition the DK extension is based on

Our logical id has been extended to cover individual Reference Set members as well:

snomedStore:MAIN/201101031/DK/20140203:98403008|84f56f72-9f8b-423d-98b8-25961811393c 

where

• 98403008 is the Reference Set ID

• 98484f56f72-9f8b-423d-98b8-25961811393c03008 is the reference set member

Snow Owl's extension API

Snow Owl exposes a comprehensive REST API to support areas such as:

• Syndication - content provisioning between servers or between the Snow Owl Authoring platform and servers

• Administration (repository and revision control management)

• Auditing

• SNOMED CT specific browsing and authoring API

REST API

Currently only JSON format is supported with UTF-8 encoding and content type of Content-Type = application/fhir+json;charset=utf-8. In case of any errors during the processing the API responds with an OperationOutCome within the response body using one of the HTTP status codes:

ValueSet API

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

• 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

Delete and create operations are not implemented.

$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 , 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

• ?fhir_vs=refset/[sctid] - all concept IDs in the specified reference set

The in-parameters are not yet supported.

$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)

• Potential version mismatch (_error if the reference points to a version that is different to the code's version)

• The status of the given code and reference (warning if code is inactive while reference is active)

For SNOMED CT URIs, implicit value sets are supported:

• ?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

• ?fhir_vs=refset/[sctid] - all concept IDs in the specified reference set

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

NOTE: It is highly recommended to keep the previous Snow Owl 6 deployment up and running until you have the data and all connected services migrated to the new version successfully. The new Snow Owl 7 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.

Java 11

From Snow Owl 7.1, Snow Owl compiles and runs on Java 11+ versions. It is recommended to use the latest OpenJDK or OracleJDK 11 LTS version. Install from OpenJDK, Oracle or AdoptJDK. The Oracle JDK comes with commercial usage restrictions, see here before installing.

RDBMS vs Elasticsearch

While Snow Owl 6 was relying on two data sources for reading and writing data, a primary RDBMS (MySQL) for writing and a secondary Elasticsearch index for full-text search, queries and quick access, Snow Owl 7 in the other hand requires only a single data source, an Elasticsearch cluster.

If you were using an external Elasticsearch cluster then we recommended installing the new Elasticsearch 7.x version first, then installing Snow Owl 7.x and finally connecting the two (or using the appropriate Docker images). If you were using the embedded version, then installing the new Snow Owl 7 version is enough.

After the migration, the MySQL software dependency can be uninstalled from the machine if there are no other services depending on it.

Database content

Due to schema changes the old content present in the RDBMS and index cannot be used by a Snow Owl 7 installation. To migrate an existing dataset to the new version, perform an export in the old system and use the exported files to import the content back into the new Snow Owl 7 version.

LDAP Authorization

The new Snow Owl 7 version comes with complete authorization support using JWT authorization tokens. The old User - Role - Permission system can be used by performing the following migration steps:

1. Add the administrator permission to all administrator roles: *:*

2. Remove the unused permission values from all roles used by Snow Owl

3. Add the classify:* permission declaration and assign it to all roles that should be able to run classifications

Configuration changes

Snow Owl 7 configuration file has been renamed to snowowl.yml (from snowowl_config.yml) and moved to the <HOME>/configuration folder.

The following configuration settings have been changed:

• repository.database configuration setting has been removed completely

• repository.numberOfWorkers has been renamed to repository.maxThreads and its default value became 200.

• metrics settings has been renamed to monitoring

Apply these changes to the configuration before starting your Snow Owl Terminology Server.

Startup and shutdown

The old startup.bat, startup.sh, shutdown.bat, shutdown.sh have been replaced with the new snowowl.sh, snowowl.bat and shutdown.sh scripts.

Packaging

Snow Owl 7 comes in four distribution formats:

• zip/tar.gz for manual deployments

• rpm for CentOS/RHEL based Linux system deployments

• deb for Debian based Linux system deployments

• docker for Docker based deployments

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

ConceptMap API

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

• SNOMED CT Simple Map Reference Sets with Concepts as referenced components

• SNOMED CT Complex Map Reference Sets

• SNOMED CT Extended Map Reference Sets

• Snow Owl's generic Mapping Sets

$translate

All concept map accessible via the /ConceptMap endpoints are considered when retrieving mappings (translations). The translate request's source that designates the source value set cannot be interpreted hence not used. With the exception of SNOMED CT where the standard URI is expected, our proprietary short name or component ids are used to designate the source/target code system.

SNOMED CT:

• Simple Map Type Reference Set mappings are considered equivalent in terms of their correlation

• The availability and format of target code systems are not guaranteed, there is an ongoing conversation at SNOMED CT International to rectify this.

Snow Owl 7 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. Additionally, you can experiment with any Elasticsearch compatible index management software, like Curator for example.

Recommended snapshot configuration

We highly recommend using two remotely accessible repositories (Amazon S3, network attached storage, etc.) to back up and restore data to/from. The back up interval depends on your use case and how you are accessing the data. If you have write-heavy scenarios, we recommend a hourly backup interval, otherwise some value between hourly - daily is preferrable.