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:

• CareDeliveryReports: KL-Gateway FHIR Implementation Guide (IG)

• ChildrenDeliveryReports: KL-Children FHIR Implementation Guide (IG)

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 Home - v1.2.0.

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.

Open

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.

Open

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:

OperationOutcome - FHIR v5.0.0

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:

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

Issues

If you encounter a bug or an issue with the gateway or the security component/flow please report it as an issue on GitHub - trifork/klg-docs: Public documentation for Gateway.

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