Client implementation guidelines

This Implementation guide aims to outline the requirements and interactions needed in the use case where a wellness application needs to send patient generated data from a device to KotiDigi platform.

Assumptions

  • Client only interacts with a single URI using a Direct FHIR RESTful Write
  • Pre-Coordination with Client App is needed for acceptance of patient supplied data within the approved context of the user’s permissions

Functional Requirements

  • Client SHALL be able to create FHIR resources on a Server
  • Client SHOULD be able to fetch and query for the FHIR resources it has created via the Server’s FHIR API
  • Kotidigi platform assumes that all Resources submitted from clients have a Patient reference. At the moment Patient is referenced by finnish social security number, in the near future we plan to transfer to pseudonymized reference with a Kotidigi generated Patient identifier

Example workflow

Use Case Categories Covered by KotiDigi platform API

Some use case categories and FHIR resource types expected to be covered by this approach:

  • Vitals (e.g. : Weight, Blood Pressure) --> Observation
  • Activity (e.g. Steps,Sleep) --> Observation
  • At home diagnostics (Blood Glucose, Covid 19 Test) --> Observation
  • non-FHIR Documents (e.g. photos) --> DocumentReference
  • Assessments(e.g. patient reported Outcomes) --> QuestionnaireResponse/Observation

Example interactions

Observations can be added to Kotidigi with simple HTTP POST operations in FHIR standard Observation format, see https://www.hl7.org/fhir/observation.html for details.

Example Observations for Kotidigi releted concepts can be fould here: https://simplifier.net/kotidigi/~resources?category=Example&exampletype=Observation

Example request:

POST https://sandbox.kotidigi.fi/api/ecosystem/Observation
Content-Type: application/fhir+json; charset=UTF-8
Authorization: Basic ZXhhbXBsZTplaW5lLWdyb3NzZS1zcGVsYW5k

    "resourceType": "Observation",
    "status": "final",
    "category":  [
        {
            "coding":  [
                {
                    "system": "http://terminology.hl7.org/CodeSystem/observation-category",
                    "code": "vital-signs"
                }
            ]
        }
    ],
    "code": {
        "coding":  [
            {
                "system": "http://loinc.org",
                "code": "29463-7",
                "display": "Body weight with reference range and interpretation"
            },
            {
                "system": "http://snomed.info/sct",
                "code": "27113001",
                "display": "Body weight (observable entity)"
            }
        ]
    },
    "subject": {
        "identifier": {
            "system": "urn:oid:1.2.246.21",
            "value": "010101-123N"
        }
    },
    "effectiveDateTime": "2022-05-17T11:46:00+02:00",
    "device": {
        "extension":  [
            {
                "url": "DeviceVersion",
                "valueString": "Withings"
            },
            {
                "url": "lastSyncTime",
                "valueDateTime": "2022-04-01"
            }
        ]
    },
    "valueQuantity": {
        "value": 95,
        "unit": "kg",
        "system": "http://unitsofmeasure.org",
        "code": "kg"
    },
    "interpretation":  [
        {
            "coding":  [
                {
                    "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
                    "code": "N",
                    "display": "Normal"
                }
            ]
        }
    ],
    "referenceRange":  [
        {
            "low": {
                "value": 55,
                "unit": "kg",
                "system": "http://unitsofmeasure.org",
                "code": "kg"
            },
            "high": {
                "value": 150,
                "unit": "kg",
                "system": "http://unitsofmeasure.org",
                "code": "kg"
            },
            "appliesTo":  [
                {
                    "coding":  [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "248153007",
                            "display": "Male"
                        }
                    ],
                    "text": "Normal range"
                }
            ],
            "age": {
                "low": {
                    "value": 15,
                    "unit": "years",
                    "system": "http://unitsofmeasure.org",
                    "code": "a"
                },
                "high": {
                    "value": 100,
                    "unit": "years",
                    "system": "http://unitsofmeasure.org",
                    "code": "a"
                }
            },
            "text": "Age"
        }
    ]
}