Versions Compared

Old Version 13

changes.mady.by.user Erik Nielsen

Saved on

compared with

New Version 14

changes.mady.by.user John Schneider

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents

General Aspects of Interacting with Services

Caching on Searching

Client-side caching is, as caching in general, a mechanism for achieving better performance although it must be applied with caution, especially when used with clinical content.

Note

Use of events for cache invalidation, as described in Caching Client-side caching , might not be immediately available to a client. As described in Caching Client-side caching, caching of information from services in the Clinical Domain is not recommended, with the Patient service being an exception.

...

In the following, focus is on server-side caching applied upon search operations and how a client can influence it.

eHealth Infrastructure Services with Server-side Caching on Searching

It can generally be assumed that the caching is based on the principles described in HAPI FHIR Search Result Caching. When interacting with custom operations, caching is specific to the operation itself.

Patient Service

  • Search results will be reused for 1 minute

    • This cache is used when identical searches are performed (same search parameters)

    • This means search results can be up to 1 minute stale!

  • Search results for a particular bundle ID is cached in the database for 1 hour

    • This cache is used when paging through the result bundle of a particular search

  • Max value for max-results header is 1000

    • Cache-Control: nostore, max-results=1000

  • Default page size is 20

  • Maximum page size is 200

    • Clients can request a particular page size by setting the _count parameter

  • Person$match does not employ any caching

    • internally, it first searches for a Patient with the provided CRN in the local database (does not use the search result cache, for technical reasons)

      • If a patient exists, the information from that patient is returned

      • If a patient does not exist, a request is sent to the CPR registry to lookup the information

        • The result of this request is not cached or persisted

Info

Infrastructure note: Sticky sessions are not required as the cache is stored in the database.

Disabling Server-side Caching on Searching

If your use case requires that search results are not cached you have the opportunity to opt out of this using http-headers on your client request:

...

In a HAPI FHIR-based client, opt-out can be achieved like this:

...

Filtering on Searching with Included Resources

Info

This functionality is available from eHealth Infrastructure Release 6.1 when including referenced ClinicalImpression in a Task search. It may later be extended to other resource types.

...

  • OperationOutcome.issue.severity: warning

  • OperationOutcome.issue.code: suppressed

  • OperationOutcome.issue.diagnostics: Some included resources were filtered due to access constraints for the user

Interactions with the Terminology Service

Extracting Translations from ValueSet and CodeSystem

How to determine, say, Danish translations used in ValueSet? The ValueSet as a resource is likely not to contain a proper, displayable value in Danish as the ValueSet can be defined as include of other ValueSet and/or include of entire or partial CodeSystem, and as the display values in the ValueSet are for technical help primarily. Translations, if available, reside in the CodeSystem.

To get translations for at ValueSet, use $expand as follows:

  1. Call $expand on the ValueSet

    1. GET <base-url>/fhir/ValueSet/$expand?url=<ValueSet url>&property=designation

  2. Determine best translation:

    1. Choose designation with “da” (for Danish) if available, otherwise

    2. Choose display (as best alternative - this will be in whatever language the concept is defined with)

      1. In the example below, this is the case for code assessment

Info

Example request and response on $expand on topic-type

Request:

GET <base-url>/fhir/ValueSet/$expand?url=http://ehealth.sundhed.dk/vs/topic-type

Response:

{     "resourceType": "ValueSet",     "status": "active",

…

            {                 "system": "http://hl7.org/fhir/definition-topic",                 "code": "assessment",                 "display": "Assessment"             }, …

            {                 "system": "http://ehealth.sundhed.dk/cs/topic-type",                 "code": "self-treatment",                 "display": "Self-treatment",                 "designation": [                     {                         "language": "da",                         "value": "Selvbehandling"                     }                 ]             }

…

CodeSystems and designations

For supported operations on concept lookups and decomposition, please see the supported operations on CodeSystem at http://hl7.org/fhir/STU3/codesystem-operations.html. Designations targeted consumers/citizens will eg. contain the following data in the designation:

<designation>
<language value="da"></language>
<use>
<system value="http://terminology.hl7.org/CodeSystem/hl7TermMaintInfra"</system>>
<code value="consumer"></code>
</use>
<value value="Højde"></value>
</designation>

Determining the proper code, system and unit for Quantity

Given an observation codeand corresponding system from the ValueSet ehealth-observation-codes, how does one then determine how to specify an observed quantity or reference range? The following describes how to obtain values to set inQuantity.code, .system and .unit.

To get values forQuantity.codeandQuantity.system use the ConceptMap conceptmap-obs-code-to-ucum as follows:

  1. Call $translate on the given code and system:

    1. GET <base-url>/fhir/ConceptMap/$translate?system=<system>&code=<code>

  2. On match found, the values to use in Quantity.codeandQuantity.systemare the matching concept’s code and system, respectively, where the source ConceptMap is “http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-ucum” (see example response below):

Info

Example request and response on $translate on conceptmap-obs-code-to-ucum

Request:

GET <base-url>/fhir/ConceptMap/$translate?system=urn:oid:1.2.208.176.2.1&code=NPU03804

Response:

{     "resourceType": "Parameters",     "parameter": [         {             "name": "result",             "valueBoolean": true         },         {             "name": "message",             "valueString": "Matches found!"         },         {             "name": "match",             "part": [                 {                     "name": "equivalence",                     "valueCode": "specializes"                 },                 {                     "name": "concept",                     "valueCoding": {                         "system": "http://unitsofmeasure.org",                         "code": "kg",                         "display": "kilogram"                     }                 },                 {                     "name": "source",                     "valueUri": "http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-ucum"                 }             ]         }     ] }

To get the corresponding and printable value for Quantity.unit, use the ConceptMap conceptmap-ucum-to-printsymbol as follows:

  1. Call $translate on the given system and code determined in the response above:

    1. GET <base-url>/fhir/ConceptMap/$translate?target=http://ehealth.sundhed.dk/vs/ehealth-ucum-printsymbol-supplement&code=<code>&system=<system>

  2. On match found, extract the matching concept (see example response below).

  3. Call $lookupon the matching (CodeSystem) system and code:

    1. GET <base-url>/fhir/CodeSystem/$lookup?system=http://ehealth.sundhed.dk/cs/ehealth-ucum-printsymbol-supplement&code=<code>

  4. On match found, the value to use in Quantity.unitis the matching concept’s designation.valuewhere the designation.language=da(see example response below). If there is no such designation, the printable value in Quantity.unit shall be left empty.

Note

The $lookup does not return designation on eHealth Infrastructure Release 4 and other releases prior to Release 5.

Info

Example request and response on $translate on conceptmap-ucum-to-printsymbol

Request (Note that URL-encoding of percent as code is used):

GET <base-url>/fhir/ConceptMap/$translate?target=http://ehealth.sundhed.dk/vs/ehealth-ucum-printsymbol-supplement&code=%25&system=http://unitsofmeasure.org

Response:

{     "resourceType": "Parameters",     "parameter": [         {             "name": "result",             "valueBoolean": true         },         {             "name": "message",             "valueString": "Matches found!"         },         {             "name": "match",             "part": [                 {                     "name": "equivalence",                     "valueCode": "specializes"                 },                 {                     "name": "concept",                     "valueCoding": {                         "system": "http://ehealth.sundhed.dk/cs/ehealth-ucum-printsymbol-supplement",                         "code": "%",                         "display": "percent"                     }                 },                 {                     "name": "source",                     "valueUri": "http://ehealth.sundhed.dk/ConceptMap/conceptmap-ucum-to-printsymbol"                 }             ]         }     ] }

Info

Example request and response on $lookup on ehealth-ucum-printsymbol-supplement

Request (Note that URL-encoding of percent as code is used):

GET <base-url>/fhir/CodeSystem/$lookup?system=http://ehealth.sundhed.dk/cs/ehealth-ucum-printsymbol-supplement&code=%25

Response:

{     "resourceType": "Parameters",     "parameter": [         {             "name": "name",             "valueString": "UCUMPrintSymbolSupplement"         },         {             "name": "version",             "valueString": "0.6.0"         },         {             "name": "display",             "valueString": "percent"         },         {             "name": "abstract",             "valueBoolean": false         },         {             "name": "designation",             "part": [                 {                     "name": "language",                     "valueCode": "da"                 },                 {                     "name": "use"                 },                 {                     "name": "value",                     "valueString": "%"                 }             ]         }     ] }

Determining whether to provide measurement as integer or decimal

Given an observation codeand corresponding system from the ValueSet ehealth-observation-codes, how does one determine whether an observed quantity or reference range shall be stated as an integer or decimal? While a particular device might produce a decimal with a given precision for a measure, it is up to the client/solution to convert to the form expected by the infrastructure. Whether integer or decimal, the value is set inQuantity.value.

To determine whether to use integer or decimal, use the ConceptMap conceptmap-obs-code-to-value-type as follows:

  1. Call $translate on the given code and system:

    1. GET <base-url>/fhir/ConceptMap/$translate?system=<system>&code=<code>&target=http://hl7.org/fhir/ValueSet/data-types

  2. On match found, indication of whether to use integer or decimal are the matching concept’s code and system, respectively, where the source ConceptMap is “http://ehealth.sundhed.dk/ConceptMap/conceptmap-obs-code-to-value-type” (see example response below).

  3. The codes integer and decimal in system http://hl7.org/fhir/data-types signify that the observed value or reference range shall be given as integer and decimal, respectively.

...

Example request and response on $translate on conceptmap-obs-code-to-value-type

Request:

GET <base-url>/fhir/ConceptMap/$translate?system=urn:oid:1.2.208.176.2.1&code=NPU03804&target=http://hl7.org/fhir/ValueSet/data-types

Response:

...