Skip to content
This repository has been archived by the owner on Mar 22, 2024. It is now read-only.

Process Data Sharing Start v0.3.1

Jump to bottom
Reto Wettstein edited this page Apr 12, 2023 · 10 revisions

This page lists FHIR resources that can be used to prepare the DIC KDS FHIR store before answering a manual user tasks and start the data-sharing coordinate process at a HRP. The following needs to be known beforehand:

DIC:

  • The DIC identifier of the local organization
  • A project identifier for which results should be extracted and transmitted
  • The project results (i.e. the actual data) that should be transmitted

HRP:

  • The HRP identifier wich coordinates the process
  • A project identifier for which results should be extracted and merged
  • The URL where the data-sharing contract can be accessed
  • The COS identifier which should receive the individual DIC project results
  • The DIC identifiers which should provide the project results
  • The Researcher identifiers which should get access to the merged project results

It is important to differentiate between the DSF FHIR server and the KDS FHIR store. The DSF FHIR server contains all FHIR resources of the DSF needed for process flow and the KDS FHIR store contains the project results (i.e. the actual data) to be transmitted. These are two different FHIR servers.

DIC: Prepare KDS FHIR Store before Answering a Manual User Task

Before answering the manual user tasks release-data-set requiring input in the DSF user interface as part of the data-sharing execute process, the DIC KDS FHIR store needs to be prepared with the data that should be transmitted to the COS.

To prepare your DIC KDS FHIR store manually, upload a Transaction Bundle like the following examples containing a DocumentReference resource and a linked Binary or Bundle as attachment resource. Please replace all placeholders in the form <REPLACE-WITH-...>. For the placeholders concerning a UUID, please make sure to use the same placeholder inside one Transaction Bundle of one project, but different UUIDs in Transaction Bundles of different projects.

To send the Transaction Bundle to a KDS FHIR store with basic authentication, the following cURL command could be used:

curl \
-u "<username>:<password>" \ 
-H "Accept: application/fhir+xml" -H "Content-Type: application/fhir+xml" \
-d @transaction-bundle.xml \
https://<kds-fhir-base-url>/fhir

Notice: On Windows you need to remove the \ multi-line command seperators.

The individual parts of the command have the following meaning:

  • <username> represents the basic authentication username
  • <password> represents the basic authentication password
  • transaction-bundle.xml contains the corresponding Transaction Bundle resource from below
  • <kds-fhir-base-url> needs to be replaced with the base url of your KDS FHIR store

Notice 2: This works only if you are using a HAPI FHIR server as your DIC KDS FHIR store having set the environment variable HAPI_FHIR_ALLOWED_BUNDLE_TYPES: COLLECTION,DOCUMENT,MESSAGE,TRANSACTION,TRANSACTIONRESPONSE,BATCH,BATCHRESPONSE,HISTORY,SEARCHSET. If you are using a BLAZE FHIR server with Version < 0.18.2 as your DIC KDS FHIR store, you have to upload and link both resources separately. Start by uploading the attachment resource, add the id of the attachment resource to DocumentReference.content.attachment.url and upload the DocumentReference resource.

Decentralyzed Analysis (VHF-MI-dezentral / WE-STORM):

This Transaction Bundle containing a DocumentReference resource with a linked Binary resource should be used in the Projectathon 7 projects with identifier VHF-MI-dezentral and WE-STORM.

To encode the results in a csv- or zip-file as base64 format, the following command could be used: base64 /path/to/file.

<Bundle xmlns="http://hl7.org/fhir">
	<type value="transaction"/>
	<entry>
		<fullUrl value="DocumentReference/<REPLACE-WITH-DOCUMENT-REFERENCE-UUID>"/>
		<resource>
			<DocumentReference xmlns="http://hl7.org/fhir">
				<id value="<REPLACE-WITH-DOCUMENT-REFERENCE-UUID>" />
				<masterIdentifier>
					<system value="http://medizininformatik-initiative.de/sid/project-identifier"/>
					<!-- Example: <value value="VHF-MI-dezentral"/> -->
					<!-- Example: <value value="WE-STORM"/> -->
					<value value="<REPLACE-WITH-PROJECT-IDENTIFIER>"/>
				</masterIdentifier>
				<status value="current"/>
				<docStatus value="final"/>
				<author>
					<type value="Organization"/>
					<identifier>
						<system value="http://highmed.org/sid/organization-identifier"/>
						<!-- Example: <value value="ukhd.de"/> -->
						<value value="<REPLACE-WITH-YOUR-ORGANIZATION-IDENTIFIER>"/>
					</identifier>
				</author>
				<!-- Example: <date value="2022-11-16T15:00:00+01:00"/> -->
				<date value="<REPLACE-WITH-DATE-TIME>"/>
				<content>
					<attachment>
						<!-- Example: <contentType value="text/csv"/> -->
						<!-- Example: <contentType value="application/zip"/> -->
						<contentType value="<REPLACE-WITH-CONTENT-TYPE>"/>
						<url value="Binary/<REPLACE-WITH-BINARY-UUID>"/>
					</attachment>
				</content>
			</DocumentReference>
		</resource>
		<request>
			<method value="PUT"/>
			<url value="DocumentReference/<REPLACE-WITH-DOCUMENT-REFERENCE-UUID>"/>
		</request>
	</entry>
	<entry>
		<fullUrl value="Binary/<REPLACE-WITH-BINARY-UUID>"/>
		<resource>
			<Binary xmlns="http://hl7.org/fhir">
				<id value="<REPLACE-WITH-BINARY-UUID>" />
				<!-- Example: <contentType value="text/csv"/> -->
				<!-- Example: <contentType value="application/zip"/> -->
				<contentType value="<REPLACE-WITH-CONTENT-TYPE>"/>
				<!-- Example: <data value="base-64-data-omitted"/> -->
				<data value="<REPLACE-WITH-BASE64-ENCODED-DATA-MATCHING-CONTENT-TYPE>"/>
			</Binary>
		</resource>
		<request>
			<method value="PUT"/>
			<url value="Binary/<REPLACE-WITH-BINARY-UUID>"/>
		</request>
	</entry>
</Bundle>

Centralized Analysis (VHF-MI-2-zentral):

This Transaction Bundle containing a DocumentReference resource with a linked Bundle resource should be used in the Projectathon 7 project with identifier VHF-MI-2-zentral.

Caution: The following Transaction Bundle for DIC KDS FHIR store preparation can be omitted if you are using the script provided for data extraction, pseudonymization and data-set upload in the project VHF-MI-2-zentral using the option --storebundle.

<Bundle xmlns="http://hl7.org/fhir">
	<type value="transaction"/>
	<entry>
		<fullUrl value="DocumentReference/<REPLACE-WITH-DOCUMENT-REFERENCE-UUID>"/>
		<resource>
			<DocumentReference xmlns="http://hl7.org/fhir">
				<id value="<REPLACE-WITH-DOCUMENT-REFERENCE-UUID>" />
				<masterIdentifier>
					<system value="http://medizininformatik-initiative.de/sid/project-identifier"/>
					<!-- Example: <value value="VHF-MI-2-zentral"/> -->
					<value value="<REPLACE-WITH-PROJECT-IDENTIFIER>"/>
				</masterIdentifier>
				<status value="current"/>
				<docStatus value="final"/>
				<author>
					<type value="Organization"/>
					<identifier>
						<system value="http://highmed.org/sid/organization-identifier"/>
						<!-- Example: <value value="ukhd.de"/> -->
						<value value="<REPLACE-WITH-YOUR-ORGANIZATION-IDENTIFIER>"/>
					</identifier>
				</author>
				<!-- Example: <date value="2022-11-16T15:00:00+01:00"/> -->
				<date value="<REPLACE-WITH-DATE-TIME>"/>
				<content>
					<attachment>
						<!-- Example: <contentType value="application/fhir+xml"/> -->
						<contentType value="<REPLACE-WITH-CONTENT-TYPE>"/>
						<url value="Bundle/<REPLACE-WITH-BUNDLE-UUID>"/>
					</attachment>
				</content>
			</DocumentReference>
		</resource>
		<request>
			<method value="PUT"/>
			<url value="DocumentReference/<REPLACE-WITH-DOCUMENT-REFERENCE-UUID>"/>
		</request>
	</entry>
	<entry>
		<fullUrl value="Bundle/<REPLACE-WITH-BUNDLE-UUID>"/>
		<resource>
			<Bundle xmlns="http://hl7.org/fhir">
				<id value="<REPLACE-WITH-BUNDLE-UUID>" />
				<!-- Example: <type value="transaction"/><entry> ... </entry>/> -->
				<REPLACE-WITH-BUNDLE-RESOURCE-CONTENT>
			</Bundle>
		</resource>
		<request>
			<method value="PUT"/>
			<url value="<REPLACE-WITH-BUNDLE-UUID>"/>
		</request>
	</entry>
</Bundle>

DIC: Release Data by Answering a Manual User Task

All manual user tasks are created as QuestionnaireResponse resources on your DSF FHIR server. To answer a manual user task you need access to a web browser which can use your DSF client certificate.

If e-mail notifications have been activated as part of the DSF BPE deployment, an e-mail is sent with every new created manual user task containing it's interface URL location refering to a form the be filled out.

If e-mail notifications are deactivated, a list of all manual user tasks that are waiting to be answered can be found using the URL https://<dsf-fhir-base-url>/fhir/QuestionnaireResponse?status=in-progress&_sort=-_lastUpdated. Selecting a single QuestionnaireResponse from the list by clicking on it's fullURL value will redirect you to the manual user task's interface consisting of a form the be filled out:

Projectathon Data-Sharing: Manual User Task In-Progress

After completing the form by following it's instructions, the user task can be answered by clicking the submit button. If the form has been submitted and the answers could be stored successfully it changes into read-only. If errors occur, they are displayed in the corresponding form section.

Projectathon Data-Sharing: Manual User Task Released

HRP: Start Coordinate Process

To start the data-sharing coordinate process, a Task resource like the following example has to be sent to the HRP DSF FHIR server. Please replace all placeholders in the form <REPLACE-WITH-...>.

To send the Task resource to the DIC DSF FHIR server, the following cURL command could be used:

curl \
--cert client-certificate.pem \
--key client-certificate_private-key.pem \
-H "Accept: application/fhir+xml" -H "Content-Type: application/fhir+xml" \
-d @task.xml \
https://<dsf-fhir-base-url>/fhir/Task

Notice: On Windows you need to remove the \ multi-line command seperators.

The individual parts of the command have the following meaning:

  • task.xml contains the corresponding Task resource from below
  • client-certificate.pem contains your client-certificate
  • client-certificate_private-key.pem contains the private-key belonging to your client-certificate
  • <dsf-fhir-base-url> needs to be replaced with the base url of your DSF FHIR server

Task: Data-Sharing Coordinate Process

<Task xmlns="http://hl7.org/fhir">
   <meta>
      <profile value="http://medizininformatik-initiative.de/fhir/StructureDefinition/task-coordinate-data-sharing|0.3.1" />
   </meta>
   <instantiatesUri value="http://medizininformatik-initiative.de/bpe/Process/coordinateDataSharing/0.3.1"/>
   <status value="requested"/>
   <intent value="order"/>
   <!-- Example: <authoredOn value="2022-11-16T15:00:00+01:00"/> -->
   <authoredOn value="<REPLACE-WITH-DATE-TIME>"/>
   <requester>
      <type value="Organization"/>
      <identifier>
         <system value="http://highmed.org/sid/organization-identifier"/>
         <!-- Example: <value value="forschen-fuer-gesundheit.de"/> -->
         <value value="<REPLACE-WITH-HRP-ORGANIZATION-IDENTIFIER>"/>
      </identifier>
   </requester>
   <restriction>
      <recipient>
         <type value="Organization"/>
         <identifier>
            <system value="http://highmed.org/sid/organization-identifier"/>
            <!-- Example: <value value="forschen-fuer-gesundheit.de"/> -->
         <value value="<REPLACE-WITH-HRP-ORGANIZATION-IDENTIFIER>"/>
         </identifier>
      </recipient>
   </restriction>
   <input>
      <type>
         <coding>
            <system value="http://highmed.org/fhir/CodeSystem/bpmn-message"/>
            <code value="message-name"/>
         </coding>
      </type>
      <valueString value="coordinateDataSharing"/>
   </input>
   <input>
      <type>
         <coding>
            <system value="http://medizininformatik-initiative.de/fhir/CodeSystem/data-sharing"/>
            <code value="project-identifier"/>
         </coding>
      </type>
      <valueIdentifier>
         <system value="http://medizininformatik-initiative.de/sid/project-identifier"/>
         <!-- Example: <value value="VHF-MI-dezentral"/> -->
         <!-- Example: <value value="VHF-MI-2-zentral"/> -->
         <!-- Example: <value value="WE-STORM"/> -->
         <value value="<REPLACE-WITH-PROJECT-IDENTIFIER>"/>
      </valueIdentifier>
   </input>
   <input>
      <type>
         <coding>
            <system value="http://medizininformatik-initiative.de/fhir/CodeSystem/data-sharing"/>
            <code value="contract-location"/>
         </coding>
      </type>
      <!-- Example: <valueUrl value="http://forschen-fuer-gesundheit.de/contract/VHF-MI-dezentral"/> -->
      <!-- Example: <valueUrl value="http://forschen-fuer-gesundheit.de/contract/VHF-MI-2-zentral"/> -->
      <!-- Example: <valueUrl value="http://forschen-fuer-gesundheit.de/contract/WE-STORM"/> -->
      <valueUrl value="<REPLACE-WITH-CONTRACT-LOCATION-URL>"/>
   </input>
   <input>
      <type>
         <coding>
            <system value="http://medizininformatik-initiative.de/fhir/CodeSystem/data-sharing"/>
            <code value="cos-identifier"/>
         </coding>
      </type>
      <valueReference>
         <type value="Organization"/>
         <identifier>
            <system value="http://highmed.org/sid/organization-identifier"/>
            <!-- Example: <value value="uniklinikum-leipzig.de"/> -->
            <!-- Example: <value value="ukdd.de"/> -->
            <value value="<REPLACE-WITH-COS-IDENTIFIER>"/>
         </identifier>
      </valueReference>
   </input>
   <!-- Repeat for every DIC which should provide the project results -->
   <input>
      <type>
         <coding>
            <system value="http://medizininformatik-initiative.de/fhir/CodeSystem/data-sharing"/>
            <code value="medic-identifier"/>
         </coding>
      </type>
      <valueReference>
         <type value="Organization"/>
         <identifier>
            <system value="http://highmed.org/sid/organization-identifier"/>
            <!-- Example: <value value="ukhd.de"/> -->
            <value value="<REPLACE-WITH-DIC-IDENTIFIER>"/>
         </identifier>
      </valueReference>
   </input>
   <!-- Repeat for every researcher which should get access to the merged project results -->
   <input>
      <type>
         <coding>
            <system value="http://medizininformatik-initiative.de/fhir/CodeSystem/data-sharing"/>
            <code value="researcher-identifier"/>
         </coding>
      </type>
      <valueIdentifier>
         <system value="http://medizininformatik-initiative.de/sid/researcher-identifier"/>
         <!-- Example: <value value="researcher-1"/> -->
         <value value="<REPLACE-WITH-RESEARCHER-IDENTIFIER>"/>
      </valueIdentifier>
   </input>
</Task>
Clone this wiki locally