Technical documentation of the Service, Support, and Logistics API for eHealth

1. Introduction

1.1. Scope

eHealth is a digital infrastructure backing a number of telemedical solutions offered by public healthcare authorities in Denmark.

Telemedical solutions are used for treatment, care, and prophylactic measures of patients who are overall better treated or monitored in their own homes than through hospital admissions or frequent visits to physicians. Telemedical solutions are focused on specific diseases or conditions such as patients with chronic obstructive pulmonary disease, diabetes, or complicated pregnancies.

When a healthcare practitioner has prescribed a certain telemedical solution to a patient, it is usually necessary to deliver certain medical devices in the patient’s home accompanied by certain services such as installation and configuration of the equipment and training of the patient to use the equipment. When the telemedical solution is no longer relevant the equipment may need to be re-collected.

To manage the support and logistics required to provision medical devices and services in the private homes of patients the eHealth infrastructure contains a component called "Service, Support, and Logistics" — abbreviated "SSL". The SSL component contains functionality to manage providers of equiment and services and their catalogues and for healthcare workers to easily order and trace orders of equipment and services to be delivered.

1.2. Requirements

The SSL component is custom built for regions and municipalities in Denmark based on a technical specification in the public tender for the eHealth infrastructure [INFO].

1.3. Intended audience

This document is a technical manual describing the API of the SSL backend to enable IT architects and programmers to develop SSL-applications for both providers and healthcare workers.

2. The eHealth telemedical system

To set the scene, this section provides background information about the overall architecture of the eHealth system.

2.1. Users

The eHealth telemedical system is used by two categories of users: Patients and employees.

Patients are individuals who are subject to telemedical treatment, and employees are employees of the health care system - such as doctors, nurses or administrative workers. Employees are responsible for the telemedical treatment of patients.

Employees of SSL Providers are also considered to be users of type "employee".

2.2. Main parts

The eHealth system consists of three main parts: The infrastructure, patient applications and employee applications. At the highest level of abstraction the architecture of eHealth can be depicted like this:

Patient applications are used by patients in their homes to submit measurements from medical devices, communicate with doctors, etc. whereas employee applications are used by employees e.g. to administer telemedical treatments, monitor and analyse measurements submitted by patients, and other clinical tasks.

Patient and employee applications are interacting through the "eHealth Infrastructure" which provides services to the applications. Example of services are: Data persistence, data distribution, clinical triaging, patient and employee notifications, security, and more.

2.2.1. The infrastructure part

The eHealth Infrastructure is divided into a number of independent microservices. Each microservice offers its services to applications by exposing an API. API’s of the Infrastructure are largely based on a standard called HL7 FHIR [HL7FHIR] which is widely used in medical IT systems all over the world.

In practice, this means that most microservices of the eHealth Infrastructure offer a RESTful HTTP-based API with resources defined by the HL7 FHIR standard. The eHealth Infrastructure can therefore be thought of as a number of microservices exposing HL7 FHIR API’s like this:

It is anticipated that a number of patient and employee applications will follow a design pattern called "backend for frontend" [BFF]. With this pattern each application is allowed to deploy a backend component co-located with the eHealth Infrastructure to support the front-end applications. The BFF’s can for instance provide their own persistent storage and map between the HL7 FHIR format and whichever formats are preferred by the client applications. This is utilized by SSL which deploys a BFF component co-located in the same Kubernetes cluster as the eHealth Infrastructure.

3. The Service, Support, and Logstics application

"SSL" (Service, Support, and Logistics) is an employee application.

The SSL application utilises the BFF pattern described above and hence has a BFF component exposing a RESTful JSON-based API colocated with the eHealth Infrastructure. The FHIR-based eHealth Infrastructure has no knowledge of the SSL BFF and will never make any requests to it. But some calls to the SSL BFF result in calls to the HL7 FHIR-based API’s.

The deployment can be depicted like this:

3.1. Microservices

In the actual deployment the eHealth SSL BFF consists of three microservices:

ssl-catalogue
ssl-catalogue-excel
ssl-order

ssl-catalogue is responsible for information about SSL catalogues and items. ssl-order is responsible for managing orders and track-and-trace information, and ssl-catalogue-excel offers operations to upload SSL catalogues in Microsoft Excel format.

The green component "eHealth SSL BFF" in practice therefore looks like this:

The purpose of this document is to define and describe the API’s offered by the three BFF services ssl-order, ssl-catalogue, ssl-catalogue-excel and to document the interactions with the eHealth Infrastructure - so that UI applications can be developed.

3.2. Actors

The following user types can use the SSL BFF:

Table 1. Actors in the SSL domain.
Actor	Definition
AdministrativeClerk	An administrative worker in the health care provider’s organization with no access to patient-related or clinical data. AdministrativeClerks may be utilized to maintain contracts and parties in SSL Governance and catalogue, catalogue items and annotations in SSL Catalogues.
MonitoringResponsible	A health care employee with access to sensitive health related data and who can create and submit orders and is responsible for seeing them fulfilled. MonitoringResponsibles are intended to communicate with patients, to search SSL Catalogues and to issue SSL Orders.
Provider	An organization, a or person working for an organization, responsible for fulfulling an order. Providers are intended to provide catalogues and catalogue items, either directly through the SSL BFF, or by means of an AdminstrativeClerk. Providers may also use SSL Orders to discover and maintain SSL orders.

These actor types correspond to JWT user types stamped into JWT tokens.

3.3. Resources

The microservices of the SSL BFF expose a number of REST resources. This diagram shows each microservice and the REST resources they expose:

The same diagram in greater detail shows how these resources are related to other resources in the SSL domain and also FHIR resources in the HL7 FHIR-based clinical backend:

3.4. SSL-Catalogue

The ssl-catalogue microservice holds information about catalogues from different providers. Each catalogue contains a number of orderable catalogue items (in the form of services and device models). Catalogue items can be annotated with buyer-specific annotations to facilite advanced searching for items with certain qualities. The service also holds black lists so that a specific patient can have an item black-listed (non-orderable for that patient) and white lists, to make items orderable to specific organizations.

The resources exposed by this microservice are:

Table 2. Resources exposed by SSL Catalogue.
Resource	Definition	Inspired by
Catalogue	A list of device models and services which a provider can deliver under the terms of a given contract.	OIOUBL Catalogue
Service	A medical or device-related service which can be ordered for the treatment of a patient.	OIOUBL Catalogue.CatalogueLine OIOUBL Catalogue.CatalogueLine.Item
DeviceModel	A medical device model of a given brand which can be ordered for the treatment of a patient.	OIOUBL Catalogue.CatalogueLine OIOUBL Catalogue.CatalogueLine.Item
Annotation	A annotation of a CatalogueItem using customer specified annotation values
WhiteList	A white list is a list of catalogue items available to a buying organization. Only items in a catalogue explicitly pointed out by an organization’s white list can be ordered by that organization.
BlackList	A black list is a list of catalogue items unwanted or undesirable to a patient.

3.5. SSL-Order

The SSL Orders microservice manages the fulfillment of orders from healthcare practitioners to SSL providers. Healthcare practitioners can create orders for delivery or pickup of medical devices and for the provisioning of services, such as training of the patient in the use of a device, or technical support, maintenance, repairs, and replacement of specific devices already in use. Health care practitioners can trace the progress of each order.

The support this the SSL Orders microservice also holds relatively static information about SSL providers and organizations in the healthcare system which can order and finance equipment and services from the SSL providers. The service keeps track of which of these parties have contracts with each other, so that items can only be ordered from SSL providers with a valid contract.

The resources exposed by this microservice are:

Table 3. Resources exposed by SSL Catalogue.
Resource	Definition	Inspired by
Contract	A legal agreement between an organization and a provider which enables that a provider can deliver devices and services to a buying party.	OIOUBL Contract
Party	A legal party which is engaged into a Contract. Parties can have different roles such as buyer, seller and accounting. A seller is a legal entity inside or outside the healthcare system which is capable of providing catalogue items under the terms of a contract. A buyer is a clinical organization in the healthcare system which is related to a contract in a role enabling it to order devices and services from a provider. An accounting party is an administrative organization in the healthcare system which can receive invoices and execute payments to providers.	OIOUBL Party OIOUBL Order.SellerSupplierParty OIOUBL Order.BuyerCustomerParty OIOUBL Order.AccountingCustomerParty
Order	An order for devices or services made by a practioner and to be fulfilled by a provider in relation to the medical treatment of a patient.	OIOUBL Order
OrderLine	An request for a specific action (e.g. delivery, pickup, repair) to be fulfilled in relation to a specific item or an item which can be ordered fra a catalogue.	OIOUBL Order.OrderLine
TraceLine	A trace line describing the progression of an order.

3.5.1. Order states

Order resources have a property termed status of type Coding which can contain values from the value set http://ehealth.sundhed.dk/vs/order-status.

The order state can be changed through an update operation. The following are legal state changes:

3.6. Coding values

The following fields are validated against the terminology server and must have values from the given legal systems/codes:

Field System Codes

Field	System	Codes
`Catalogue.status`	<TBD>	`DRAFT`, `CURRENT`, `RETIRED`
`CatalogueItem.status`	<TBD>	`AVALABLE`, `UNAVAILABLE`, `RETIRED`
`Annotation.status`	<TBD>	`DRAFT`, `ACTIVE`, `RETIRED`
`Order.status`	<TBD>	`DRAFT`, `SUBMITTED`, `ASSIGNED`, `VALIDATED`, `CONDITIONALLY_ACCEPTED`, `CONDITIONS_ACCEPTED`, `DECLINED`, `ACCEPTED`, `TIME_OF_FULFULLMENT_AGREED`, `FULFILLED`, `REVOKED`
`OrderLine.status`	<TBD>	`UNFULFILLED`, `FULFILLED`
`OrderLine.action`	<TBD>	`PICKUP`, `DELIVER`, `REPAIR`, `REPLACE`, `REPAIRORREPLACE`, `MAINTENANCE`

Catalogue.status

<TBD>

DRAFT, CURRENT, RETIRED

CatalogueItem.status

<TBD>

AVALABLE, UNAVAILABLE, RETIRED

Annotation.status

<TBD>

DRAFT, ACTIVE, RETIRED

Order.status

<TBD>

DRAFT, SUBMITTED, ASSIGNED, VALIDATED, CONDITIONALLY_ACCEPTED, CONDITIONS_ACCEPTED, DECLINED, ACCEPTED, TIME_OF_FULFULLMENT_AGREED, FULFILLED, REVOKED

OrderLine.status

<TBD>

UNFULFILLED, FULFILLED

OrderLine.action

<TBD>

PICKUP, DELIVER, REPAIR, REPLACE, REPAIRORREPLACE, MAINTENANCE

Note	The selected set of fields validated against the FHIR terminology server and the range of legal codes is subject to change.

4. API design guidelines

4.1. Specifications

The SSL BFF API’s are defined using the OpenAPI Specification version 2.0 [OAS2].

4.2. Media types

The SSL BFF API’s exchange data with clients using media type application/json.

4.3. OIOUBL resemblance

Names of resources used in relation to SSL are to a reasonable degree aligned with entities defined in "NemHandel" [OIOUBL].

4.4. Versioning

Microservices in the eHealth infrastructure use semantic versioning [SEMVER]. So given given a version number MAJOR.MINOR.PATCH, we increment the:

MAJOR version for incompatible API changes,
MINOR version for functionality changed in a backwards-compatible manner, and
PATCH version for backwards-compatible bug fixes.

Example

Microservice ssl-catalogue-1.2.1 exposes its services on:

https://ehealth.sundhed.dk/ssl-catalogue/v1/catalogue

4.5. Base URLs

The base url of SSL BFF’s are: https://ehealth.sundhed.dk/ssl-<MICROSERVICE>/v<MAJOR>/.

Example

Base URL of ssl-catalogue:

https://ehealth.sundhed.dk/ssl-catalogue/v1/

4.6. Security

The SSL component shares a JWT-based security model with other parts of the eHealth infrastructure.

Some operations may require certain permissions and user types stamped into JWT tokens, otherwise HTTP status code 401 Unauthorized or 403 Forbidden will be returned.

Note	The exact payload of JWT tokens, including the format and values of permissions and user types, is documented in a separate document related to the eHealth Infrastructure. When this document is released it will be referenced here.

4.7. Resource id’s

All resource id’s are assigned server-side. Id’s are opaque and clients can make no assumptions about them.

4.8. Resource reference formats

4.8.1. In request body

References to other resources (regardles whether they are FHIR or REST resources) are expressed as fully qualified URL’s.

Reference URL’s are resolvable.

Example

Reference to an SSL resource:

{
   ...
   "seller": ""http://ehealth.sundhed.dk/ssl-order/v1/party/b83e7b2e-779f-44fc-9c4d-b1f564303a31"
   ...
}

Example

Reference to an clinical FHIR resource:

{
   ...
   "organization": "https://ehealth.sundhed.dk/organization/fhir/Organization/15241"
   ...
}

4.8.2. In query parameters

Sometimes references are required as HTTP query parameters. In this case the entire URL pointing out a referenced resource is used in the query parameter. Like this:

Example

Reference to an SSL resource:

https://ehealth.sundhed.dk/ssl-order/v1/trace-line?order=https%3A%2F%2Fehealth.sundhed.dk%2Fssl-order%2Fv1%2Forder%2F3374f389-aac6-4e98-9e85-16b32c563c27

4.9. Code values

Some fields of the SSL REST resources are of a type called Coding. These fields are intended to comply with the Coding data type from the HL7 FHIR standard [HL7COD].

4.10. Concurrency and locking

The SSL microservices are expected to experience low resource contention, and hence use "last writer wins" policy.

4.11. Patch operations

The body of HTTP PATCH requests must comply with the JSON Patch format [JSONPATCH].

5. API specifications

Technical API specifications in OpenAPI format [OAS2] can be downloaded in different versions and formats for each microservice here:

Table 4. Technical API specifications
Microservice	v1.0.0
ssl-order	Raw	HTML
ssl-catalogue	Raw	HTML
ssl-catalogue-excel	Raw	HTML

The raw swagger.yaml files can be used to generate client stubs in different programming languages using swagger-codegen - or they can be read in a more human-friendly format by pasting them into Swagger Editor. An hosted, online instance of Swagger Editor can be found at http://editor.swagger.io.

6. Example use cases

The OpenAPI specifications given above define the exact operations including inputs and outputs which are supported by the SSL microservices. As an additional aid and guidance for the intended usage, this section contains selected examples of concrete usages.

6.1. Catalogues

6.1.1. Create a catalogue

POST /ssl-catalogue/v1/catalogue
{
  "name": "A catalogue",
  "seller": "https://ehealth.sundhed.dk/ssl-order/v1/party/aac960cf-884d-4a38-bf88-ad9922c6437a",
  "status": {
    "system": "http://ehealth.sundhed.dk/vs/catalogue-status",
    "code": "DRAFT"
  }
}

-->

HTTP/1.1 201 Created
Location: https://ehealth.sundhed.dk/ssl-catalogue/v1/catalogue/d47c3104-e656-46a3-b740-daf8bb0288f0

6.1.2. Search for catalogue items with certain annotations

Search all catalogues available to buyer "https://ehealth.sundhed.dk/ssl-governance/v1/party/d36202ed-4751-449b-a371-53a94b6b3ca4" for items annotated with "http://ehealth.sundhed.dk/vs/device-measuring-type/forced-expiratory-volume" and "http://ehealth.sundhed.dk/vs/device-button-size/large".

GET /ssl-catalogue/v1/catalogue-items?buyer=https://ehealth.sundhed.dk/ssl-governance/v1/party/d36202ed-4751-449b-a371-53a94b6b3ca4&annotation=http://ehealth.sundhed.dk/vs/device-measuring-type/forced-expiratory-volume&annotation=http://ehealth.sundhed.dk/vs/device-button-size/large

-->

HTTP/1.1 200 OK

[
  {
    "id": "12a68cc8-cee5-433d-a662-8f02ea494fa8",
    "identifiers" : [ {
      "system" : "urn:ietf:rfc:3986",
      "assigner" : "Danish Health Authorities",
      "value" : "NUC8766"
    },
    "catalogue": "https://ehealth.sundhed.dk/ssl-catalogue/v1/catalogue/12738808-a816-4342-b063-ada645e9a894",
    "catalogueItemType": "DeviceModel",
    "name": "Spirometer",
    "manufacturer": "Alphaworks",
    "model": "SuperSpiro IV"
    "description" : "Multipurpose spirometer for wheel chair mounting. Battery supply only. No powerbrick."
  },
  {
    "id": "1c2803e3-c387-411f-9dc3-dc6f437187dc",
    "catalogue": "https://ehealth.sundhed.dk/ssl-catalogue/v1/catalogue/daa4123f-116d-4eb9-bfc0-dbf1369d9dc9",
    "catalogueItemType": "DeviceModel",
    "name": "Spirometer",
    "manufacturer": "Betaworks",
    "model": "MegaSpiro Nano"
  }
]

6.2. Orders

6.2.1. Create an order

An order is created through a HTTP POST operation. If no status is assigned it will be assigned status DRAFT by the server. If the status field is supplied in the POST operation only status DRAFT is accepted.

POST /ssl-order/v1/order
{
  "name": "A catalogue",
  "buyer": "https://ehealth.sundhed.dk/ssl-governance/v1/party/84fd4bb4-3f8d-4a60-9a36-8b190ad0c0de",
  "seller": "https://ehealth.sundhed.dk/ssl-governance/v1/party/e2dee7bf-0f34-4006-92b9-78bda9777781",
  "receiver": {
    "name": "Demo Demoson",
    "addressLine 1": "Demo Avenue 1",
    "postalCode": "9999",
    "postalDistrict": "Demo City",
    "email": "demo@demo.com",
    "patient": "https://ehealth.sundhed.dk/patient/fhir/Patient/1566241"
}

-->

HTTP/1.1 201 Created
Location: https://ehealth.sundhed.dk/ssl-order/v1/order/2d013eda-a8ef-49d7-b561-93efd6b14e54

6.2.2. Add an order line

POST /ssl-order/v1/order-line
{
  "order": "https://ehealth.sundhed.dk/ssl-order/v1/order/2d013eda-a8ef-49d7-b561-93efd6b14e54",
  "status": {
    "system": "http://ehealth.sundhed.dk/vs/order-line-status",
    "code": "SUBMITTED"
  },
  "item": "https://ehealth.sundhed.dk/ssl-catalogue/v1/catalogue-item/1c2803e3-c387-411f-9dc3-dc6f437187dc",
  "action": {
    "system": "http://ehealth.sundhed.dk/vs/order-line-action",
    "code": "DELIVER"
  }
}

-->

HTTP/1.1 201 Created
Location: https://ehealth.sundhed.dk/ssl-order/v1/order-line/c09082de-4f06-4b4b-bac6-e8e4379be0ae

6.2.3. Submit an order

An order is submitted to an SSL provider by updating its status from DRAFT to SUBMITTED. This can be done through e.g. an HTTP PATCH operation:

PATCH /ssl-order/v1/order/2d013eda-a8ef-49d7-b561-93efd6b14e54
{
    { "op": "replace", "path": "/status/code", "value": "SUBMITTED" }
}

-->

HTTP/1.1 204 No Content

6.2.4. Get all details of an order

GET /ssl-order/v1/order/2d013eda-a8ef-49d7-b561-93efd6b14e54/details

-->

{
  "id": "2d013eda-a8ef-49d7-b561-93efd6b14e54",
  "identifier": [
    {
      "system": "urn:oid:1.0.15961.8.21"
      "value": "4312879"
      "assigner": "Andeby Plasterforsyning ApS"
    }
  ],
  "status": {
    "system": "http://ehealth.sundhed.dk/vs/order-status",
    "code: "fulfilled",
    "display": "Afsluttet"
  },
  "notes": [
    {
      "timestamp": "2019-04-23T18:25:43.000Z"
      "authorName": "Hans Hansen"
      "authorOrganization": "Region Jylland"
      "note": "Må afleveres hos naboen"
    }
  ],
  "buyer": "https://ehealth.sundhed.dk/ssl-governance/v1/party/84fd4bb4-3f8d-4a60-9a36-8b190ad0c0de",
  "seller": "https://ehealth.sundhed.dk/ssl-governance/v1/party/e2dee7bf-0f34-4006-92b9-78bda9777781",
  "receiver": {
    "name": "Mod Tagersen"
    "addressLine 1": "Storegade 52"
    "postalCode": "9999"
    "postalDistrict": "Xkøbing"
    "email": "private@mail.dk"
    "phone": "9999 9999"
    "clinicalRef": "https://ehealth.sundhed.dk/patient/fhir/Patient/1566241"
  },
  "orderLines": [
    ... All order lines
  ],
  "traceLines": [
    ... All related traces lines sorted by timestamp.
  ]
}

6.2.5. Trace an order

GET /ssl-order/v1/trace-lines?order=https://ehealth.sundhed.dk/ssl-order/v1/order/2d013eda-a8ef-49d7-b561-93efd6b14e54

-->

HTTP/1.1 200 OK

{
  [
    "id": "db491f2e-4a7a-4090-91eb-9a9f2e3d3f1d",
    "timestamp": "2019-04-23T18:25:43.000Z",
    "createdByOrganization": "Xkøbing Kommunes Hjælpemiddelcentral",
    "text": "Bestilling nr. 14131 er foretaget",
    "order": "https://ehealth.sundhed.dk/ssl-order/v1/order/2d013eda-a8ef-49d7-b561-93efd6b14e54",
    "statusChange": {
      "subject": "https://ehealth.sundhed.dk/ssl-order/v1/order/2d013eda-a8ef-49d7-b561-93efd6b14e54"
      "oldStatus": {
        "system": "https://ehealth.sundhed.dk/vs/order-status",
        "code": "DRAFT"
      },
      "newStatus": {
        "system": "https://ehealth.sundhed.dk/vs/order-status",
        "code": "SUBMITTED"
      }
    }
  ]
}

6.3. Other

6.3.1. Support requests

Use cases involving "support" in the SSL domain are handled by existing functionality in both the SSL component and in the clinical FHIR-based backend. Therefore there is no separate ssl-support microservice. Instead SSL support is handled through:

FHIR Communication and SSL Orders for monitoring responsibles
SSL Orders for providers

Monitoring responsible receives a support request from a patient

If a patient decides to raise a support request, the patient contacts the monitoring responsible through normal means of communation such as email, telephone or similar. The monitoring responsible ensures, that a proper FHIR Communication resource is created to capture the patient’s request.

The monitoring responsible may search for similar problems and potential solutions outside the scope of the SSL component. If a solution is found the monitoring responsible will send a proper Communication to the patient. If the monitoring responsible does not find a workable solution (s)he may escalate the issue to an SSL provider.

Monitoring responsible requests technical support from SSL provider

When a monitoring responsible decides to escalate a support issue to an SSL provider, this is done by issuing an SSL order in exactly the same way as if a device or a patient training service was requested.

This implies, that catalogues must contain catalogue items representing support services, such as requests to provide repair, maintenance, replacement or support-in-usage.

To request e.g. a repair of a device, the monitoring responsible will create an order, with an order line expressing a request to repair a specific device. This is expressed in the following sequence diagram:

7. Bibliography

[HL7FHIR] "Welcome to FHIR", http://hl7.org/fhir/
[BFF] "Pattern: Backends For Frontends", written on Nov 18 2015 by Sam Newman, https://samnewman.io/patterns/architectural/bff/
[HL7COD] "HL7 Data Types", https://www.hl7.org/fhir/datatypes.html#Coding
[OAS2] "OpenAPI Specification (fka Swagger RESTful API Documentation Specification), Version 2.0", https://swagger.io/specification/v2/.
[INFO] "Informationsvideoer om FUT" (in Danish), https://digst.dk/digital-service/digital-velfaerd/telemedicin-kol/faelles-udbud-af-telemedicin-fut/informationsvideoer/
[OIOUBL] "Introduction to OIOUBL", http://www.oioubl.info/classes/en/index.html.
[SEMVER] "Semantic Versioning 2.0.0", https://semver.org/.
[JSONPATCH] "JSONPatch.com", http://jsonpatch.com/.
[K8S] "What is Kubernetes", https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/.
[DOCKER] "Docker Documentation", https://docs.docker.com/

Technical documentation of the Service, Support, and Logistics API for eHealth - telemedical infrastructure