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. Relations between resources from the SSL domain and the clinical domain

The relation between the SSL resources and the Clinical FHIR resources in a flow is like this (the creation of a careplan for the Patient takes place before these flow)

Order delivery (new Device):

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
Creates an SSL order based on one or more of the search results for the Patient, references the Patient on the order and sets a reciving address for the order
Releases the SSL order by assigning it to a SSL seller and setting the status to Submited
The SSL seller gets the order from the SSL GUI or SSL API, and sets out to fullfill the order, in that regard the SSL order is shifting state a number of times, ex. when the time of fullfillement has been agreeed (TimeOfFullfilmentAgreed)
The SSL seller employee delivers the order and sets the status of the individual SSL orderlines to Fullfilled and set the status on the entire SSL order to Fullfiled
The SSL API receives the status updates and is now in a position where FHIR resources in the clinical domain have to be created, the steps are
1. A Device resource is created with an identifier set to the external ID entered by the SSL seller employee.
2. A DeviceUseStatement resource is created with reference to the Device and the Patient, found on the SSL Order /OrderLine
3. 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

If the flow is service order, the flow is like this ex. (PICKUP)

The Patient calls in and informs that the Device is broken
The Practitioner creates an SSL order with a SSL Service item of type PICKUP, and with a reference to the FHIR Device to be picked up
The Practitioner releses the SSL order to the SSL seller
The SSL seller gets the order from the SSL GUI or SSL API, and sets out to fullfill the order, in that regard the SSL order is shiftig state a number of times, ex. when the time of fullfillement has been agreeed
The SSL seller employee delivers the order and sets the individual orderlines to fullfilled and fullfills the entire order
The SSL API receives the status updates and is now in a position where the exixting FHIR resource DeviceUseStatement can be updated
1. it is retrived 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)

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 a orderline of type service (PICKUP) and another orderline with a new Device (the replacement).

3.5. 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
CatalogueItem	An object with the common attributes from Service and DeviceModel	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.
Package	A package is a collection of white lists available to a buying organization. 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.

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

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

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

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

3.7.1. Servicetype

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

3.7.2. Annotations

Annotation have a name and a value.

The value is a Coding from a valueset, 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

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://ssl-catalogue.inttest.ehealth.sundhed.dk/v1/catalogue

4.5. Base URLs

The base url of SSL BFF’s 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 in inttest environment is:

https://ssl-catalogue.inttest.ehealth.sundhed.dk/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": "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"
   ...
}

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%2Fssl-order.inttest.ehealth.sundhed.dk%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. Security

The examples below do not contain security tokens. However for the examples to work it is necessary to send a security token as a 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:

6.2. Catalogues

6.2.1. Create a catalogue

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

{
  "id": null,
  "identifiers": [
    {
      "system": "http://ehealth.sundhed.dk/ssl/test/system1/",
      "value": "117718e3-0153-4c1d-989f-a257dfb8aaf6"
    }
  ],
  "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

6.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/test/system1/",
      "value": "117718e3-0153-4c1d-989f-a257dfb8aaf6"
    }
  ],
  "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

6.2.3. Create a catalogue item

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

{
  "catalogueItemType": "DeviceModel",
  "identifiers": [
    {
      "system": "SellersId",
      "value": "seller_1234",
    }
  ],
  "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

6.2.4. Create multiple catalogue items

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

[
  {
    "catalogueItemType": "DeviceModel",
    "identifiers": [
      {
        "system": "SellersId",
        "value": "seller_1234"
      }
    ],
    "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": "SellersId",
        "value": "seller_9234"
      }
    ],
    "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>

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

6.2.6. Create a black list 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

6.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",
  "whiteListRefs": [
    "https://ssl-catalogue.ehealth.sundhed.dk/v1/white-list/94a67a8d-447e-4f11-a002-81779e326450"
  ]
}

-->

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

6.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": "ade86ead-6fb7-42f6-82db-43fa32d90aa5",
        "value": "45cd5023-0c95-4014-9244-59d07b01df2e"
      }
    ],
    "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"
  }
]

6.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": "ade86ead-6fb7-42f6-82db-43fa32d90aa5",
        "value": "45cd5023-0c95-4014-9244-59d07b01df2e"
      }
    ],
    "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"
  }
]

6.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": "DRAFT",
    "buyerRef": "https://ssl-order.ehealth.sundhed.dk/v1/party/313",
    "whiteListRefs": [
      "https://ssl-catalogue.ehealth.sundhed.dk/v1/white-list/94a67a8d-447e-4f11-a002-81779e326450"
    ]
  }
]

6.3. Orders

6.3.1. Create a party

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

{
  "allowedRoles": [
    "BUYER"
  ],
  "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

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

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

6.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"
}

-->

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

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

6.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"
      }
    }
  ]
}

6.4. Other

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