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 equipment and services and their catalogues and for healthcare workers to easily order and trace orders of equipment and services to be delivered.

1.2. Purpose

The purpose of this document is to describe the APIs offered by the SSL backend - so that SSL applications can be developed. The SSL backend consists of the two SSL microservices; ssl-order, ssl-catalogue

Furthermore, this document describes the SSL backend interactions with the eHealth Infrastructure

1.3. Terms and definitions

Table 1. Terms and Definitions
Term	Definition
SSL Provider	Organisation that can provide services and/or devices/equipment to a citizen in a medial treatment.
SSL Supplier	Same as SSL Provider
Employee	Employees of the health care system - such as doctors, nurses or administrative workers, or employees of an SSL provider.
Patient applications	Applications used by patients in their homes to submit measurements from medical devices, communicate with doctors, etc.
Employee applications	Applications are used by employees e.g. to administer telemedicine treatments, monitor and analyse measurements submitted by patients, and other clinical tasks.
SSL Component	The SSL solution consists of SSL application, SSL API and an SSL backend.
SSL Application	The SSL application is an employee application built on top of the SSL API.
SSL API	The Application Programming Interface provided by SSL Backend.
SSL Backend	Provide API to develop SSL applications.
Catalogue or SSL catalogue	A catalogue of services and devices that healthcare can be ordered to be delivered as part of a medical treatment.
Item	An item in a catalogue. That is, either a Service or DeviceModel.
Device Model	A medical device model of a given brand which can be ordered for the treatment of a patient.
Device	The actual medical device or equipment delivered or installed in a patient or citizens home as part of medical treatment
Equipment	See device
Service	A Service is an activity performed by SSL Provider. This can be installing and configuration of the equipment and training of the patient to use the equipment.

1.4. 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.5. Intended audience

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

1.6. Document history

Table 2. Document changes
Revision	Date	Responsible	Description
1.0	2021-05-05	OLL, Systematic	Added this log to the document
1.1	2022-01-11	JOS, Systematic	Added terms and definition. Added use cases diagrams. Moved some sections around to improve readability.

2. The eHealth telemedical system

This section describes the overall architecture of the eHealth telemedical system.

2.1. eHealth Users

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

Patients are citizens who are subject to telemedical treatment.
Employees are employees of the health care system - such as doctors, nurses or administrative workers, or employees of SSL providers.

Employees are responsible for the telemedical treatment of patients.

2.2. Main parts

The eHealth system consists of three main parts:

eHealth infrastructure,
eHealth patient applications and
eHealth employee applications.

At the highest level of abstraction the architecture of eHealth can be depicted like this:

2.2.1. eHealth Infrastructure

The eHealth Infrastructure are largely based on a standard called HL7 FHIR [HL7FHIR] which is widely used in medical IT systems all over the world.

The eHealth Infrastructure is divided into a number of independent microservices. Each microservice offers its services to applications by exposing an API.

In practice, this means that most microservices of the eHealth Infrastructure offer a REST 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 APIs like this:

2.2.2. Patient applications

Patient applications are used by patients in their homes to submit measurements from medical devices, communicate with doctors, etc.

2.2.3. Employee applications

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.

3. The Service, Support, and Logistics (SLL) Architecture

3.1. SSL Backend, Microservices and Resources

The SSL backend is part of the eHealth Infrastructure.

The SSL backend consists of two microservices:

ssl-order service
ssl-catalogue service

ssl-order service is responsible for managing orders and track-and-trace information.

ssl-catalogue service is responsible for SSL Catalogues and items and offers operations for both upload and download of SSL Catalogues and items, in Microsoft Excel format.

Note	The used Excel for downloading and uploading to the SSL Catalogue is version 16.0 build 13127.21064. Use an Excel compliant version.

The ssl-order and ssl-catalogue services expose a number of REST resources in JSON format. Calling an SSL API might result in calls to the HL7 FHIR-based APIs.

The diagram below shows the microservice and the REST resources they expose:

3.1.1. `ssl-catalogue` resources

The ssl-catalogue service 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 facilitate advanced searching for items with certain qualities.

The service also holds blacklists 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 3. ssl-catalogue resources.
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
CatalogueItem	An object with the common attributes for Service and DeviceModel	OIOUBL Catalogue.CatalogueLine
CatalogueTemplate	A CatalogueTemplate is a template for Catalogues in Microsoft Excel format. The CatalogueTemplate can be downloaded from the service to for the basis for the SSL provider to create a Catalogue to be added.
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 OIOUBL Catalogue.CatalogueLine.Item
Annotation	An 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 blacklist is a list of catalogue items unwanted or undesirable to a patient.
Package	A package is a collection of white lists available to a buying organization. A package is typically used to define a collection of DeviceModels and Services for the treatment of a specific condition. Only packages with status `ACTIVE` should be used when using packages to build orders.
Problem	A problem is a description of a problem to a specific device model. A problem have a references to the affected catalogue items have and have may a known resolution

3.1.2. `ssl-order` Resources

The ssl-order 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.

To support this the ssl-order 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.

Table 4. The resources exposed by the ssl-catalogue service.
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 practitioner and to be fulfilled by a provider in relation to the medical treatment of a patient.	OIOUBL Order
OrderLine	A 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 from a catalogue.	OIOUBL Order.OrderLine
TraceLine	A trace line describing the progression of an order.

3.2. Relations to resources in Clinical Domain

The REST resources in the SSL domain have relations to each other, and to resources in the Clinical and Administrative domain. The diagram below shows how SS resources are related to each other, and relations to FHIR resources in the HL7 FHIR-based clinical backend:

4. SSL Actors and Use Cases

This section describes the actors in the SSL domain.

An Actor is a person, organization, or system that has a role that initiates or interacts with activities.

An Actor may have a number of Roles. A Role is the part an actor plays in an organization and the contribution they make through the application of their skills, knowledge, experience, and abilities. A ROle is the expected function of an actor, or the part somebody or something plays in a particular activity.

Table 5. Actors and roles in the SSL domain.
Actor type	Actor	Definition and Roles
Clinical	Healthcare Provider or Care Provider	A health care or care provider is an organization licensed to provide health care diagnosis and treatment services including medication, surgery and medical devices.
SSL	SSL Provider (SSL leverandør)	An organization responsible for fulfilling an order. SLL Providers can provide catalogues and catalogue items, either directly through SSL application or API, or by through an Administrative Clerk. SSL Providers use the ssl-order API to search and maintain SSL orders.
SSL	SSL Employee	A person working for an SSL provider responsible for fulfilling an order. Roles SSL Catalogue Responsible (Katalogansvarlig) Service and Logistic (Service og logistik samarbejdspartner) Incident Manager (Support samarbejdspartner) Incident Reporter (Fejlmelder)
Administrative	Administrative Clerk	An administrative worker in the healthcare provider’s organization. Administrative clerks maintain contracts, parties and annotations in SSL Catalogues. Roles SSL Contract Responsible (Aftaleansvarlig) Clinical Administrator (Pakke- og forløbsbygger) Incident Reporter (Fejlmelder)
Clinical	Monitoring Responsible	A health care employee in a healthcare provider’s organization. A Monitoring Responsible can search SSL Catalogues and create and submit SSL Orders, querying orders. Roles * Incident Reporter (Fejlmelder)
Clinical	Practitioner	A health care employee in a healthcare provider’s organization. A practitioner uses the SSL API indirectly using employee applications.

4.1. Use Cases

This section provides contains a use case diagram for the SSL domain.

On the left, the actors introduced above are shown. The middle shows example applications that the actors interact with. And finally on the right, the SSL backend and its microservices.

There are a number of systems or applications involved in the use cases:

SSL application - This is the eHealth UI application provided as part of the eHealth infrastructure. The SSL Application provides end-user access to part of the functionalities or services provided by the SSL backend.
SSL Supplier IT - This is the SSL Supplier custom application. The SSL Supplier IT can be their ERP system that uses the SSL API provided by the eHealth infrastructure.
Employee application - Employee application is external application. This could be any employee application for eHealth. The Employee application is included in the drawing to show that the use case for e.g. creating and submitting orders are not available in the SSL application.
SSL backend - The SSL backend as described above consisting of the two services: ssl-order-service and ssl-catalogue-service.

4.2. Activities

The use cases or activities requires some data or output from other activities. This section illustrates an example of the sequence of these activities, e.g. a Seller Party needs to be created before catalogues can be created, and catalogues are required before creating whitelist and packages etc.

Notice this is just an example, and other sequences can work as well.

In the following section some of the use cases or activities are elaborated into sequence diagrams.

4.2.1. Maintain parties

Parties can be created using either the API or the SSL application.

Notice, Party has a reference to a "FHIR Organisation", and the "FHIR Organization" must exist in the Administrative domain to be able create a Party.

In the following some of these activities are elaborated in UML sequence-diagrams.

4.2.2. Maintain Catalogue and Catalogue Items

The SSL Provider must be created in the SSL Domain as Party with the Party.Role SELLER in order to be able to create, read, update or delete Catalogues.

Catalogues can be created either using the API or the SSL application.

Large SSL providers will have the ability to integrate their ERP systems into the Solution through Infrastructure’s SSL-facing APIs.

SSL Provider creating a catalogue using the SSL application:

Creating a catalogue using the API:

4.2.3. Manage Package

A Package groups one or more SSL CatalogItems from a buyer’s whitelist. A package ensures that included CatalogItems are added to a desired package so that the collection can be searched in this way.

Prerequisite

One or more Catalogues are created
One or more Whitelists are created

Packages as managed through the SSL Application by the administrative clerk.

4.2.4. Order delivery

The use case for Order Delivery involves both SSL resources and the Clinical FHIR resources. The flow can be like this.

There are two examples of Order Delivery, one Deliver a Device, and other for delivering a service
Notice, the creation of a CarePlan for the Patient takes place before this flow.

Order delivery (Device):

The Order delivery (Device) use case as a sequence diagram.

The practitioner does one of the following:
1. Searches his FHIR organizations whitelist for a package of CatalogItems through the use of a package reference
2. Searches his FHIR organizations whitelist for CatalogItems which are annotated with the NPU code required for the activities in patients CarePlan
The practitioner:
1. Create an SSL order based on one or more of the search results for the Patient, references the Patient on the order and sets a receiving address for the order
2. Releases the SSL order by assigning it to an SSL seller and
3. Setting the status to Submitted
The SSL seller
1. Gets the order from the SSL GUI or SSL API
2. Sets out to fulfill the order, in that regard the SSL order is shifting state a number of times, ex. when the time of fulfillment has been agreed (TimeOfFulfillmentAgreed)
The SSL seller employee
1. Delivers the order and sets the status of the individual SSL orderlines to Fulfilled and
2. Set the status on the entire SSL order to 'Fulfilled'
The SSL Backend:
1. Receives the status updates and is now in a position where FHIR resources in the clinical domain have to be created, the steps are
2. A Device resource is created with an identifier set to the external ID entered by the SSL seller employee.
3. A DeviceUseStatement resource is created with reference to the Device and the Patient, found on the SSL Order/OrderLine
4. A DeviceMetric resource is created and linked to the Device. Annotations linked to the SSL DeviceModel are used for setting DeviceMetric attributes like quality attributes

Order Delivery (Service)

The sequence below examplifies the flow if it is service order (example PICKUP).

The Patient calls in and informs that the Device is broken
The Practitioner creates an SSL Order with an SSL Service item of type PICKUP, and with a reference to the FHIR Device to be picked up
The Practitioner releases the SSL Order to the SSL seller
The SSL seller gets the order from the SSL GUI or SSL API, and sets out to fulfill the order, in that regard the SSL Order is shifting state a number of times, ex. when the time of fulfillment has been agreed
The SSL seller employee delivers the order and sets the individual orderlines to fulfilled and fulfills the entire order
The SSL API receives the status updates and is now in a position where the existing FHIR resource DeviceUseStatement can be updated
1. it is retrieved based on FHIR Device and FHIR Patient references on the SSL Order / OrderLine
2. it is updated by setting status to Completed (The device is no longer being used)

The above use case as a sequence diagram.

These service types have impact on clinical resources (Device, DeviceMetric, DeviceUseStatement):

CALIBRATION,
PICKUP,
REPAIR,
DELIVER

These service types do not have an impact on clinical resources:

TRAINING,
RE-TRAINING,
MAINTENANCE,
REPLACE,
INSTALL

See implementation guide for values: https://docs.ehealth.sundhed.dk/latest/ig/CodeSystem-ehealth-device-service-types.html

The service type REPLACE is not used. The use-case is handled by an orderline of type service (PICKUP) and another orderline with a new Device (the replacement).

4.3. Other use cases

4.3.1. FHIR Communication

SSL Orders can be associated to FHIR Communication resources in the Clinical domain.

The association is created by assign Communication (of profile eHealth-message) element Communication.ehealth-thread-id to the value from Order.threadId.

This shall be done for messages created from the SSL domain.

The Order.threadId field is ignored in input at Order creation and update as the value is set server-side by the service.

4.3.2. Support requests

Use cases involving "support" in the SSL domain are handled by functionality in both the SSL application and in the clinical FHIR-based backend.

SSL support is handled through:

Monitoring Responsible handles support through the FHIR Communication service and the ssl-order service
SSL Providers handle support through the ssl-order service

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

5. API design guidelines

5.1. Specifications

The SSL APIs are defined using the OpenAPI Specification version 3.0 [OAS3].

5.2. Media types

The SSL APIs exchange data with clients using media type application/json.

5.3. OIOUBL resemblance

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

5.4. Versioning

Microservices in the eHealth infrastructure use semantic versioning [SEMVER]. So 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://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/catalogue

5.5. Base URLs

The base url of SSL microservices are:

https://{MICROSERVICE}.{ENVIRONMENT}.ehealth.sundhed.dk/v{MAJOR}/

The MICROSERVICE variable can take on the following values:

ssl-catalogue
ssl-order

The ENVIRONMENT variable can take on the following values:

inttest
exttest
preprod
prod

The MAJOR variable is the major version as described in Versioning.

Example

Base URL of ssl-catalogue service in inttest environment is:

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

The URL expresses the desired MAJOR version of the API to use. Therefore, the user must define which specific MAJOR version of the API is desired by setting it in the URL.
If a new version of the API is released, the user must then use this new version in the URL, in order to use the new version of the API.

Example

Assuming a situation with two supported API versions and the user wants to perform an operation on catalogue/1337.
If the user desires to use API version 1 the reference used must reflect it.

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

If the user desires to use API version 2 the reference used must reflect it.

https://ssl-catalogue.inttest.ehealth.sundhed.dk/v2/catalogue/1337

It has not yet been decided whether multiple simultaneous versions will be supported.

5.6. Security

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

For the SSL Services the JWT user_type can be either SYSTEM, PRACTITIONER or SSL.

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. The document can be found here [SSL-ACCESS-CONTROL].

5.7. Resource id’s

All resource Ids are assigned server-side. Ids are opaque and clients can make no assumptions about them.

5.8. Resource reference formats

5.8.1. In request body

References to other resources (regardless whether they are FHIR or REST resources) are expressed as fully qualified URLs.

Reference URLs are resolvable.

Example

Reference to an SSL resource:

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

Example

Reference to a clinical FHIR resource:

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

5.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%2Fssl-order.inttest.ehealth.sundhed.dk%2Fv1%2Forder%2F3374f389-aac6-4e98-9e85-16b32c563c27

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

5.10. Concurrency and locking

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

5.11. Patch operations

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

6. API specifications

Technical API specifications are presented in Swagger-UI and can be downloaded in an OpenAPI format [OAS3] through the /swagger.yaml link on each Swagger-UI page. The specification is available for each environment microservice and for each environment. The different specifications can be viewed and downloaded here:

Table 6. Swagger-UI API documentation
Microservice	EXTTEST	PREPROD	PROD
ssl-order	Swagger-UI	Swagger-UI	Swagger-UI
ssl-catalogue	Swagger-UI	Swagger-UI	Swagger-UI

The swagger.yaml files can be used to generate client stubs in different programming languages using swagger-codegen.

A hosted, online instance of Swagger Editor can be found at http://editor.swagger.io.

A list of OpenAPI tools can be found here https://openapi.tools/

7. States and Values

7.1. Order states

Order resources have a property termed status which is an enum, with a number of predefined values tied to business logic.

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

7.2. Order line states

Order line resources have a property termed status which is an enum, with a number of predefined values tied to business logic.

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

7.3. 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
`CatalogueItem.serviceType`	http://ehealth.sundhed.dk/vs/device-service-types	See implementation guide for values: https://docs.ehealth.sundhed.dk/latest/ig/CodeSystem-ehealth-device-service-types.html
`Annotation.value`	http://ehealth.sundhed.dk/vs/ssl-catalogue-item-annotations	See implementation guide for values: https://docs.ehealth.sundhed.dk/latest/ig/ValueSet-ehealth-ssl-catalogue-item-annotations.html

CatalogueItem.serviceType

http://ehealth.sundhed.dk/vs/device-service-types

See implementation guide for values:
https://docs.ehealth.sundhed.dk/latest/ig/CodeSystem-ehealth-device-service-types.html

Annotation.value

http://ehealth.sundhed.dk/vs/ssl-catalogue-item-annotations

See implementation guide for values: https://docs.ehealth.sundhed.dk/latest/ig/ValueSet-ehealth-ssl-catalogue-item-annotations.html

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

7.4. Service types

Service types have a name and a value. the legal values are given in https://docs.ehealth.sundhed.dk/latest/ig/CodeSystem-ehealth-device-service-types.html and also show here:

Code system : http://ehealth.sundhed.dk/cs/device-service-types

Values:

TRAINING
RE-TRAINING
CALIBRATION
REPAIR
MAINTENANCE
REPLACE (not used at the moment)
PICKUP
DELIVER
INSTALL

7.5. Annotations

Annotation have a name and a value.

The value is a Coding from a value-set, as is therefore expressed with "system" (like a namespace) and a code (like a value).

Clients which create Annotations can freely choose Annotation names, expect that the following names are reserved and used for special purposes:

http://ehealth.sundhed.dk/vs/device-calibration-actor
http://ehealth.sundhed.dk/vs/device-measurement-unit
http://ehealth.sundhed.dk/vs/device-calibration-period
http://ehealth.sundhed.dk/vs/device-calibration-type
http://ehealth.sundhed.dk/vs/device-safety
http://ehealth.sundhed.dk/vs/device-types
http://ehealth.sundhed.dk/vs/observation-codes
http://ehealth.sundhed.dk/vs/usage-quality
http://ehealth.sundhed.dk/vs/device-measuring-quality
http://hl7.org/fhir/ValueSet/metric-category

8. Example API calls

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.

8.1. Security

The examples below do not contain security tokens. However, for the examples to work it is necessary to send a security token as an HTTP request header with each request.

The security tokens have the form of JWT tokens. In the eHealth DevTest environment the authenticity of the token is not validated, and therefore unsigned JWT tokens can be used. In other eHealth environments the JWT tokens are verified and therefore need to contain a signature from a trusted token issuer.

An example HTTP request header containing an unsigned encoded JWT token looks like this:

authorization: "Bearer eyJhbGciOiJub25lIn0.eyJ1c2VyX2lkIjoiMGY3N2M5NmMtN2YzMC00Zjk3LTlhM2EtY2JjODgwNzAzMTJmIiwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIlNTTENhdGFsb2d1ZS53cml0ZSIsIlNTTENhdGFsb2d1ZUl0ZW0ucmVhZCIsIlNTTFdoaXRlTGlzdC5yZWFkIiwiU1NMQmxhY2tMaXN0LnJlYWQiLCJTU0xXaGl0ZUxpc3Qud3JpdGUiLCJTU0xBbm5vdGF0aW9uLnJlYWQiLCJTU0xBbm5vdGF0aW9uLndyaXRlIiwiU1NMQ2F0YWxvZ3VlSXRlbS53cml0ZSIsIlNTTEJsYWNrTGlzdC53cml0ZSIsIlNTTENhdGFsb2d1ZS5yZWFkIl19LCJ1c2VyX3R5cGUiOiJTWVNURU0ifQ.

The payload of the JWT token can be inspected by visiting http://jwt.io and pasting the encoded token:

8.2. Calls to SSL Catalogue Service

8.2.1. Create a catalogue

POST /v1/catalogue
Content-Type:"application/json"

{
  "id": null,
  "identifiers": [
    {
      "system": "http://ehealth.sundhed.dk/ssl/catalogue/catalogue-identifier",
      "value": "some-catalogue-id-from-seller"
    }
  ],
  "seller": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/0c55f48b-f276-488a-8517-cd91bc174f0c",
  "name": "A catalogue name",
  "status": "ACTIVE"
}

-->

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

Note	It is mandatory to include an identifier where system is "http://ehealth.sundhed.dk/ssl/catalogue/catalogue-identifier" and the value is an id defined by the seller.

8.2.2. Update a catalogue name

PUT /v1/catalogue
Content-Type:"application/json"

{
  "id": "d47c3104-e656-46a3-b740-daf8bb0288f0",
  "identifiers": [
    {
      "system": "http://ehealth.sundhed.dk/ssl/catalogue/catalogue-identifier",
      "value": "some-catalogue-id-from-seller"
    }
  ],
  "seller": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/0c55f48b-f276-488a-8517-cd91bc174f0c",
  "name": "NEW NAME",
  "status": "ACTIVE"
}

-->

HTTP/1.1 204 No content

8.2.3. Create a catalogue item

POST /v1/catalogue-item
Content-Type:"application/json"

{
  "catalogueItemType": "DeviceModel",
  "identifiers": [
    {
      "system": "http://ehealth.sundhed.dk/ssl/catalogue/catalogue-item-identifier",
      "value": "some-item-id-from-seller",
    }
  ],
  "catalogue": "https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/catalogue/d47c3104-e656-46a3-b740-daf8bb0288f0",
  "name": "Spirometer",
  "description": "The optimal spirometer",
  "manufacturer": "Spyrometer",
  "model": "Spiro IV",
  "status": "AVAILABLE"
}

-->

HTTP/1.1 201 Created
Location: https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/catalogue-item/e82d2460-cf4d-464f-96c1-8ac391561dab

Note	It is mandatory to include an identifier where system is "http://ehealth.sundhed.dk/ssl/catalogue/catalogue-item-identifier" and the value is an id defined by the seller, e.g. part/item number.

8.2.4. Create multiple catalogue items

POST /v1/catalogue-items
Content-Type:"application/json"

[
  {
    "catalogueItemType": "DeviceModel",
    "identifiers": [
      {
        "system": "http://ehealth.sundhed.dk/ssl/catalogue/catalogue-item-identifier",
        "value": "some-item-id-from-seller"
      }
    ],
    "catalogue": "https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/catalogue/827efd91-1d9f-4194-b2f4-cf202762e26b",
    "name": "Device model name",
    "description": "The optimal spirometer",
    "status": "AVAILABLE",
    "manufacturer": "Spyrometer",
    "model": "Spiro IV",
    "version": "1.0"
  },
  {
    "catalogueItemType": "Service",
    "identifiers": [
      {
        "system": "http://ehealth.sundhed.dk/ssl/catalogue/catalogue-item-identifier",
        "value": "another-item-id-from-seller"
      }
    ],
    "relatedTo": null,
    "catalogue": "https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/catalogue/827efd91-1d9f-4194-b2f4-cf202762e26b",
    "name": "Service name",
    "description": "Training in the use of a spirometer",
    "status": "AVAILABLE",
    "serviceType": {
      "system": "http://ehealth.sundhed.dk/ssl/test/service-type",
      "code": "fast"
    }
  }
]

-->

HTTP/1.1 201 Created
<Array of created catalogue-items>

8.2.5. Create a white list item

POST /v1/white-list
Content-Type:"application/json"

{
  "buyer": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/bae9b324-34e1-4b31-b4e2-6cf8f0a3f102",
  "item": "https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/catalogue-item/bebe7ee6-36f1-4169-a8d8-826e2b139928"
}

-->

HTTP/1.1 201 Created
Location: https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/white-list/7e2b970b-aa0b-47da-a84e-03c7a7715964

8.2.6. Create a blacklist item

POST /v1/black-list
Content-Type:"application/json"

{
  "patient": "https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/Patient/868898027",
  "item": "https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/catalogue-item/732827d7-c866-4893-b292-5d52b149f6ba"
}

-->

HTTP/1.1 201 Created
Location: https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/black-list/694e363e-88c3-458a-95b1-d3bf4978de81

8.2.7. Create a package

POST /v1/package
Content-Type: "application/json"

{
  "name": "Set of COPD monitoring equipment",
  "status": "DRAFT",
  "buyerRef": "https://ssl-order.ehealth.sundhed.dk/v1/party/313",
  "packageWhiteListRefs": [
    {
      "whiteListRef": "https://ssl-catalogue.ehealth.sundhed.dk/v1/white-list/94a67a8d-447e-4f11-a002-81779e326450",
      "defaultIncluded": true
    }
  ]
}

-->

HTTP/1.1 201 Created
Location: https://ssl-catalogue.ehealth.sundhed.dk/v1/package/694e363e-88c3-458a-95b1-d3bf4978de81

8.2.8. Search for catalogue items with certain annotations

Search all catalogues available to buyer "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/9e9259c5-34c8-4389-b99f-5badcfafd275" for items annotated with "manual calibration" (eHealth/device-calibration-type:http://ehealth.sundhed.dk/vs/device-calibration-type|manual) and button size "large" (eHealth/device-button-size:http://ehealth.sundhed.dk/vs/device-button-size%7Clarge):

GET /v1/catalogue-items?buyer=https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/9e9259c5-34c8-4389-b99f-5badcfafd275&patient=https://patient.inttest.ehealth.sundhed.dk/fhir/Patient/6334767&annotation=eHealth%2Fdevice-calibration-type%3Ahttp%3A%2F%2Fehealth.sundhed.dk%2Fvs%2Fdevice-calibration-type%7Cmanual&annotation=eHealth%2Fdevice-button-size%3Ahttp%3A%2F%2Fehealth.sundhed.dk%2Fvs%2Fdevice-button-size%257Clarge

-->

HTTP/1.1 200 OK

[
  {
    "catalogueItemType": "DeviceModel",
    "id": "072f7750-246a-4987-9a39-a22a189bddaa",
    "catalogueItemType": "DeviceModel",
    "identifiers": [
      {
        "system": "http://ehealth.sundhed.dk/ssl/catalogue/catalogue-item-identifier",
        "value": "some-item-id-from-seller"
      }
    ],
    "catalogue": "https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/catalogue/5f793df7-3f75-4244-bf46-5f9e7103cc46",
    "name": "List operation catalogue item name",
    "description": "The optimal spirometer",
    "status": "AVAILABLE",
    "manufacturer": "List operation manufactured",
    "model": "List operation Spiro IV",
    "version": "3.0"
  }
]

8.2.9. Search for catalogue items from package for patient

Search all catalogue items available for patient "https://patient.inttest.ehealth.sundhed.dk/fhir/Patient/6334767" from package "https://ssl-order.inttest.ehealth.sundhed.dk/v1/package/1f1ceae2-a17c-4587-b828-32ea2158561a" to buyer "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/9e9259c5-34c8-4389-b99f-5badcfafd275"

GET /v1/catalogue-items?buyer=https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/9e9259c5-34c8-4389-b99f-5badcfafd275&patient=https://patient.inttest.ehealth.sundhed.dk/fhir/Patient/6334767&package=https://ssl-order.inttest.ehealth.sundhed.dk/v1/package/1f1ceae2-a17c-4587-b828-32ea2158561a

-->

HTTP/1.1 200 OK

[
  {
    "catalogueItemType": "DeviceModel",
    "id": "072f7750-246a-4987-9a39-a22a189bddaa",
    "catalogueItemType": "DeviceModel",
    "identifiers": [
      {
        "system": "http://ehealth.sundhed.dk/ssl/catalogue/catalogue-item-identifier",
        "value": "some-item-id-from-seller"
      }
    ],
    "catalogue": "https://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/catalogue/5f793df7-3f75-4244-bf46-5f9e7103cc46",
    "name": "List operation catalogue item name",
    "description": "The optimal spirometer",
    "status": "AVAILABLE",
    "manufacturer": "List operation manufactured",
    "model": "List operation Spiro IV",
    "version": "3.0"
  }
]

8.2.10. Search for active packages

Search for all active packages available to the buyer organization.

GET /v1/packages?status=ACTIVE

-->

HTTP/1.1 200 OK

[
  {
    "id": "94a67a8d-447e-4f11-a002-81779e326450",
    "name": "Set of COPD monitoring equipment",
    "status": "ACTIVE",
    "buyerRef": "https://ssl-order.ehealth.sundhed.dk/v1/party/313",
    "packageWhiteListRefs": [
      {
        "whiteListRef": "https://ssl-catalogue.ehealth.sundhed.dk/v1/white-list/94a67a8d-447e-4f11-a002-81779e326450",
        "defaultIncluded": true
      }
    ]
  }
]

8.3. Calls to SSL Order Service

8.3.1. Create a party

POST /v1/party/
Content-Type:"application/json"

{
  "allowedRoles": [
    "SELLER"
  ],
  "name": "2e058d91-9519-4a50-a2bd-ac8dfdf99a16",
  "email": "test@test.dk",
  "organization": "https://organization.ehealth.sundhed.dk/fhir/Organization/550035708"
}

-->

HTTP/1.1 201 Created
Location: https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/bfafb0b2-1a02-43da-a448-1dbd74b47ea4

8.3.2. Create a contract

POST /v1/contract/
Content-Type:"application/json"

{
  "name": "A contract",
  "validityPeriod": {
    "start": "2019-10-21",
    "end": "2022-10-20"
  },
  "seller": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/68532e09-e63a-49c7-bfe0-186b25673347",
  "account": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/ecf7380b-f9db-4083-b39c-e7ed9f338028",
  "buyer": [
    "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/75076192-c3cb-46a0-82ee-3a9bdb15869c"
  ],
  "reminderDays": 5
}

-->

HTTP/1.1 201 Created
Location: https://ssl-order.inttest.ehealth.sundhed.dk/v1/contract/5c97ca56-c907-402f-9bef-4532678b370e

8.3.3. Create an order

An order is created through an 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 /v1/order
Content-Type:"application/json"

{
  "status": "DRAFT",
  "priority": true,
  "buyer": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/152beb87-98d0-4306-9bc9-6c025a6ea443",
  "seller": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/fdeb0bd0-467f-4ade-b0ac-12eb624e5e43",
  "receiver": {
    "name": "name",
    "addressLine1": "addressLine1",
    "addressLine2": "addressLine2",
    "postalCode": "postalCode",
    "postalDistrict": "postalDistrict",
    "email": "test@patient.dk",
    "phone": "phone",
    "patient": "https://patient.inttest.ehealth.sundhed.dk/fhir/Patient/1566241"
  }
}

-->

HTTP/1.1 201 Created
Location: https://ssl-order.inttest.ehealth.sundhed.dk/v1/order/a3d0932f-27d2-45a0-ba69-da53e711695b

8.3.4. Add an order line

POST /v1/order-line
Content-Type:"application/json"

{
  "order": "https://ehealth.sundhed.dk/ssl-order/v1/order/2d013eda-a8ef-49d7-b561-93efd6b14e54",
  "status": "UNFULFILLED",
  "item": "https://ehealth.sundhed.dk/ssl-catalogue/v1/catalogue-item/a84de3e3-c620-4e54-a0a7-55209e2ee880",
  "agreedFrom": "2021-02-12T09:25:41.500605Z",
  "agreedTo": "2021-02-12T09:25:41.500605Z",
  "device": {
        "externalId": null,
        "identifiers": [],
        "clinicalRef": null
  }
}

-->

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

8.3.5. 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 /v1/order/2d013eda-a8ef-49d7-b561-93efd6b14e54
Content-Type:"application/json"

{
    { "op": "replace", "path": "/status/code", "value": "SUBMITTED" }
}

-->

HTTP/1.1 204 No Content

8.3.6. Get all details of an order incl trace

GET /v1/order/52741f36-6739-4a97-b60e-49e1b9f59805/details
Accept:"application/json"

-->

{
  "order": {
    "id": "52741f36-6739-4a97-b60e-49e1b9f59805",
    "identifiers": [
       ... identifiers ...
    ],
    "status": "SUBMITTED",
    "priority": false,
    "notes": [
      ... notes ...
    ],
    "buyer": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/fe515b17-7b2e-4afc-b54e-5772daa9584e",
    "seller": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/party/90afcb3a-f741-40d5-abd3-723d6cf8f16f",
    "receiver": {
      "name": "name",
      "addressLine1": "addressLine1",
      "addressLine2": "addressLine2",
      "postalCode": "postalCode",
      "postalDistrict": "postalDistrict",
      "email": "test@ukr.net",
      "phone": "phone",
      "patient": "https://patient.inttest.ehealth.sundhed.dk/fhir/Patient/1566241"
    }
  },
  "orderLines": [
    ... order lines ...
  ],
  "traceLines": [
    {
      "id": "f78283a3-b288-40d4-99c4-94c2fbf8e45b",
      "timestamp": "2019-10-21T12:01:10.757186Z",
      "createdByOrganization": "ORGANIZATION_NAME",
      "text": "Order line updated status changed device has been added",
      "supplementaryText": "Order line updated status changed UNFULFILLED -> SUBMITTED device has been added Device/21108",
      "order": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/order/52741f36-6739-4a97-b60e-49e1b9f59805",
      "orderLine": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/order-line/2bf3928e-7bf2-4d0c-9574-a1d295968675",
      "statusChange": {
        "oldStatus": "UNFULFILLED",
        "newStatus": "SUBMITTED"
      }
    },
    {
      "id": "00f499f1-a3b7-4e51-ad38-029d16940d55",
      "timestamp": "2019-10-21T12:01:10.804744Z",
      "createdByOrganization": "ORGANIZATION_NAME",
      "text": "Order updated: priority changed",
      "supplementaryText": "Order updated: priority changed true -> false",
      "order": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/order/52741f36-6739-4a97-b60e-49e1b9f59805",
      "orderLine": null,
      "statusChange": null
    },
    {
      "id": "ece7f284-3cda-40d5-9f83-01546253ab50",
      "timestamp": "2019-10-21T12:01:10.964992Z",
      "createdByOrganization": "ORGANIZATION_NAME",
      "text": "Order updated: status changed",
      "supplementaryText": "Order updated: status changed DRAFT -> SUBMITTED",
      "order": "https://ssl-order.inttest.ehealth.sundhed.dk/v1/order/52741f36-6739-4a97-b60e-49e1b9f59805",
      "orderLine": null,
      "statusChange": {
        "oldStatus": "DRAFT",
        "newStatus": "SUBMITTED"
      }
    }
  ]
}

9. Bibliography

[HL7FHIR] "Welcome to FHIR", http://hl7.org/fhir/
[HL7COD] "HL7 Data Types", https://www.hl7.org/fhir/datatypes.html#Coding
[OAS3] "OpenAPI Specification (fka Swagger RESTful API Documentation Specification), Version 3.0", https://swagger.io/specification/v3/.
[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/.
[SSL-ACCESS-CONTROL] "SSL Roles, RBAC and ABAC", https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/291176482/Tokens+Roles+and+RBAC+ABAC#SSL

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