One of Snow Owl's powerful features is the ability to list concepts matching a user-specified query expression using SNOMED International's Expression Constraint Language (ECL) syntax. If you would like to know more about the language itself, visit the documentation on the official site.

In this example, we list the direct descendants of the root concept using the ECL expression <!138875005 (via the ecl query parameter), and also limit the result set to a single item using the limit query parameter:

curl -u "test:test" 'http://localhost:8080/snowowl/snomedct/SNOMEDCT/concepts?ecl=%3C!138875005&limit=1&pretty'

As no query parameter in this request would make Snow Owl differentiate between "better" and "worse" results (eg. a search term to match), concepts in the response will be sorted by identifier.

The item returned is, indeed, one of the top-level concepts in SNOMED CT: 105590001 |Substance|

{
  "items": [ {
    "id": "105590001",
    "released": true,
    "active": true,
    "effectiveTime": "20020131",
    "moduleId": "900000000000207008",
    "iconId": "substance",
    "score": 0.0,
    "memberOf": [ "723560006", "733073007", "900000000000497000" ],
    "activeMemberOf": [ "723560006", "733073007", "900000000000497000" ],
    "definitionStatus": {
      "id": "900000000000074008"
    },
    "subclassDefinitionStatus": "NON_DISJOINT_SUBCLASSES",
    "ancestorIds": [ "-1" ],
    "parentIds": [ "138875005" ],
    "statedAncestorIds": [ "-1" ],
    "statedParentIds": [ "138875005" ],
    "definitionStatusId": "900000000000074008"
  } ],
  "searchAfter": "AoEpMTA1NTkwMDAx",
  "limit": 1,
  "total": 19
}

The number 19 in property total suggests that additional matches exist that were not included in the response this time.

Let's import an RF2 archive using its SNAPSHOT content (see release types here) so that we can further explore the available SNOMED CT APIs. To start the import process, send the following request:

curl -v -u "test:test" http://localhost:8080/snowowl/snomedct/SNOMEDCT/import?type=snapshot\&createVersions=false \
-F file=@SnomedCT_InternationalRF2_PRODUCTION.zip

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:

< HTTP/1.1 201 Created
< Location: http://localhost:8080/snowowl/snomedct/SNOMEDCT/import/107f6efa69886bfdd73db5586dcf0e15f738efed

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

The process itself is asynchronous and its status can be checked by periodically sending a GET request to the location returned in the response header:

curl -u "test:test" http://localhost:8080/snowowl/snomedct/SNOMEDCT/import/107f6efa69886bfdd73db5586dcf0e15f738efed?pretty

The expected response while the import is running:

{
  "id": "107f6efa69886bfdd73db5586dcf0e15f738efed",
  "status": "RUNNING"
}

Upon completion, you should receive a different response that lists component identifiers visited during the import as well as any defects encountered in uploaded release files:

{
  "id": "107f6efa69886bfdd73db5586dcf0e15f738efed",
  "status": "FINISHED",
  "response": {
    "visitedComponents": [ ... ],
    "defects": [ ],
    "success": true
  }
}

This guide contains all the necessary details for installing the Snow Owl Terminology Server in a production environment. The following sections will guide you on how to:

• Select the appropriate hardware and software environment to host the service

• Download, install, and configure the entire technology stack necessary for operating the server

• Handle release packages to upgrade to a newer version

• Perform a data backup or a restore

• Manage user access

• Install Snow Owl using advanced methods

• Apply advanced configuration options

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:

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

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

• Administer your instance data

• Check your instance health, status, and statistics

Conclusion

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 guide shows you how to quickly set up a Snow Owl deployment using docker to store, search, and edit any healthcare terminology data. Start here if you are interested in evaluating its core features.

TL;DR

Here is how to deploy Snow Owl in less than a minute:

Prerequisites

The open-source version of Snow Owl can be downloaded as a docker image. The list of all published tags and additional details about the image can be found in Snow Owl's public Docker Hub repository.

To initiate a Snow Owl deployment, the only requirements are:

• the Docker Engine (see install guide)

• a terminal

• git (optional, see install guide)

Supported architectures

Setting up a fully operational Snow Owl server depends on which architecture is supported by the Docker Engine. Thankfully it has a wide variety of platforms such as Linux, Windows, and Mac.

Start your deployment

There is a preassembled docker compose configuration in Snow Owl's GitHub repository. This set of files can be used to start up a Snow Owl terminology server and its corresponding data layer, an Elasticsearch instance.

To get ahold of the necessary files it is required to either download the repository content (see instructions here) or clone the git repository using the git command line tool:

git clone https://github.com/b2ihealthcare/snow-owl.git

Once the clone is finished find the directory containing the compose example:

cd ./snow-owl/docker/compose

While in this directory start the services using docker compose:

docker compose up -d

The service snowowl listens on localhost:8080 while it talks to the elasticsearch service over an isolated Docker network.

To stop the application, type docker compose down. Data volumes/mounts will remain on disk, so it's possible to start the application again with the same data using docker compose up.

A default user is configured to experiment with features that would require authentication and authorization. The username is test and its password is the same.

Here is the full content of the compose file:

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.11.1
    container_name: elasticsearch
    environment:
      - "ES_JAVA_OPTS=-Xms6g -Xmx6g"
    ulimits:
      memlock:
        soft: -1
        hard: -1
      nofile:
        soft: 65536
        hard: 65536
    volumes:
      - es-data:/usr/share/elasticsearch/data
      - ./config/elasticsearch/elasticsearch.yml:/usr/share/elasticsearch/config/elasticsearch.yml
      - ./config/elasticsearch/synonym.txt:/usr/share/elasticsearch/config/analysis/synonym.txt
    healthcheck:
      test: curl --fail http://localhost:9200/_cluster/health?wait_for_status=green || exit 1
      interval: 1s
      timeout: 1s
      retries: 60
    ports:
      - "127.0.0.1:9200:9200"
    restart: unless-stopped
  snowowl:
    image: b2ihealthcare/snow-owl-oss:latest
    container_name: snowowl
    environment:
      - "SO_JAVA_OPTS=-Xms6g -Xmx6g"
      - "ELASTICSEARCH_URL=http://elasticsearch:9200"
    depends_on:
      elasticsearch:
        condition: service_healthy
    volumes:
      - ./config/snowowl/snowowl.yml:/etc/snowowl/snowowl.yml
      - ./config/snowowl/users:/etc/snowowl/users # default username and password: test - test
      - es-data:/var/lib/snowowl/resources/indexes
    ports:
      - "8080:8080"
    restart: unless-stopped

volumes:
  es-data:
    driver: local

Change memory settings

Reducing the memory settings of the docker stack is feasible when Snow Owl is assessed with limited terminologies and basic operations such as term searches. An applicable minimum value should be no less than 2 GB for each service.

The memory settings of Elasticsearch can be changed by adapting the following line in the docker-compose.yml file to e.g.:

- "ES_JAVA_OPTS=-Xms2g -Xmx2g"

The memory settings of Snow Owl can be changed by adapting the following line in the docker-compose.yml file to e.g.:

- "SO_JAVA_OPTS=-Xms2g -Xmx2g"

Check the healthiness of the service

Snow Owl's status is exposed via a health REST API endpoint. To see if everything went well, run the following command:

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

The expected response is

{
  "version": "<version number>",
  "description": "You Know, for Terminologies",
  "repositories": {
    "items": [ {
      "id": "snomed",
      "health": "GREEN",
      "diagnosis": "",
      "indices" : [ {
        "index": "snomed-relationship",
        "status": "GREEN"
      }, {
        "index": "snomed-commit",
        "status": "GREEN"
      }, ...
    } ]
  }
}

The response contains the installed version along with a list of repositories, their overall health (eg. "snomed" with health "GREEN"), and their associated indices and status (eg. "snomed-relationship" with status "GREEN").

Snow Owl is now running but does not contain any content whatsoever. To be able to import or author terminology data a resource has to be created beforehand. There are three major resource types in the system:

• Code Systems (e.g. SNOMED CT, ATC, LOINC, ICD-10)

• Value Sets

• Concept Maps

For the sake of this quick start guide, we will follow along the path of how to create a SNOMED CT code system, import content and query concepts based on different criteria.

Create a Code System

If we take a look at eg. the list of known code systems, we get an empty result set:

To import SNOMED CT content, we have to create a code system first using the following request:

The request body includes:

• The code system identifier (SNOMEDCT)

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

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

• Additional code system settings stored as key-value pairs

If the request succeeds the server returns a "204 No Content" response. We can verify that the code system 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 code system now exists but is empty. To verify this claim, we can list concepts using either Snow Owl's native API tailored for SNOMED CT or the standardized FHIR API 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.

The following request can be used to list all available concepts in a SNOMED CT code system:

The expected response is:

At this point, we can either import or create content in the SNOMED CT code system. Follow the instructions on the next page to import your SNOMED CT RF2 release into Snow Owl.

Search by identifier

Now that SNOMED CT content is present in the code system (identified by the unique id SNOMEDCT) it is time to take a deeper dive. A frequent interaction is to retrieve properties of a concept identified by its . To do so, execute the following command:

The response should look something like this:

We used the expand query parameter to include the concept's Preferred Term (PT) in the response. The concept in question is the root concept of the SNOMED CT hierarchy.

Search by term

Snow Owl also allows users to retrieve concepts matching a specific search term or phrase. See what happens if we try to find the concepts associated with the condition "Méniere's disease":

This time more than one concept can be present in the response, so we receive a collection of items. Results are sorted by relevance, indicated by the field score:

The total number of matching concepts is shown in the property named total.

Operating System

The Terminology Server is recommended to be installed on x86_64 / amd64 Linux operating systems where Docker Engine is available. See by Docker.

Here is the list of distributions that we suggest in the order of recommendation:

• Ubuntu LTS releases

• Debian LTS releases

• CentOS 7 (deprecated)

It is possible to install the server release package on other distributions but bear in mind that there might be limitations.

Software packages

Before starting the production deployment of the Terminology Server make sure that the following packages are installed and configured properly:

• Docker Engine

• ability to execute bash scripts

Firewall

In case a reverse proxy is used, the Terminology Server requires two ports to be opened either towards the intranet or the internet (depending on usage):

• http: port 80

• https: port 443

In case there is no reverse proxy installed, the following port must be opened to be able to access the server's REST API:

• http: port 8080

Snow Owl with a co-located Elasticsearch cluster

For installations where Snow Owl and Elasticsearch are co-located, we recommend the following hardware specifications:

Snow Owl with a managed Elasticsearch cluster

For installations where Snow Owl connects to a managed Elasticsearch cluster at we recommend the following hardware specifications:

Cloud VMs

Here are a few examples of which Virtual Machine types could be used for hosting the Terminology Server at the three most popular Cloud providers (including but not limited to):

The technology stack behind the Terminology Server consists of the following components:

• The Terminology Server application

• Elasticsearch as the data layer

• Optional: Authentication/Authorization service

  • Either an OpenID Connect/OAuth2.0 compatible external service with JSON Web Token support

  • Or an LDAP-compliant directory service

• Optional: A reverse proxy handling the requests towards the REST API

Terminology Server

Outgoing communication from the Terminology Server goes via:

• HTTP(s) towards Elasticsearch and to the external OpenID Connect/OAuth2 authorization server

• LDAP(s) towards the A&A service

Incoming communication is handled through the HTTP port 8080.

A selected reverse proxy channels all incoming traffic through to the Terminology Server.

Elasticsearch

Elasticsearch versions supported by each major version of Snow Owl:

The Elasticsearch cluster can either be:

• a co-located, single-node, self-hosted cluster

A&A service

Reverse proxy

With a preconfigured domain name and DNS record, the default installation package can take care of requesting and maintaining the necessary certificates for secure HTTP. See the details of this in the Configuration section.

Snow Owl® is a highly scalable 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.

Example use cases

• 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 access collaboratively 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.

Features

Revision-controlled authoring and distribution

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

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

SNOMED CT and others

• SNOMED CT terminology support

  • RF2 Release File Specification as of 2024-05-01

  • Support for Relationships with concrete values

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

Various sets of APIs

• Dedicated SNOMED CT, ATC, ICD-10, LOINC, Local Code System, Value Set, and Concept Map APIs

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

Full-text search and data storage

• • Connect to your existing cluster or use the embedded instance (supports up to Elasticsearch 8.x)

  • All the power of Elasticsearch is available (monitoring, analytics, and many more)

Acknowledgments

Numerous other organizations have directly or 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)

• National Library of Medicine (USA)

Having secure HTTP in case the Terminology Server is a public-facing instance is definitely a must. For such cases, we are providing a pre-configured environment and a convenience script to acquire the necessary SSL certificate.

SSL certificate retrieval and renewal are managed by certbot, the official ACME client recommended by Let's Encrypt.

To be able to obtain an SSL certificate the following requirements must be met:

• docker and docker compose are installed

• the server instance has a public IP address

• a DNS A record is configured for the desired domain name routing to the server's IP address

For the sake of example let's say the target domain name is snow-owl.b2ihealthcare.com .

Go to the sub-folder called ./snow-owl/docker/configs/cert. Make sure the init-certificate.sh script has permission to be executable and get some details about its parameters:

[root@host]# pwd
/opt/snow-owl/docker/configs/cert

[root@host]# chmod +x init-certificate.sh
[root@host]# ./init-certificate.sh -h
  DESCRIPTION:

     Get certificate for the specified domain name using Let's Encrypt and certbot

  OPTIONS:
     -h
        Show this help
     -d domain
        Define the domain name to get the certificate for
     -e email (optional)
        The email address to use for the certificate registration

  EXAMPLES:

     ./init-certificate.sh -d mywebsite.com -e example@mail.com
     ./init-certificate.sh -d example.com

As you can see -d is used for specifying the domain name, and -e is used for specifying a contact email address (optional). Now execute the script with our example parameters:

./init-certificate.sh -d snow-owl.b2ihealthcare.com -e domain@b2ihealthcare.com

After successful execution, a new folder is created ./snow-owl/cert which contains all the certificate files required by NGINX. The docker-compose.yml file is also amended with a piece of code that guarantees automatic renewal of the certificate:

  nginx:
    image: nginx:stable
    container_name: nginx
    volumes:
      - ./configs/nginx/conf.d/:/etc/nginx/conf.d/
      - ./configs/nginx/nginx.conf:/etc/nginx/nginx.conf
      - ${CERT_FOLDER}/conf:/etc/letsencrypt
      - ${CERT_FOLDER}/www:/var/www/certbot
    depends_on:
      - snowowl
    ports:
      - "80:80"
      - "443:443"
    # Reload nginx config every 6 hours and restart
    command: "/bin/sh -c 'while :; do sleep 6h & wait $${!}; nginx -s reload; done & nginx -g \"daemon off;\"'"
    restart: unless-stopped
  certbot:
    image: certbot/certbot:latest
    container_name: certbot
    volumes:
      - ${CERT_FOLDER}/conf:/etc/letsencrypt
      - ${CERT_FOLDER}/www:/var/www/certbot
    # Check for SSL cert renewal every 12 hours
    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"
    restart: unless-stopped

At this point everything is prepared for having secure HTTP, let's see what else needs to be configured before spinning up the service.

Terminology Server releases are shared with customers through custom download URLs. The downloaded artifact is a Linux (tar.gz) archive that contains:

• an initial folder structure

• the configuration files for all services

• a docker-compose.yml file that brings together the entire technology stack to run and manage the service

• the credentials required to pull our proprietary docker images

As a best practice, it is advised to extract the content of the archive under /opt. So the deployment folder will be /opt/snow-owl. The docker-compose setup will rely on this path, however, if required it can be changed by editing the ./snow-owl/docker/.env file later on (see DEPLOYMENT_FOLDER environment variable).

When decompressing the archive it is important to use the --same-owner and --preserve-permissions options so the docker containers can access the files and folders appropriately.

tar --extract \
    --gzip \
    --verbose \
    --same-owner \
    --preserve-permissions \
    --file=/path/to/snow-owl-linux-x86_64.tar.gz \
    --directory=/opt/

The next page will describe the content of the release package in more detail.

To configure the Terminology Server to work with a managed Elasticsearch cluster two settings require attention.

Configure Terminology Server

First, the local Elasticsearch container and all its configurations should be removed from the docker-compose.yml file. Once that is done, we have to tell the Terminology Server where to find the cluster. This can be set in the file ./snow-owl/docker/configs/snowowl/snowowl.yml:

repository:
  index:
    socketTimeout: 60000
    clusterUrl: https://my-es-cluster.elastic-cloud.com:9243
    clusterUsername: my-es-cluster-user
    clusterPassword: my-es-cluster-pwd

Configure Elastic Cloud

The Snow Owl Terminology Server leverages Elasticssearch's synonym filters. To have this feature work properly with a managed Elasticsearch cluster our custom dictionary has to be uploaded and configured. The synonym file can be found in the release package under ./snow-owl/docker/configs/elasticsearch/synonym.txt. This file needs to be compressed as an zip archive by following this structure:

.
└── analysis
    └── synonym.txt

For the managed Elasticsearch instance this zip file needs to be configured as a bundle extension. The steps required are covered in this guide in great detail.

Once the bundle is configured and the cluster is up we can (re)start the docker stack. In case there are any troubles the Terminology Server will refuse to initialize and let you know what the problem is in its log files.

In certain cases, a pre-built dataset is also shipped together with the Terminology Server. This is to ease the initial setup procedure and get going fast.

These datasets are the compressed form of the Elasticsearch data folder which follows the same structure. Except for having a top folder called indexes . This is the same folder as in ./snow-owl/resources/indexes . So to be able to load the dataset one should just extract the contents of the dataset archive to this path.

tar --extract \
    --gzip \
    --verbose \
    --same-owner \
    --preserve-permissions \
    --file=snow-owl-resources.tar.gz \
    --directory=/opt/snow-owl/resources/

chown -R 1000:0 /opt/snow-owl/resources

This section includes information on how to set up Snow Owl and get it running using standalone installation methods

Java (JVM) Version

Snow Owl is built using Java and requires at least Java 17 to run. Only Oracle’s Java and the OpenJDK are supported.

We recommend installing the latest version in the Java 17 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.

Here is the list of files and folders extracted from the release package and their role are described below.

snow-owl/
├── backup
├── docker
│   ├── configs
│   │   ├── cert
│   │   │   ├── conf.d
│   │   │   ├── docker-compose-cert.yml
│   │   │   ├── docker-compose.yml
│   │   │   ├── init-certificate.sh
│   │   │   └── nginx.conf
│   │   ├── elasticsearch
│   │   │   ├── elasticsearch.yml
│   │   │   └── synonym.txt
│   │   ├── ldap-bootstrap
│   │   │   ├── 100_groups.ldif
│   │   │   └── 200_users.ldif
│   │   ├── nginx
│   │   │   ├── conf.d
│   │   │   │   └── snowowl.conf
│   │   │   └── nginx.conf
│   │   └── snowowl
│   │       ├── snowowl.yml
│   │       └── users
│   ├── docker-compose.yml
│   ├── docker_login.txt
│   └── .env
├── ldap
├── logs
└── resources
    ├── attachments 
    └── indexes

/docker

Contains every configuration file used for the docker stack, including docker-compose.yml.

In Docker, this directory serves as the context, implying that when executing commands, one needs to either explicitly reference the configuration file or run docker compose commands directly within this directory.

E.g. to verify the status of the stack there are two approaches:

Execute the command inside ./snow-owl/docker:

[root@host docker]# docker compose ps -a

Execute the command from somewhere else then ./snow-owl/docker:

[root@host ~]# docker compose --file /opt/snow-owl/docker/docker-compose.yml ps -a

/docker/configs/cert

This folder contains the files necessary to acquire an SSL certificate. None of the files should be changed here ideally.

/docker/configs/elasticsearch

There is one important file here, elasticsearch.yml which can be used for fine-tuning the Elasticsearch cluster. However, this is not necessary by default, only if an advanced configuration is required.

/docker/configs/ldap-bootstrap

This folder contains the files used upon the first start of the OpenLDAP server. The files within describe a set of groups and users to set up an initial user access model. User credentials for the test users can be found in the file called 200_users.ldif.

/docker/configs/nginx

Location of all configuration files for NGINX. By default, a non-secure HTTP configuration is assumed. If there is no need for an SSL certificate, then the files here will be used. If an SSL certificate was acquired, then the main configuration file of NGINX (nginx.conf) will be overwritten with the one under /docker/cert/nginx.conf.

/docker/configs/snowowl

snowowl.yml: this file is the default configuration file of the Terminology Server. It does not need any changes by default either.

users: list of users for file-based authentication. There is one default user called snowowl for which the credentials can be found under ./docker/.env.

/docker/docker-compose.yml

The main configuration file for the docker stack. This file is replaced in case an SSL certificate was acquired (with file /docker/cert/docker-compose.yml). This is where volumes, ports, or environment variables can be configured.

/docker/docker_login.txt

The credentials to use for authenticating with the B2i private docker registry.

/docker/.env

The collection of environment variables for the docker-compose.yml file.

This is the file to configure most of the settings of the Terminology Server. Including java heap size, Snow Owl or Elasticsearch version, passwords, or folder structure.

/ldap

The location where the OpenLDAP server stores its data.

/logs

Log files of the Terminology Server

/resources

Location of Elasticsearch and Snow Owl resources.

/resources/indexes

This directory serves as the data folder for Elasticsearch, where datasets should be extracted.

/resources/attachments

Snow Owl's local file storage. Import and export artifacts are stored here.

/cert (optional)

In case an SSL certificate is acquired, all the files used by certbot and NGINX are stored here. This folder is automatically created by the certificate retrieval script.

/backup (optional)

This is the initial folder of all backup artifacts. This should be configured as a network mount to achieve data redundancy.

When a new Snow Owl Terminology Server release is available we recommend performing the following steps.

New releases are going to be distributed the same way: a docker stack and its configuration within an archive.

It is advised to decompress the new release files to a temporary folder and compare the contents of ./snow-owl/docker .

The changes usually are restricted to version numbers in the .env file. In such cases, it is equally acceptable to overwrite the contents of the ./snow-owl/docker folder as is or cherry-pick the necessary modifications by hand.

Once the new version of the files is in place it is sufficient to just issue the following commands, an explicit stop of the service is not even required (in the folder ./snow-owl/docker):

The Terminology Server release package contains a built-in solution to perform rolling and permanent data backups. The docker stack has a specialized container (called snow-owl-backup) that is responsible for creating scheduled backups of:

• the Elasticsearch indices

• the OpenLDAP database (if present)

For the Elasticsearch indices, the backup container uses the . Snapshots are labeled in a predefined format with timestamps. E.g. snowowl-daily-20220324030001

The OpenLDAP database is backed up by compressing the contents of the folder under ./snow-owl/ldap. Filenames are generated using the name of the corresponding Elasticsearch snapshot. E.g. snowowl-daily-20220324030001.tar.gz.

Daily backups

Daily backups are rolling backups, scheduled, and cleaned up based on the settings specified in the ./snow-owl/docker/.env file. Here is a summary of the important settings that could be changed.

BACKUP_FOLDER

To store backups redundantly it is advised to mount a remote file share to a local path on the host. By default, this folder is configured to be at ./snow-owl/backup. It contains:

• the snapshot files of the Elasticsearch cluster

• the backup files of the OpenLDAP database

• extra configuration files

CRON_DAYS, CRON_HOURS, CRON_MINUTES

Backup jobs are scheduled by cron, so cron expressions can be defined here to specify the time a daily backup should happen.

NUMBER_OF_DAILY_BACKUPS_TO_KEEP

This is used to tell the backup container how many daily backups must be kept.

Example daily backup config

Let's say we have an external file share mounted to /mnt/external_folder. There is a need to create daily backups after each working day, during the night at 2:00 am. Only the last two-weeks-worth of data should be kept (assuming 5 working days each week).

One-off backups

It is also possible to perform backups occasionally, e.g. before versioning an important SNOMED CT release or before a Terminology Server version upgrade. These backups are kept until manually removed.

To create such backups the following command needs to be executed using the backup container's terminal:

The script will create a snapshot backup of the Elasticsearch data with a label snowowl-my-backup-label-20220405030002 and an archive that contains the database of the OpenLDAP server with the name snowowl-my-backup-label-20220405030002.tar.gz.

Full list of steps to perform before spinning up the service:

1. Extract the Terminology Server release archive to a folder. E.g. /opt/snow-owl

2. (Optional) Obtain an SSL certificate

   1. Make sure a DNS A record is routed to the host's public IP address

   2. Go into the folder ./snow-owl/docker/cert

   3. Execute the ./init-certificate.sh script:

3. (Optional) Configure access for managed Elasticsearch Cluster (elastic.co)

4. (Optional) Extract dataset to ./snow-owl/resources where folder structure should look like ./snow-owl/resources/indexes/nodes/0 at the end.

5. Verify file ownership to be UID=1000 and GID=0:

6. Check any credentials or settings that need to be changed in ./snow-owl/docker/.env

7. Authenticate with our private docker registry while in the folder ./snow-owl/docker:

8. Issue a pull (in folder ./snow-owl/docker)

9. Spin up the service (in the folder ./snow-owl/docker)

10. Verify that the REST API of the Terminology Server is available at:

    1. With SSL: https://snow-owl.example.com/snowowl

    2. Without SSL: http://hostname:8080/snowowl

11. Verify that the server and cluster status is GREEN by querying the following REST API endpoint:

    1. With SSL:

    2. Without SSL:

12. Enjoy using the Snow Owl Terminology Server

Some settings may require attention before moving to production. While the steps below may not necessitate any action, there are cases where the host running both Snow Owl and Elasticsearch will require fine-tuning.

Configure your host for Elasticsearch requirements

Some system-level settings need to be checked before deploying your own Elasticsearch in production.

Following there is an extensive guide on what to verify, but usually, it comes down to these items:

Configure your host for Snow Owl requirements

Set permissions for folders and files appropriately

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 the user mentioned above

  • ensure that settings, data and log directories are writable as well

A good strategy is to grant group access to gid 1000 or 0 for the local directory.

Bind-mount Snow Owl's temporary working folder

In case the file system of the docker service on the host is different from what the Snow Owl deployment uses, it could be worthwhile to bind-mount Snow Owl's temporary working folder to a path that has excellent I/O performance. E.g.:

• the root file system / is backed by a block storage that purposefully has lower I/O performance, this is the file system used by the docker service.

• the deployment folder /opt/snow-owl is backed by a fast local SSD

The definition of the snowowl service in the docker compose file should be amended like this:

Using the custom backup container it is possible to restore:

• the Elasticsearch indices

• the OpenLDAP database (if present)

To restore any of the data the following steps have to be performed:

• stop Snow Owl, Elasticsearch, and the OpenLDAP containers (in the folder ./snow-owl/docker):

• (re)move the contents of the old Elasticsearch data folder:

• restart the Elasticsearch container only (keep Snow Owl stopped):

• use the backup container's terminal and execute the restore script:

  • without any parameters, if only the Elasticsearch indices have to be restored

  • with parameter -l in case the Elasticsearch indices and the OpenLDAP database have to be restored at the same time

• the script will list all available backups and prompts for selection:

• enter the numerical identifier of the backup to restore and wait until the process finishes

• exit the backup container and restart all containers:

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.

The latest stable version of Snow Owl can be found on the 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 a 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.

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.

Directory layout of RPM

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

The Snow Owl Terminology Server employs two distinct methods for user management. The primary authentication and authorization service is the LDAP Directory Server, while a secondary option is a file-based database strictly utilized for administrative purposes. The following methods can be applied when granting or revoking user access.

LDAP-based identity provider

There are several ways to access and manage an OpenLDAP server, hereby we will only describe one of them, through the .

Apache Directory Studio is an open-source, free application. It is available for different platforms (Windows, macOS, and Linux).

Before accessing the LDAP database there is one technical prerequisite to satisfy. The OpenLDAP server has to be accessible from the machine Apache Directory Studio is installed. The best and most secure way to achieve that is to set up an SSH tunnel. Follow to an article that describes how to configure an SSH tunnel using and Windows.

The OpenLDAP server uses port 389 for communication. This is the port that needs to be tunneled through the SSH connection. Here is what the final configuration looks like in PuTTY:

Once the SSH tunnel works, it's time to set up our connection in Apache DS. Go to File -> New -> LDAP Connection and set the following:

Hit the "Check Network Parameter" button to verify the network connection.

Go to the next page of the wizard and provide your credentials. The default Bind DN and Bind password can be found in the Terminology Server release package under ./snow-owl/docker/.env.

Hit the "Check Authentication" button to verify your credentials. Hit Finish to complete the setup procedure.

All users and groups should be browseable now through the LDAP Browser view:

Grant user access

To grant access to a new user an LDAP entry has to be created. Go to the LDAP Browse view and right-click on the organization node, then New -> New Entry:

It is the easiest to use an existing entry as a template:

Leave everything as is on the Object Classes page, then hit Next. Fill in the new user's credentials:

On the final page, double-click on the userPassword row and provide the user's password:

Hit Finish to add the user to the database.

Now we need to assign a role for the user. Before going forward, get ahold of the user's DN using the LDAP Browser view:

Select the desired role group in the Browser view and add a new attribute:

Select the attribute type uniqueMember and hit Finish:

Paste the user's DN as the value of the attribute and hit Enter to make your changes permanent:

Revoke user access

To revoke access the user has to be deleted from the list of users:

And also has to be removed from the role group:

Change credentials

To change either the first or last name, or the password of a user, just edit any of the attributes in the user editor:

File-based identity provider

There is a configuration file ./snow-owl/docker/configs/snowowl/users that contains the list of users with their credentials encrypted. This method of authentication should be used for testing or internal purposes only, users added here will have elevated privileges.

Grant user access

To grant access the users file has to be amended with the new user and its credentials. There are several ways to encrypt a password but here is one that is easy and available on most of the Linux variants. The package called htpasswd has to be installed:

It will prompt for the password and will amend the file with the new user at the end.

Revoke user access

Simply remove the user's line from the file and restart the service.

Change credentials

Ideally, Snow Owl should run alone on a server and use all of the resources available to it. 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

• Increase file descriptors

• Ensure sufficient virtual memory

• Ensure sufficient threads

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 ulimit, or

• permanently in /etc/security/limits.conf.

When using the RPM or Debian packages, most system settings are set in the system configuration file. However, systems that 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 temporarily. 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 that use 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

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.

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

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

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.

The preferred method of setting JVM options (including system properties and JVM flags) is via 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 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:

• Configure a file realm

• Configure an LDAP realm

Authentication

After configuring at least one security realm, Snow Owl will authenticate all incoming requests to ensure that the sender of the request is allowed to access the terminology server and its contents. To authenticate a request, the client must send an HTTP Basic or Bearer Authorization header with the request. The value should be a user/pass pair in case of using Basic authentication or a JWT token generated by Snow Owl if using the Bearer method.

Snow Owl sends a HTTP 401 Unauthorized response if a request needs to be authenticated.

Authorization

If supported by the security realm, Snow Owl will also check whether an authenticated user is permitted to perform the requested action on a given resource.

Within an organization, roles are created for various job functions. The permissions to perform certain operations are assigned to specific roles. Members, staff, or other system users are assigned particular roles, and through those role assignments acquire the permissions needed to perform particular system functions. Since users are not assigned permissions directly, but only acquire them through their role (or roles), management of individual user rights becomes a matter of simply assigning appropriate roles to the user's account; this simplifies common operations, such as adding a user or changing a user's department.

Rules

1. Role assignment: A subject can exercise a permission only if the subject has selected or been assigned a role.

2. Permission authorization: A subject can exercise a permission only if the permission is authorized for the subject's active role.

With rules 1 and 2, it is ensured that users can exercise only permissions for which they are authorized.

S = Subject = A person or automated agent R = Role = Job function or title which defines an authority level P = Permissions = An approval of a mode of access to a resource

Permissions

In Snow Owl a permission is a single value that represents both the operation the user would like to perform and the resource that is being accessed. The format is the following: <operation>:<resource>

Currently there are 7 operations supported by Snow Owl:

• browse - read the contents of a resource

• edit - write the contents of the resource, delete the resource

• import - import from external content and formats

• export - export to external content and formats

• version - create a version in a Code System, create a release

• promote - merge content from isolated branch environments to a Code System's development version

• classify - run classifiers and save their results

Resources represent the content that is being accessed by a client. A resource can be anything that can be resolved to a database entry. Currently, the following resource formats are allowed to be used in a permission:

• <repositoryId> - access the entire content available in a terminology repository

• <repositoryId>/<branch> - access the content available on a branch in a terminology repository

• <codeSystemId> - access all content of a Code System, including both the latest development and all previous releases

• <codeSystemId>/<versionId> - access a specific release of a Code System

There is a special * wild card character that can be used for both the operation and resource parts in a permission value to allow any operation to be performed on any or selected resources, or to allow certain operations to be performed on any available resources.

Examples:

• browse:snomedStore - browse all SNOMED CT Code Systems and their content

• edit:SNOMEDCT-UK-CL - edit the SNOMEDCT-UK-CL Code System

• export:SNOMEDCT-US/2019-03-01 - export the 2019-03-01 US Extension release

• *:SNOMEDCT - allow any operations to be performed on the SNOMEDCT Code System

• browse:* - allow read operations on all available resources

• *:* - administrator permission, the user can do anything with any of the available resources

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

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

Snow Owl is provided in the following package formats:

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

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 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 identifier, 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) - SNOMEDCT-UK-CL, SNOMEDCT-UK-DR - United Kingdom Clinical and Drug Extensions, respectively

• Care Provider with a special extension based on a national extension - SNOMEDCT-US-UNMC - University of Nebraska Medical Center's extension builds on top of the SNOMEDCT-US extension

The primary namespace identifier 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 a crucial role in SNOMED CT Extension management 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 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.

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

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:

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:

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:

Settings can also be flattened as follows:

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:

An orderly shutdown of Snow Owl ensures that Snow Owl has a chance to clean up 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

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.

• Single Edition

• Single Extension

• Multi Extension

Introduction

The Snow Owl Terminology Server is capable of managing multiple SNOMED CT editions and/or 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 Release Format 2 specification).

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 Namespace identifier).

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 Modules).

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 Purpose).

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 Extensions).

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 Versions).

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 identifier to globally identify its content

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

• Uses one or more languages to support specific user groups and patient-friendly terms

• Depends on the SNOMED CT International Edition

• Uses versions (effective times) to identify its content across multiple releases

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.

A typical extension scenario is the development of the extension itself. Whether you are starting your extension from scratch or already have a well-developed version that you need to maintain, the first choice you need to make is to identify the dependencies of your SNOMED CT Extension.

Extending the International Edition

If your Extension extends the SNOMED CT International Edition directly, then you need to pick one of the available International Edition versions:

• If you are starting from scratch, it is always recommended to select the latest International Release as the starting point of your Extension.

• If you have an existing Extension then you probably already know the International Release version your Extension depends on.

When you have identified the version you need to depend on then you need to import that version (or a later release packages that also includes that version in its FULL RF2 package) first into Snow Owl. Make sure that the createVersion feature of the RF2 import process is enabled, so it will automatically create the versions for each imported RF2 effectiveTime value.

After you have successfully imported all dependencies into Snow Owl, the next step is to create a Code System that represents your SNOMED CT Extension (see Core API). When creating the Code System, besides specifying the namespace and optional modules and languages, you need to enter a Code System shortName, which will serve as the unique identifier of your Extension and select the extensionOf value, which represents the dependency of the Code System.

After you have successfully created the Code System representing your Extension, you can import any existing content from a most recent release or start from scratch by creating the module concept of your extension.

#

Extending another Extension

If your Extension needs to extend another Extension and not the International Edition itself, then you need to identify the version you'd like to depend on in that Extension (that indirectly will select the International Edition dependency as well). When you have identified all required versions, then starting from the International Edition recursively traverse back and repeat the RF2 Import and Code System creation steps described in the previous section until you have finally imported your extension. In the end your extension might look like this, depending on how many Extensions you are depending on.

Summary

Setting up a Snow Owl deployment like this is not an easy task. It requires a thorough understanding of each SNOMED CT Extension you'd like to import and their dependencies as well. However, after the initial setup, the maintenance of your Extension becomes straightforward, thanks to the clear distinction from the International Edition and from its other dependencies. The release process is easier and you can choose to publish your Extension as an extension only release, or as an Edition or both (see Release). Additionally, when a new version is available in one of the dependencies, you will be able to upgrade your Extension with the help of automated validation rules and upgrade processes (see Upgrade). From the distribution perspective, this scenario shines when you need to maintain multiple Extensions/Editions in a single deployment.

Pros:

• Excellent for authoring and maintenance

• Good for distribution

Cons:

• Harder to set up the initial deployment

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.

Prepare the Release

After all development branches have been merged and integrated with the main work-in-progress version, the Extension needs to be prepared for release. This usually involves last minute fixes, running quality checks and validation rules and generating the final necessary normal form of the Extension.

Release

When all necessary steps have been performed successfully, a new Code System Version needs to be created in Snow Owl to represent the latest release. The versioning process will assign the requested effectiveTime to all unpublished components, update the necessary Metadata reference sets (like the Module Dependency Reference Set) and finally create a version branch to reference this release later.

Packaging

After a successful release, an RF2 Release Package needs to be generated for downstream consumers of your Extension. Snow Owl can generate this final RF2 Release Packages for the newly released version via the RF2 Export API.

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 SNOMED CT RF2 Import API 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

This section describes the various supported healthcare standards, how they can be imported into a Snow Owl Terminology Server, and how they can be accessed and distributed further.

List of officially supported standards

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 single extension). 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.

Next steps

After you have initialized your Snow Owl instance with the Extensions you'd like to maintain the next steps are:

• Development

• Release

• Upgrade

• Integrate

As with every other resource in Snow Owl, a LOINC Code System needs to be created using the CodeSystems API first:

Then, an official release file can be imported via the following request:

And last, create a new version to tag the content:

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

• running validation processes to verify the quality and integrity of their Extension

• classifying their authored content with an OWL Reasoner to produce its distribution normal form

The authors directly (via the available REST and FHIR APIs) or indirectly (via user interfaces, scripts, etc.) work with the Snow Owl Terminology Server to make the necessary changes for the next planned Extension release.

Workflow and Editing

Authors often require a dedicated editing environment where they can make the necessary changes and let others review the changes they have made, so errors and issues can be corrected before integrating the change with the rest of the Extension. Similarly to how SNOMED CT Extensions are separated from the SNOMED CT International Edition and other dependencies, this can be achieved by using branches.

• - to create and merge branches

• - to compare branches

Authoring APIs

To let authors make the necessary changes they need, Snow Owl offers the following SNOMED CT component endpoints to work with:

• Description API - to create and edit SNOMED CT Descriptions

• Relationship API - to create and edit SNOMED CT Relationships

• Reference Set API - to create and edit SNOMED CT Reference Sets

• Reference Set Member API - to create and edit SNOMED CT Reference Set Members

Validation

To verify quality and integrity of the changes they have made, authors often generate reports and make further fixes according to the received responses. In Snow Owl, reports and rules can be represented with validation queries and scripts.

• Validation API - to run validation rules and fetch their reported issues on a per branch basis

Classification

Last but not least, authors run an OWL Reasoner to classify their changes and generate the necessary normal form of their Extension. The Classification API provides support for running these reasoner instances and generating the necessary normal form.

First, create the ICD-10-SE Code System:

Then, import the classification content from a ClaML file (generated by B2i Healthcare, ):

And last, create a new version to mark the content:

First, create the ICF Code System:

Then, using column mapping import the concepts from the official TSV file:

And last, create a new version to mark the content:

Alternatives

To simplify integration and enable interoperability with third-party systems, Snow Owl TS offers two forms of accessing terminology resources via HTTP requests:

• An API compliant with the requirements listed in the FHIR R5 specification for terminology services:

• A native API that is customized to match Snow Owl's internal representation of its supported resources, and so can provide more options

The following pages provide additional information on each method of access:

Official Examples

A comprehensive set of examples is available in our Postman collection:

Interactive documentation

Port 8080 and the context path /snowowl is assigned in the default installation for serving both APIs. Navigate to http(s)://<host>:8080/snowowl/ to visit the built-in "interactive playground" which lists all available requests by category in the dropdown on the top left:

Once valid user credentials are entered on the "Authentication" page reachable from the sidebar, it becomes possible to send requests to the server and inspect the returned response body as well as any relevant headers:

Select a request from the sidebar so that its documentation page appears in the main area. Each request is accompanied by a short description and the list of parameters it accepts. Fields marked with a * symbol are required.

Press the Try button after populating the input fields to execute the request:

With content syndication, data can be seamlessly moved between different Snow Owl Terminology Server deployments.

This functionality is useful when content created in a central deployment (upstream) needs to be distributed to one or more read-only downstream instances. The resource distribution is designed to be uni-directional and semi-automated where an actor has to configure any new downstream instances to be able to receive data from the central unit.

Configure upstream

To be able to access the upstream server and its content the following items are required:

• the HTTP port of Elasticsearch has to be accessible for the downstream Snow Owl and Elasticsearch instances (configured via the http.port property, the default is 9200)

• the REST API of Snow Owl has to be accessible for the downstream Snow Owl servers

• an Elasticsearch API key with sufficient privileges for authentication and authorization

• a Snow Owl API key with sufficient privileges for authentication and authorization

• configure selected terminology resources as distributable

Access Elasticsearch

In case Snow Owl uses a self-hosted Elasticsearch instance the HTTP port can be opened by modifying the container settings in the docker-compose.yml file. Make sure to remove the localhost IP prefix from the port declaration:

In the case of a hosted Elasticsearch instance there is nothing to do, it will already be accessible from outside.

Access Snow Owl

The default reverse proxy configuration (shipped in the released package) exposes the Snow Owl REST API via the URL: http(s)://upstream-snow-owl-url/snowowl

Other than that no additional configuration is needed.

Obtain an Elasticsearch API key

Creating a new API key for Elasticsearch is either possible through its Api Key API or - in the case of a hosted instance - from within Kibana.

The content syndication operation requires the following permissions:

• cluster privilege: monitor

• index privilege: read

Here is an example request body for the Api Key API:

This request will return with the following response:

Take note of the encoded API Key, which is the one that will be used later on.

Obtain a Snow Owl API Key

To request an API key from the upstream Snow Owl Terminology Server the following REST API endpoint must be used:

To request an API key