Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 23 Current »

Audience: This page is intended for developers and architects that are to interface with the Care Gateway

Introduction

The Care Gateway (henceforth gateway) is a service that receives FHIR reports/bundles (eg. care delivery reports or children delivery reports) from the municipalities and asynchronously forwards them other data sources such as FLIS, SEI2, RKKP etc. The reports must follow the FHIR format specified in one of the allowed FHIR implementation guides:

Any report received by the gateway is validated against the profiles and terminology resources specified in the relevant IG. Failing to comply with these resources will result in an 4XX error.

Security

In order for a client to send reports to the gateway the client needs to obtain a valid access token. For authentication and obtaining an access token (through a KeyCloak instance) see SAML Assertion to JWT Exchange.

Note: A public key must have been forwarded ahead of time and out-of-band of the authentication flow to be successful.

Interface

As can be seen in the OpenAPI below, the reporting systems interacts with the gateway by PUT’ing reports to it on https://<server>:<port>/fhir/Bundle. By default, FHIR servers support all CRUD operations, but HTTP PUT has been selected as the only choice for KLG, because it effectively allows clients to control the id of the resource, hence putting the client in control (aka. upsert). Notice that the Bundle id chosen by the client must be globally unique, and that the id of the Bundle payload must equal the id in the URL (/fhir/Bundle/{id}). Within a Bundle (bundle entry-list), ids must only be unique within the bundle, and may be reused to indicate resource updates - this is specified by the individual implementation guides, see eg. section 2.1 (Reporting) of https://kl-dk.github.io/website/gateway/index.html.

It has been agreed that two subsequent PUTs will not update the existing bundle - instead, a DUPLICATE_ENTITY error will be returned (see section “Error messages” below).

As stated, the content must follow the FHIR structure of an allowed IG.

Business Flow

The temporal aspects of the business processes are depicted below.


Technical Flow

The technical interaction between the different parties is as depicted below. Actions within the green box are of high relevance to the audience of this page. The interaction between the gateway (white box) and 3.party systems (blue box) is shown for sake of completeness.

Error messages

The Care Gateway may return error messages in case of invalid input, technical errors etc. according to standard HAPI FHIR behaviour. All errors are reported using the OperationOutcome profile, which is described her:

https://www.hl7.org/fhir/operationoutcome.html

Apart from standard HAPI FHIR errors, the gateway may return this custom error in case a bundle with the specified bundle ID has already been created:

DUPLICATE_ENTITY: Entity with id '%s' already exists:

Example:

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "DUPLICATE_ENTITY: Entity with id 'Bundle/0c1112c3-77b5-4d85-965c-0c26228ec7e3' already exists"
        }
    ]
}

Below is also an example of a validation error (in case the input does not conform to the implementation guide):

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "Unable to find a match for profile Condition/ad506910-9030-4ddb-b8ce-7bb6a69d808e among choices: http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-condition, http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-planned-intervention",
            "location": [
                "Bundle.entry[5].resource.ofType(Observation).focus[0]",
                "Line 238, Col 12"
            ]
        },
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "Encounter.period: minimum required = 1, but only found 0 (from http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-encounter)",
            "location": [
                "Bundle.entry[6].resource.ofType(Encounter)",
                "Line 282, Col 22"
            ]
        }
    ]
}

Issues

If you encounter a bug or an issue with the gateway or the security component/flow please report it as an issue on https://github.com/trifork/klg-docs.

Test environment

Details on the gateway test environment can be found on KL Gateway Environment: TEST001

Examples

Snippet below shows an example CareDeliveryReport request without security headers

PUT http://localhost:8080/fhir/Bundle/0c1112c3-77b5-4d85-965c-0c26228ec7ef
Content-Type: application/json

{
  "resourceType" : "Bundle",
  "id" : "0c1112c3-77b5-4d85-965c-0c26228ec7ef",
  "meta" : {
    "profile" : [
      "http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-delivery-report"
    ]
  },
  "type" : "collection",
  "timestamp" : "2021-02-14T15:23:12Z",
  "entry" : [
    {
      "fullUrl" : "Patient/4a45e179-ace1-4ace-9991-8276c0ba490a",
      "resource" : {
        "resourceType" : "Patient",
        "id" : "4a45e179-ace1-4ace-9991-8276c0ba490a",
        "meta" : {
          "profile" : [
            "http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-citizen"
          ]
        },
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><p><b>identifier</b>: id: 0101570001 (OFFICIAL)</p><p><b>managingOrganization</b>: <span></span></p></div>"
        },
        "identifier" : [
          {
            "use" : "official",
            "system" : "urn:oid:1.2.208.176.1.2",
            "value" : "0101570001"
          }
        ],
        "managingOrganization" : {
          "identifier" : {
            "use" : "official",
            "system" : "urn:oid:1.2.208.176.1.1",
            "value" : "123456789012345"
          }
        }
      }
    },
    {
      "fullUrl" : "Condition/a881788d-1b27-46e3-8b76-607bc49876fd",
      "resource" : {
        "resourceType" : "Condition",
        "id" : "a881788d-1b27-46e3-8b76-607bc49876fd",
        "meta" : {
          "profile" : [
            "http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-condition"
          ]
        },
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><p><b>clinicalStatus</b>: <span title=\"Codes: {http://terminology.hl7.org/CodeSystem/condition-clinical inactive}\">Inactive</span></p><p><b>code</b>: <span title=\"Codes: {http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII I7.1}\">Respirationsproblemer</span></p><p><b>subject</b>: <a href=\"#Patient_4a45e179-ace1-4ace-9991-8276c0ba490a\">See above (Patient/4a45e179-ace1-4ace-9991-8276c0ba490a)</a></p><p><b>recordedDate</b>: 2021-02-10</p></div>"
        },
        "clinicalStatus" : {
          "coding" : [
            {
              "system" : "http://terminology.hl7.org/CodeSystem/condition-clinical",
              "code" : "inactive"
            }
          ]
        },
        "code" : {
          "coding" : [
            {
              "system" : "http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII",
              "code" : "I7.1"
            }
          ]
        },
        "subject" : {
          "reference" : "Patient/4a45e179-ace1-4ace-9991-8276c0ba490a"
        },
        "recordedDate" : "2021-02-10"
      }
    },
    {
      "fullUrl" : "Condition/ad506910-9030-4ddb-b8ce-7bb6a69d808e",
      "resource" : {
        "resourceType" : "Condition",
        "id" : "ad506910-9030-4ddb-b8ce-7bb6a69d808e",
        "meta" : {
          "profile" : [
            "http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-condition"
          ]
        },
        "text" : {
          "status" : "extensions",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><p><b>CareFollowUpEncounterExtension</b>: <a href=\"#Encounter_1fb0990d-aac7-4661-b976-874e051c5ae6\">See above (Encounter/1fb0990d-aac7-4661-b976-874e051c5ae6)</a></p><p><b>clinicalStatus</b>: <span title=\"Codes: {http://terminology.hl7.org/CodeSystem/condition-clinical active}\">Active</span></p><p><b>category</b>: <span title=\"Codes: {http://terminology.hl7.org/CodeSystem/condition-category problem-list-item}\">Problem List Item</span></p><p><b>code</b>: <span title=\"Codes: {http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII I2.1}\">Problemer med mobilitet og bevægelse</span></p><p><b>subject</b>: <a href=\"#Patient_4a45e179-ace1-4ace-9991-8276c0ba490a\">See above (Patient/4a45e179-ace1-4ace-9991-8276c0ba490a)</a></p><p><b>recordedDate</b>: 2021-02-10</p></div>"
        },
        "extension" : [
          {
            "url" : "http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-follow-up-encounter-extension",
            "valueReference" : {
              "reference" : "Encounter/1fb0990d-aac7-4661-b976-874e051c5ae6"
            }
          }
        ],
        "clinicalStatus" : {
          "coding" : [
            {
              "system" : "http://terminology.hl7.org/CodeSystem/condition-clinical",
              "code" : "active"
            }
          ]
        },
        "category" : [
          {
            "coding" : [
              {
                "system" : "http://terminology.hl7.org/CodeSystem/condition-category",
                "code" : "problem-list-item"
              }
            ]
          }
        ],
        "code" : {
          "coding" : [
            {
              "system" : "http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII",
              "code" : "I2.1"
            }
          ]
        },
        "subject" : {
          "reference" : "Patient/4a45e179-ace1-4ace-9991-8276c0ba490a"
        },
        "recordedDate" : "2021-02-10"
      }
    },
    {
      "fullUrl" : "Observation/c9c93481-f170-4653-b837-6e8eacd716ca",
      "resource" : {
        "resourceType" : "Observation",
        "id" : "c9c93481-f170-4653-b837-6e8eacd716ca",
        "meta" : {
          "profile" : [
            "http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-matter-of-interest-observation"
          ]
        },
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><p></p><p><b>code</b>: <span title=\"Codes: {http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII I7}\">Respiration og cirkulation</span></p><p><b>subject</b>: <a href=\"#Patient_4a45e179-ace1-4ace-9991-8276c0ba490a\">See above (Patient/4a45e179-ace1-4ace-9991-8276c0ba490a)</a></p><p><b>effective</b>: 2021-02-15</p><p><b>value</b>: <span title=\"Codes: {http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII B6}\">Ikke relevant</span></p></div>"
        },
        "status" : "final",
        "code" : {
          "coding" : [
            {
              "system" : "http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII",
              "code" : "I7"
            }
          ]
        },
        "subject" : {
          "reference" : "Patient/4a45e179-ace1-4ace-9991-8276c0ba490a"
        },
        "effectiveDateTime" : "2021-02-15",
        "valueCodeableConcept" : {
          "coding" : [
            {
              "system" : "http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII",
              "code" : "B6"
            }
          ]
        }
      }
    },
    {
      "fullUrl" : "Observation/c0e46d1a-bcd2-4b4f-bc74-db1237157d4e",
      "resource" : {
        "resourceType" : "Observation",
        "id" : "c0e46d1a-bcd2-4b4f-bc74-db1237157d4e",
        "meta" : {
          "profile" : [
            "http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-follow-up-observation"
          ]
        },
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><p></p><p><b>code</b>: <span title=\"Codes: {http://snomed.info/sct 712744002}\">Evaluation of care plan (procedure)</span></p><p><b>subject</b>: <a href=\"#Patient_4a45e179-ace1-4ace-9991-8276c0ba490a\">See above (Patient/4a45e179-ace1-4ace-9991-8276c0ba490a)</a></p><p><b>focus</b>: <a href=\"#Condition_a881788d-1b27-46e3-8b76-607bc49876fd\">See above (Condition/a881788d-1b27-46e3-8b76-607bc49876fd)</a></p><p><b>effective</b>: 2021-02-12</p><p><b>value</b>: <span title=\"Codes: {http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII E3}\">Afsluttes</span></p></div>"
        },
        "status" : "final",
        "code" : {
          "coding" : [
            {
              "system" : "http://snomed.info/sct",
              "code" : "712744002"
            }
          ]
        },
        "subject" : {
          "reference" : "Patient/4a45e179-ace1-4ace-9991-8276c0ba490a"
        },
        "focus" : [
          {
            "reference" : "Condition/a881788d-1b27-46e3-8b76-607bc49876fd"
          }
        ],
        "effectiveDateTime" : "2021-02-12",
        "valueCodeableConcept" : {
          "coding" : [
            {
              "system" : "http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII",
              "code" : "E3"
            }
          ]
        }
      }
    },
    {
      "fullUrl" : "Observation/4c160af3-dc6f-4405-a52a-b93447e06b68",
      "resource" : {
        "resourceType" : "Observation",
        "id" : "4c160af3-dc6f-4405-a52a-b93447e06b68",
        "meta" : {
          "profile" : [
            "http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-follow-up-observation"
          ]
        },
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><p></p><p><b>code</b>: <span title=\"Codes: {http://snomed.info/sct 712744002}\">Evaluation of care plan (procedure)</span></p><p><b>subject</b>: <a href=\"#Patient_4a45e179-ace1-4ace-9991-8276c0ba490a\">See above (Patient/4a45e179-ace1-4ace-9991-8276c0ba490a)</a></p><p><b>focus</b>: <a href=\"#Condition_ad506910-9030-4ddb-b8ce-7bb6a69d808e\">See above (Condition/ad506910-9030-4ddb-b8ce-7bb6a69d808e)</a></p><p><b>effective</b>: 2021-02-14</p><p><b>value</b>: <span title=\"Codes: {http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII E2}\">Ændres inden for rammen</span></p></div>"
        },
        "status" : "final",
        "code" : {
          "coding" : [
            {
              "system" : "http://snomed.info/sct",
              "code" : "712744002"
            }
          ]
        },
        "subject" : {
          "reference" : "Patient/4a45e179-ace1-4ace-9991-8276c0ba490a"
        },
        "focus" : [
          {
            "reference" : "Condition/ad506910-9030-4ddb-b8ce-7bb6a69d808e"
          }
        ],
        "effectiveDateTime" : "2021-02-14",
        "valueCodeableConcept" : {
          "coding" : [
            {
              "system" : "http://kl.dk/fhir/common/caresocial/CodeSystem/FSIII",
              "code" : "E2"
            }
          ]
        }
      }
    },
    {
      "fullUrl" : "Encounter/1fb0990d-aac7-4661-b976-874e051c5ae6",
      "resource" : {
        "resourceType" : "Encounter",
        "id" : "1fb0990d-aac7-4661-b976-874e051c5ae6",
        "meta" : {
          "profile" : [
            "http://gateway.kl.dk/1.0/StructureDefinition/klgateway-care-encounter"
          ]
        },
        "text" : {
          "status" : "generated",
          "div" : "<div xmlns=\"http://www.w3.org/1999/xhtml\"><p><b>Generated Narrative</b></p><p><b>status</b>: planned</p><p><b>class</b>: <span title=\"{http://terminology.hl7.org/CodeSystem/v3-ActCode HH}\">home health</span></p><p><b>type</b>: <span title=\"Codes: {http://kl.dk/fhir/common/caresocial/CodeSystem/KLCommonCareSocialCodes 9f03dfbb-7a97-45a5-94db-d4c3501714a9}\">opfølgning</span></p><p><b>subject</b>: <a href=\"#Patient_4a45e179-ace1-4ace-9991-8276c0ba490a\">See above (Patient/4a45e179-ace1-4ace-9991-8276c0ba490a)</a></p><p><b>period</b>: 2021-02-15 --&gt; (ongoing)</p></div>"
        },
        "status" : "planned",
        "class" : {
          "system" : "http://terminology.hl7.org/CodeSystem/v3-ActCode",
          "code" : "HH"
        },
        "type" : [
          {
            "coding" : [
              {
                "system" : "http://kl.dk/fhir/common/caresocial/CodeSystem/KLCommonCareSocialCodes",
                "code" : "9f03dfbb-7a97-45a5-94db-d4c3501714a9"
              }
            ]
          }
        ],
        "subject" : {
          "reference" : "Patient/4a45e179-ace1-4ace-9991-8276c0ba490a"
        },
        "period" : {
          "start" : "2021-02-15"
        }
      }
    }
  ]
}

  • No labels