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)

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!

Search by identifier

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.

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

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.

Operating System

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

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.

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:

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.

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.

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:

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.

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

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

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

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.

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.

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.

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.

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.

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

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

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.

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)

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.

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

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

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

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:

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 is provided as a .zip and as a .tar.gz package. These packages can be used to install Snow Owl on any system.

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.

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 is provided in the following package formats:

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:

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 Debian package for Snow Owl can be downloaded from the Downloads section. It can be used to install Snow Owl on any Debian-based system such as Debian and Ubuntu.

Download and install

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

Running Snow Owl with SysV init

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

sudo update-rc.d snowowl defaults 95 10

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

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

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

Running Snow Owl with systemd

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

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

Snow Owl can be started and stopped as follows:

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

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

Checking that Snow Owl is running

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

curl http://localhost:8080/snowowl/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.

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:

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:

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:

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:

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

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

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

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

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:

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

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

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.

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:

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.

Elasticsearch settings

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

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

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

Path settings

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

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

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

Network settings

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

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

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

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

Setting the heap size

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

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

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

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

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

• Set Xmx to no more than 50% of your physical RAM, to ensure that there is enough physical RAM left for kernel file system caches.

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

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

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

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

Configure the embedded instance

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

Connect to a remote cluster

The second option is to configure Snow Owl to use a remote Elasticsearch cluster without the embedded instance. 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 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:

Authentication

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

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 

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

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.

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.

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

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.

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.

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.

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.

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.

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

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

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

Snow Owl Concepts

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

Code Systems

From the getting started 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.

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.

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

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

Maintenance of a SNOMED CT Extension is essential to ensure that

• it incorporates changes requested by terminology consumers

• it remains aligned with the SNOMED CT International Edition

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

Change requests

Changes requested by your terminology consumers are typically content authoring tasks that you would assign to an Extension authoring team. They usually come with a well-described problem you need to address in the terminology as you would do in the usual development cycle.

International Edition Changes

Aligning content to the SNOMED CT International Edition is one of the main responsibilities of an Extension maintainer. However, keeping up with the changes introduced in SNOMED CT International Edition biannually (on January 31st and July 31st) can be an overwhelming task, especially if:

• you are under pressure from your terminology consumers to make the requested changes ASAP, especially in mission critical scenarios.

• the changes introduced in the International Edition are conflicting with your local changes and/or causing maintenance related issues after the upgrade.

To address SNOMED CT International Edition upgrade tasks in a reliable and reproducible way, Snow Owl offers an upgrade flow for SNOMED CT Extensions.

Upgrades

A Code System upgrade in Snow Owl is a complex workflow with states and steps. The workflow involves a special Upgrade Code System, a series of automated migration processes and validation rules to ensure the quality and reliability of the operation. The upgrade can be done quickly if there were no conflicts between the Extension and the International Edition. However, updates can also be a long-running process spanning over many months when significant structural changes (e.g. in substances, anatomy, or modeling approach) are made in the International Edition.

Starting the Upgrade

In Snow Owl, SNOMED CT Extension are linked to their SNOMED CT dependency with the extensionOf property. This property describes the International Edition and its version that the Extension depends on. For example, the SNOMEDCT/2019-07-31 value specifies that our Extension depends on the 2019-07-31 version of the International Edition.

Extension upgrades can be started when there is a new version available in the Extension/Edition we have selected as our dependency in the extensionOf property. When fetching a SNOMED CT Code System via the Code System API, Snow Owl will check if there are any upgrades availables and return them in the availableUpdates array property. If there are no upgrades available the array will be empty.

When the upgrade is started, Snow Owl creates a special <codeSystemId>-UP-<newExtensionOf> (eg. SNOMEDCT-MYEXT-UP-SNOMEDCT-2020-01-31) Code System to allow authors and the automated processes to migrate the latest development version of the Extension to the new dependency.

Regular Maintenance

Regular daily Extension development tasks still need to be resolved and pushed somewhere in order to continue the development of the Extension, even if an upgrade process is in progress. Each Extension still has an active development version, even if an upgrade is in progress, which can be used to push daily maintenance changes and business as usual tasks.

Changes pushed to the development area will regularly need to be synced with the upgrade until the upgrade completes, so the upgrade team will be able to resolve all remaining conflicts and issues.

Upgrade Checks

Upgrade Checks ensure the quality of the upgrade process and execute certain tasks/checks automatically. An Upgrade Check can be any logic or function to be run during the upgrade. Upgrade Checks can access the underlying upgrade Code System's content and report any issues (validation rules) or fix content automatically (migration rules). For example, a validation rule (like Active relationships must have active source, type, destination references) can be executed after each change pushed to the upgrade branch to verify whether there is any potentially invalid relationship left to fix or you are ready to go.

Completing the Upgrade

Once the upgrade authoring team is done with the necessary changes to align the Extension with the new International Edition and all the checks are completed successfully the upgrade can be completed. Completing the upgrade performs the following steps:

• Creates a <codeSystemId>-DO-<previousExtensionOf> Code System to refer to the previous state of the Extension

• Changes the current working branch of the Extension Code System to the branch that was used during the upgrade process

• Deletes the <codeSystemId>-UP-<newExtensionOf> Code System, which marks the upgrade complete, and the upgrade itself cannot be accessed anymore.

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 page describes the terminology standards offered publicly by the Swedish National Board of Health and Welfare:

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.

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

POST /codesystems
{
  "id": "LOINC",
  "url": "http://hl7.org/fhir/sid/loinc",
  "title": "LOINC",
  "language": "en",
  "description": "LOINC is a freely available international standard for tests, measurements, and observations",
  "status": "active",
  "copyright": "This material contains content from LOINC (http://loinc.org). LOINC is copyright ©1995-2023, Regenstrief Institute, Inc. and the Logical Observation Identifiers Names and Codes (LOINC) Committee and is available at no cost under the license at http://loinc.org/license. LOINC® is a registered United States trademark of Regenstrief Institute, Inc.",
  "owner": "ownerUserId",
  "contact": "https://loinc.org/",
  "oid": "2.16.840.1.113883.6.1",
  "toolingId": "loinc",
  "settings": {
      "publisher": "Regenstrief Institute, Inc.",
  }
}

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

POST /loinc/LOINC/import -F "file=@Loinc_2.77.zip"

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

POST /versions
{
  "resource": "codesystems/LOINC",
  "version": "2.77",
  "description": "LOINC 2.77 2024-02-27 release",
  "effectiveTime": "2024-02-27"
}

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.

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.

KKÅ

First, create the KKÅ Code System:

POST /codesystems
{
  "id": "kva-kirurgiska",
  "url": "http://klassifikationer.socialstyrelsen.se/kva-kirurgiska",
  "title": "KVÅ – kirurgiska åtgärder (KKÅ)",
  "language": "se",
  "description": "# Klassifikation av kirurgiska åtgärder",
  "status": "active",
  "owner": "ownerUserId",
  "copyright": "",
  "contact": "klassif@socialstyrelsen.se - Avdelningen för register och statistik, Enheten för klassifikationer och terminologi",
  "oid": "1.2.752.116.1.3.2.3.6",
  "toolingId": "lcs",
  "settings": {
    "publisher": "Socialstyrelsen",
    "isPublic": true
  }
}

Then, import the concepts from the official TSV file:

POST /lcs/kva-kirurgiska/import?idColumn=Kod&ptColumn=Titel&synonymColumns=Förkortning(ar)&synonymColumns=Beskrivning&parentColumn=Överordnad%20kod&locale=se -F "file=@kva-kirurgiska-atgarder-kka-2024-01-01.tsv"

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

POST /versions
{
  "resource": "codesystems/kva-kirurgiska",
  "version": "2024-01-01",
  "description": "2024-01-01 release",
  "effectiveTime": "2024-01-01"
}

KMÅ

First, create the KMÅ Code System:

POST /codesystems
{
  "id": "kva-medicinska",
  "url": "http://klassifikationer.socialstyrelsen.se/kva-medicinska",
  "title": "KVÅ – medicinska åtgärder (KMÅ)",
  "language": "se",
  "description": "# Klassifikation av medicinska åtgärder",
  "status": "active",
  "owner": "ownerUserId",
  "copyright": "",
  "contact": "klassif@socialstyrelsen.se - Avdelningen för register och statistik, Enheten för klassifikationer och terminologi",
  "oid": "1.2.752.116.1.3.2.3.5",
  "toolingId": "lcs",
  "settings": {
    "publisher": "Socialstyrelsen",
    "isPublic": true
  }
}

Then, import the concepts from the official TSV file:

POST /lcs/kva-medicinska/import?idColumn=Kod&ptColumn=Titel&synonymColumns=Beskrivning&parentColumn=Överordnad%20kod&locale=se -F "file=@kva-medicinska-atgarder-kma-2024-01-01.tsv"

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

POST /versions
{
  "resource": "codesystems/kva-medicinska",
  "version": "2024-01-01",
  "description": "2024-01-01 release",
  "effectiveTime": "2024-01-01"
}

First, create the ICF Code System:

POST /codesystems
{
  "id": "icf",
  "url": "http://klassifikationer.socialstyrelsen.se/icf",
  "title": "ICF",
  "language": "se",
  "description": "# Internationell klassifikation av funktionstillstånd, funktionshinder och hälsa",
  "status": "active",
  "contact": "klassif@socialstyrelsen.se - Avdelningen för register och statistik, Enheten för klassifikationer och terminologi",
  "owner": "ownerUserId",
  "oid": "1.2.752.116.1.1.3",
  "toolingId": "lcs",
  "settings": {
      "publisher": "Socialstyrelsen",
      "isPublic": true
  }
}

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

POST /lcs/icf/import?idColumn=Kod&ptColumn=Titel&synonymColumns=Beskrivning&synonymColumns=Alternativ%20titel&parentColumn=Överordnad%20kod&locale=se -F "file=@icf-2024-01-01.tsv"

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

POST /versions
{
  "resource": "codesystems/icf",
  "version": "2024-01-01",
  "description": "2024-01-01 release",
  "effectiveTime": "2024-01-01"
}

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

POST /codesystems
{
  "id": "ICD10SE",
  "url": "http://hl7.org/fhir/sid/icd-10-se",
  "title": "ICD-10-SE",
  "language": "se",
  "description": "# Internationell statistisk klassifikation av sjukdomar och relaterade hälsoproblem (ICD-10-SE)",
  "status": "active",
  "owner": "ownerUserId",
  "copyright": "",
  "contact": "https://www.socialstyrelsen.se/statistik-och-data/klassifikationer-och-koder/kodtextfiler/",
  "oid": "1.2.752.116.1.1.1",
  "toolingId": "icd10",
  "settings": {
    "publisher": "Socialstyrelsen",
    "isPublic": true
  }
}

POST /icd10/ICD10SE/classes/import -F "file=@ICD-10-SE_2024_generated.xml"

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

POST /versions
{
  "resource": "codesystems/ICD10SE",
  "version": "2024-01-01",
  "description": "2024-01-01 release",
  "effectiveTime": "2024-01-01"
}

Alternatives

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

• 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

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:

Introduction

HL7's Fast Healthcare Interoperability Resources (FHIR) standard describes data types, resources, interactions, coded values and their associated code systems that are used to represent and exchange structured clinical data.

Thanks to its pluggable and extensible architecture, Snow Owl TS is able to expose clinically relevant resources like code systems, value sets and concept maps in a format that can be consumed by third-party FHIR clients. Additionally, Snow Owl's revision model allows concurrent management of resource versions.

Interactive documentation

Navigate to http://<host>:8080/snowowl/ and select "FHIR API" from the category dropdown to see the full list of FHIR requests supported by Snow Owl TS:

Request/response formats

JSON and XML formats are both supported; resources in Turtle RDF format are not accepted (nor produced) by the server. The MIME type for these formats can appear in the Accept and Content-Type headers. These are the following:

• XML

  • application/fhir+xml

  • application/xml

  • text/xml

• JSON

  • application/fhir+json

  • application/json

  • text/json

Unless explicitly stated in the MIME type, the server accepts and responds in the R5 format. To select an explicit FHIR version format the fhirVersion argument can be used along with the fhir+json/xml media types. For example:

Accept: application/fhir+json;fhirVersion=4.0.1

All declared and provided FHIR endpoints support the following FHIR Specification versions:

Common request parameters

Override response format

Clients can override the desired output format by using the _format query parameter, if they have limited access to request headers. In this case shorthand values like xml and json are also permitted (Content-Type must still be set correctly if the request includes a body):

GET /snowowl/fhir/CodeSystem/SNOMEDCT?_format=xml&_pretty=true

[Response headers]
Content-Type: application/fhir+xml

<CodeSystem xmlns="http://hl7.org/fhir">
  <id value="SNOMEDCT"/>
  <meta>
    <lastUpdated value="2023-10-17T15:03:40.942Z"/>
  </meta>
  <language value="en"/>
  <text>
    <status value="empty"/>
    <div xmlns="http://www.w3.org/1999/xhtml"></div>
  </text>
  <url value="http://snomed.info/sct/900000000000207008"/>
  <name value="SNOMEDCT"/>
  <title value="SNOMED CT International Edition"/>
  <status value="active"/>
  [...]

Snow Owl returns a 406 Not Acceptable response if the client requested a response format it does not support. Conversely, if the request body is in a format it does not recognize, a 415 Unsupported Media Type response is emitted.

Pretty-printing

For development purposes, responses returned from the server can be formatted so they are more pleasing to the human eye. The example above already includes the query parameter that controls this behavior; it is named _pretty. Setting its value to true results in pretty-printed output.

Resource summary

The query parameter _summary controls whether a subset of the elements should be returned for a resource. Supported values are:

• true -> return a pre-defined subset of elements from the resource (these are marked as "summary" in the FHIR specification)

• false -> return all elements of the resource

• text -> return text, id, meta and top-level elements marked as "mandatory" in the FHIR specification (to ensure that the response remains a valid FHIR resource representation)

• data -> remove the text element that contains a human-readable rendering of the resource, in the form of eg. an XHTML snippet

• count -> return hit count without the accompanying list of matching resources (applicable in resource search interactions only)

When summary mode is enabled, returned resources are marked with a SUBSETTED code to indicate that certain elements were left out:

GET /snowowl/fhir/CodeSystem/SNOMEDCT?_summary=text

[Response headers]
Content-Type: application/fhir+json

{
  "resourceType": "CodeSystem",
  "id": "SNOMEDCT",
  "meta": {
    "lastUpdated": "2023-10-17T15:03:40.942Z",
    "tag": [{
      "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationValue",
      "code": "SUBSETTED",
      "display": "As requested, resource is not fully detailed."
    }]
  },
  "text": {
    "status": "empty",
    "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"></div>"
  },
  "status": "active",
  "content": "not-present"
}