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.

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!

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

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

The first one indicates that the file was uploaded successfully and a resource has been created to track 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:

The expected response while the import is 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:

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.

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

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

• a terminal

Supported architectures

Start your deployment

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

While in this directory start the services using docker compose:

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:

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

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

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:

The expected response is

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

Operating System

The Terminology Server is recommended to be installed on x86_64 / amd64 Linux operating systems where Docker Engine is available. See the list of supported architectures 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

• docker compose

• 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

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

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 SNOMED CT Identifier. To do so, execute the following command:

curl -u "test:test" 'http://localhost:8080/snowowl/snomedct/SNOMEDCT/concepts/138875005?expand=pt()&pretty'

The response should look something like this:

{
  "id": "138875005",
  "released": true,
  "active": true,
  "effectiveTime": "20020131",
  "moduleId": "900000000000207008",
  "iconId": "snomed_rt_ctv3",
  "score": 0.0,
  "memberOf": [ "900000000000497000" ],
  "activeMemberOf": [ "900000000000497000" ],
  "definitionStatus": {
    "id": "900000000000074008"
  },
  "subclassDefinitionStatus": "NON_DISJOINT_SUBCLASSES",
  "pt": {
    "id": "220309016",
    "term": "SNOMED CT Concept",
    "concept": {
      "id": "138875005"
    },
    "type": {
      "id": "900000000000013009"
    },
    "typeId": "900000000000013009",
    "conceptId": "138875005",
    "acceptability": {
      "900000000000509007": "PREFERRED",
      "900000000000508004": "PREFERRED"
    }
  },
  "ancestorIds": [ ],
  "parentIds": [ "-1" ],
  "statedAncestorIds": [ ],
  "statedParentIds": [ "-1" ],
  "definitionStatusId": "900000000000074008"
}

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

curl -u "test:test" 'http://localhost:8080/snowowl/snomedct/SNOMEDCT/concepts?term=M%C3%A9niere%27s%20disease&expand=pt()&pretty'

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:

{
  "items": [ {
    "id": "13445001",
    "released": true,
    "active": true,
    "effectiveTime": "20020131",
    "moduleId": "900000000000207008",
    "iconId": "disorder",
    "score": 3.9305625,
    "memberOf": [ "447562003", "733073007", "900000000000497000" ],
    "activeMemberOf": [ "447562003", "733073007", "900000000000497000" ],
    "definitionStatus": {
      "id": "900000000000074008"
    },
    "subclassDefinitionStatus": "NON_DISJOINT_SUBCLASSES",
    "pt": {
      "id": "178783019",
      "term" : "Ménière's disease",
      "concept": {
        "id": "13445001"
      },
      "type": {
        "id": "900000000000013009"
      },
      "typeId": "900000000000013009",
      "conceptId": "13445001",
      "acceptability": {
        "900000000000509007": "PREFERRED",
        "900000000000508004": "PREFERRED"
      }
    },
    "ancestorIds": [ "-1", "20425006", ..., "1279550006" ],
    "parentIds": [ "50438001" ],
    "statedAncestorIds": [ "-1", "64572001", "138875005", "404684003" ],
    "statedParentIds": [ "50438001" ],
    "definitionStatusId": "900000000000074008"
  }, {
    ...
  } ],
  "searchAfter": "AoIFQAd5LmITGo8wMTA4OTA5MTAwMDExOTEwNQ==",
  "limit": 50,
  "total": 27
}

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

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 managed Elasticsearch cluster hosted by elastic.co

A&A service

For authorization and authentication, the application supports external OpenID Connect/OAuth2 compatible authorization services (eg. Auth0) and any traditional LDAP Directory Servers. We recommend starting with OpenLDAP and evolving to other solutions later because it is easy to set up and maintain while keeping Snow Owl's user data isolated from any other A&A services.

Reverse proxy

A reverse proxy, such as NGINX is recommended to be utilized between the Terminology Server and either the intranet or the internet. This will increase security and help with channeling REST API requests appropriately.

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 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 elastic.co 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):

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.

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

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

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

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

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

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 , the official ACME client recommended by .

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:

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:

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:

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

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:

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:

For the managed Elasticsearch instance this zip file needs to be configured as a bundle extension. The steps required are covered in 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.

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)

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 .

[root@host]# diff /opt/snow-owl/docker/ /opt/new-snow-owl-release/snow-owl/docker/
Common subdirectories: /opt/snow-owl/docker/configs and /opt/new-snow-owl-release/snow-owl/docker/configs
diff /opt/snow-owl/docker/.env /opt/new-snow-owl-release/snow-owl/docker/.env
10c10
< ELASTICSEARCH_VERSION=7.16.3
---
> ELASTICSEARCH_VERSION=7.17.1
24c24
< SNOWOWL_VERSION=8.1.0
---
> SNOWOWL_VERSION=8.1.1

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

docker compose pull
docker compose up -d

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

BACKUP_FOLDER=/mnt/external_folder
NUMBER_OF_DAILY_BACKUPS_TO_KEEP=10

CRON_DAYS=Tue-Sat
CRON_HOURS=2
CRON_MINUTES=0

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:

root@host:/# docker exec -it backup bash
root@ad36cfb0448c:/# /backup/backup.sh -l my-backup-label

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.

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.

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 this link there is an extensive guide on what to verify, but usually, it comes down to these items:

• Set vm.max_map_count to at least 262144

• Increase ulimits for nofile and nproc

• Disable swapping

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:

snowowl:
    image: b2ihealthcare/snow-owl-<variant>:<version>
    ...
    volumes:
      - ./config/snowowl/snowowl.yml:/etc/snowowl/snowowl.yml
      - ./config/snowowl/users:/etc/snowowl/users
      - ${SNOWOWL_DATA_FOLDER}:/var/lib/snowowl
      - ${SNOWOWL_LOG_FOLDER}:/var/log/snowowl
+     - /path/to/folder/with/fast/performance:/usr/share/snowowl/work
    ports:
    ...

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

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

docker compose stop snowowl elasticsearch ldap

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

mv -t /tmp ./snow-owl/resources/indexes/nodes

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

docker compose start elasticsearch

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

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

  Copy

  root@host:/# docker exec -it backup bash
  root@ad36cfb0448c:/# /backup/restore.sh

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

  Copy

  root@host:/# docker exec -it backup bash
  root@ad36cfb0448c:/# /backup/restore.sh -l

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

root@ad36cfb0448c:/# /backup/restore.sh

################################
Snow Owl restore script STARTED.

#### Verify Elasticsearch snapshot repository ####

Checking existence of repository 'snowowl-snapshots' ...
Repository with name 'snowowl-snapshots' is present, verifying repository state ...
Repository 'snowowl-snapshots' is functional

#### Select backup to restore ####

Found 10 available backups under '/backup'
Please select the backup to restore by choosing the right number in the menu below (hit Enter when the selection was made)

 1) snowowl-daily-20220323030001
 2) snowowl-daily-20220324030001
 3) snowowl-daily-20220325030002
 4) snowowl-daily-20220326030002
 5) snowowl-daily-20220329030001
 6) snowowl-daily-20220330030001
 7) snowowl-daily-20220331030002
 8) snowowl-daily-20220401030002
 9) snowowl-daily-20220402030001
10) snowowl-daily-20220405030002

#?

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

• exit the backup container and restart all containers:

root@ad36cfb0448c:/# exit
root@host:/# docker compose up -d

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

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

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

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

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

which should give you a response like this:

{
  "version": "<version_number>",
  "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 a 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.

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

which should give you a response something like this:

{
  "version": "<version_number>",
  "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:

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:

   Copy

   ./init-certificate.sh -d snow-owl.example.com

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:

   Copy

   chmod -R 1000:0 ./snow-owl/docker ./snow-owl/logs ./snow-owl/resources

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:

   Copy

   cat docker_login.txt | docker login -u <username> --password-stdin https://docker.b2ihealthcare.com

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

   Copy

   docker compose pull

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

   Copy

   docker compose up -d

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:

       Copy

       curl https://snow-owl.example.com/snowowl/info

    2. Without SSL:

       Copy

       curl http://hostname:8080/snowowl/info

12. Enjoy using the Snow Owl Terminology Server

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.

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 this link to an article that describes how to configure an SSH tunnel using PuTTY 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:

htpasswd -nBC 10 my-new-username | head -n1 | sed 's/$2y/$2a/g' >> ./snow-owl/docker/configs/snowowl/users

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

Remove the user's line from the file and regenerate the credentials according to the Grant user access section.

Snow Owl is provided in the following package formats:

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

Download and install

Running Snow Owl with SysV init

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

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

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

Running Snow Owl with systemd

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

Snow Owl can be started and stopped as follows:

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

Checking that Snow Owl is running

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

which should give you a response something like this:

Configuring Snow Owl

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

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:

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:

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

The new limit is only applied during the current session.

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

/etc/security/limits.conf

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

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

Sysconfig file

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

However, for systems 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:

Once finished, run the following command to reload units:

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

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

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

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

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.

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

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

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

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

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.

Users Command

To simplify file realm configuration, the Snow Owl CLI comes with a command to add a user to the file realm (snowowl users add). See the command help manual (-h option) for further details.

Authorization

The file security realm does NOT support the Authorization formats at the moment. If you are interested in configuring role-based access control for your users, it is recommended to switch to the LDAP security realm.

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

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

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

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

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.

identity:
  providers:
    - ldap:
        uri: <ldap_uri>
        bindDn: cn=admin,dc=snowowl,dc=b2international,dc=com
        bindDnPassword: <adminpwd>
        baseDn: dc=snowowl,dc=b2international,dc=com
        roleBaseDn: {baseDn}
        userFilter: (objectClass={userObjectClass})
        roleFilter: (objectClass={roleObjectClass})
        userObjectClass: inetOrgPerson
        roleObjectClass: groupOfUniqueNames
        userIdProperty: uid
        permissionProperty: description
        memberProperty: uniqueMember
        usePool: false

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:

dn: cn=John Doe+sn=Doe+uid=johndoe@b2international.com,dc=snowowl,dc=b2international,dc=com
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: person
objectClass: top
cn: John Doe
sn: Doe
uid: johndoe@b2international.com
userPassword: <encrypted_password> 

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:

dn: cn=Browser,dc=snowowl,dc=b2international,dc=com
objectClass: top
objectClass: groupOfUniqueNames
cn: Browser
description: browse:*
description: export:*
uniqueMember: cn=John Doe+sn=Doe+uid=johndoe@b2international.com,dc=snowowl,dc=b2international,dc=com 

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.

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

Pros:

• Excellent for authoring and maintenance

• Good for distribution

Cons:

• Harder to set up the initial deployment

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

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

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.

Next steps

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

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.