Some FHIR resources in the eHealth Infrastructure are transformed to document form and registered in national document sharing infrastructure. This way, the patient and other healthcare professionals can access the health data registered through other health systems while subjected to various access controls and audit logging.
The document registering process involves:
determining whether criteria for document registering are met
assembly to a volatile (in-memory) FHIR Composition (as described in https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/2242281473/Performing+Document+Query+and+Retrieve+and+Using+Transformations#Preparing-Transformations-by-Assembling-Required-FHIR-Resources )
transformation of assembled FHIR Composition to Danish profiles of Clinical Document Architecture (CDA) documents (as described in https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/2242281473/Performing+Document+Query+and+Retrieve+and+Using+Transformations#Transformation-Details ) to a document
extract of document metadata from the document and context
registering of document and document metadata in the national document sharing infrastructure.
Primary FHIR Resource Type | Assembling of Resources for Transformation | Transformation | Registered as Document Type |
---|---|---|---|
https://ehealth.sundhed.dk/fhir/OperationDefinition--s-transform-to-PHMR.html | |||
https://ehealth.sundhed.dk/fhir/OperationDefinition--s-transform-to-QRD.html | |||
https://ehealth.sundhed.dk/fhir/OperationDefinition--s-transform-to-APD.html | APD |
This description below focuses on the criteria for this registration to take place.
Content
Prerequisites for Document Registering of Observation Resources
Prerequisites for registering a document about a FHIR Observation are all of:
Prerequisite (Logically) | Criteria |
---|---|
Sharing is allowed for the activity. |
|
The particular Observation is approved for document registering. |
|
The Observation has a measurement quantity/value. Rationale: Otherwise, the Observation cannot be shared as a PHMR document. |
|
Prerequisites for Document Registering of QuestionnaireResponse Resources
Prerequisites for registering a document about a FHIR QuestionnaireResponse are all of:
Prerequisite (Logically) | Criteria |
---|---|
Sharing is allowed for the activity. |
|
The particular FHIR QuestionnaireResponse is approved for document registering. |
|
The FHIR QuestionnaireResponse is a response to a FHIR Questionnaire which is marked up as corresponding to a known and generally accessible, external questionnaire represented as a Questionnaire Form Definition Document (QFDD). Rationale: Document registering of a FHIR QuestionnaireResponse as a Questionnaire Response Document (QRD) document is of reduced value to a clinician retrieving the QRD from document sharing infrastructure if the corresponding questionnaire is not available as a QFDD. |
|
Prerequisites for Document Registering of Appointment Resources
Prerequisites for registering a document about an Appointment are all of:
Prerequisite (Logically) | Criteria |
---|---|
The Appointment is for a single Patient type participant only |
|
The Appointment has legal basis for which national document sharing has been established |
|
Document registering of the Appointment must not be denied |
|
Any previous document registering of the Appointment must not have had its document metadata deprecated by manual procedure. Rationale: An update to an Appointment previously registered as a document leads to a new document with document metadata that replaces the document metadata of the prior document. Manually initiated deprecation must be respected in order for document metadata not “reappearing” of what was previously asked to be removed (deprecated). | Internal bookkeeping must not reflect that manual deprecation has been completed for the Appointment. |
That is, once document metadata has been manually deprecated, further updates of the Appointment resource are not reflected in new Appointment Documents being document registered for that Appointment.
Document Transformation and Registration Processing
The transformation of resources to documents and the subsequent registration to the national document sharing infrastructure is an automatic procedure split in two different processes. The initial process is event driven and is the first attempt at transforming and registering the transformed document. However, a periodic job will attempt to retry the transformation and registration of documents that failed due to either a lack of organizational identification using SOR-ID or a failed registration.
Event Triggered Transformation and Registration
The event driven process goes through the five steps outlined at the top of the page.
determining whether criteria for document registering are met for the FHIR resource in question
assemble to a volatile (in-memory) FHIR Composition
transformation of assembled FHIR Composition to Danish profiles of Clinical Document Architecture (CDA) documents
extract of document metadata from the document and context
registering of document and document metadata in the national health document sharing infrastructure.
If an error occurs during the processing of a resource, the event that triggered it is rolled back. The event is then automatically retried for some time before being put aside on a dead-letter-queue (DLQ) if it keeps failing. The only two exceptions to this are:
When transformation (Step 3) fails due to
Composition.authorOrganization
orComposition.custodian
missing a SOR-ID. In this case the event is not rolled back, the attempt is instead book-kept for a periodic retry job (currently, nightly). The rationale is that missing SOR-ID can occur due to lack of registration by municipalities in the municipal organization register and, once corrected by them, the transformation should be retried. It requires an import from the municipal registration system, see https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/533528597/Importing+and+updating+Organization+information+from+SOR+and+FK-Organisation+into+eHealth+Infrastructure#eHealth-Infrastructure-imports-from-KOMBIT-F%C3%A6lleskommunalt-(FK)-Organisation , which occurs nightly.When the transformation is successful but the registration fails. In this case the event is still rolled back and then automatically retried for some time before being put aside on the dead-letter-queue if it keeps failing. However, an attempt is also book-kept for nightly retry. The reason for this is to allow a series of relatively immediate retries in case of a temporary connection issue, as well as periodic retries if the error is correctible.
Book-keeping of attempts is done internally in the Document-Transformation service in the form of FHIR DocumentReference resources formatted specifically to indicate how far in the process it came:
DocumentReference.masterIdentifier
is set only when transformation is successfulDocumentReference.identifier
is set only when registration is successful.
The following three distinct progressions in the transformation and registration process can be discerned using these elements:
Progression | Distinct Qualities |
---|---|
Transformation failed due to missing organizational identifier as SOR-ID |
No No |
Transformation successful but not registered |
Has No |
Transformed and registered |
( Has Has |
Periodic Retry of Transformation and Registration
The periodic retry job starts by finding the DocumentReference resources for retry based on their distinct qualities (see above). Two different flows are used depending on whether the resources should retry just registration or both transformation and registration. However, the flows both start by checking that the attempt has not been superseded by another successful attempt or a newer document. If so, the DocumentReference is persisted with status=superseded
and no further processing or retries will be attempted.
If only registration is retried, then there are only two primary steps.
Check if the attempt has been superseded by another successful attempt or a newer document.
registering of document and document metadata in the national health document sharing infrastructure.
Should the registration fail once again, an error message is persisted in the DocumentReference, but is still retried again in next period of the periodic retry job.
If both transformation and registration needs to be retried, the process is very similar to that of the event driven procedure.
Check if the attempt has been superseded by a successful attempt or a newer document.
Check if SOR-ID is still missing
assemble to a volatile (in-memory) FHIR Composition
transformation of assembled FHIR Composition to Danish profiles of Clinical Document Architecture (CDA) documents
extract of document metadata from the document and context
registering of document and document metadata in the national health document sharing infrastructure.
If the SOR-ID is still missing, the retry of the DocumentReference is abandoned, but is retried again the next time. However, should the transformation happen to fail due to something else, after the missing SOR-ID has been corrected, the error will be persisted in the DocumentReference resource and will not be retried again in the future, as only the SOR-ID transformation error is currently expected to be correctable (here by external correction in municipal organizational registration, see above).
Document Metadata for Document Registering
The eHealth Infrastructure prepares document metadata that adhere to:
Version 0.96 dated 24 October 2018 of XDS Metadata for Document Profile, Danish Profile
Version 1.0.1 of XDS Metadata ValueSet, Danish Profile
The document metadata described here are those prepared in the IHE XDS.b DocumentEntry structure cf. XDS Metadata for Document Profile, Danish Profile, consisting of a number of attributes.
For the most part, document metadata attributes associated with a document reflects values within the document. Notably, there are the following two exceptions:
DocumentEntry attribute practiceSettingCode - which reflects the clinical specialty in which the document was authored. The eHealth Infrastructure uses an organisational specialty, as described below.
DocumentEntry attribute healthcareFacilityTypeCode - which reflects the organisational unit type
Determining the Organisational Context
The organisational context to use as source for the two document metadata attributes depends on the FHIR resource type which served as the primary driver of the document content:
For FHIR Observation and FHIR QuestionnaireResponse resources, the FHIR Organization is the one referenced from the
ClinicalImpression.assessorOrganization
of the FHIR ClinicalImpression approving document sharing.For FHIR Appointment resources, the FHIR Organization is the one referenced in
Appointment.responsibleOrganization
.
Determining the practiceSettingCode Attribute Value
Whether a FHIR Organization specialty is primary or regular is determined from the Organization.
After release 2024.4
If the FHIR Organization is from the municipal source (imported from the municipal registry FK Organisation), determining the specialty possibly involves traversing the FHIR Organization tree (with municipal source), and using the specialty/specialties (expected to be) registered in the related SOR imported FHIR Organization.
An acceptable specialty is one included in IHE XDS ValueSet https://ehealth.sundhed.dk/fhir/ValueSet-dk-ihe-practicesettingcode-vs.html.
Starting with the Organization resource identified in the organisational context (see above):
If the corresponding SOR imported Organization has a single primary specialty which is acceptable, it is used.
If the corresponding SOR imported Organization has a single primary specialty which is unacceptable, the document registrering is terminated.
If the corresponding SOR imported Organization has multiple primary specialties, the document registrering is terminated.
if the corresponding SOR imported Organization has no specialty/specialties, the parent Organization of the municipal source Organization is considered.
If no specialty has been determined, a fallback value for municipal source Organization specialty is used. Currently the fallback is configured to
code=2903041000005106
,system=http://www.snomed.org/
,display=det kommunale omsorgs-, social- og sundhedsområde
.
If the FHIR Organization has SOR source (has been imported from SOR), then the first primary specialty found on that specific Organization is used, if no primary specialty is present the first regular specialty is used.
The determined specialty code is validated against the IHE XDS ValueSet https://ehealth.sundhed.dk/fhir/ValueSet-dk-ihe-practicesettingcode-vs.html . When valid, the value is used, otherwise the document registering is terminated.
Determining the healthcareFacilityTypeCode Attribute Value
The value of Organization.type
is validated against the IHE XDS ValueSet https://ehealth.sundhed.dk/fhir/ValueSet-dk-ihe-healthcarefacilitytypecode-vs.html . When valid, the value is used, otherwise the document registering is terminated.