Omgang met URL's in FHIR-results

Base URL van FHIR Resource Servers

De base URL (<base>) van een FHIR Resource Server is:

1. Indien <fhir-version> gelijk is aan STU3: https://<FQDN>/fhir, dus bijvoorbeeld "http://myhost.customer.org/fhir"

2. Indien <fhir-version> hoger dan STU3: https://<FQDN>/fhir/<fhir-version>, dus bijvoorbeeld "http://myhost.customer.org/fhir/R4"

R4 ondersteunt impliciet ook R4B.

Wanneer een Resource Server een absolute URL oplevert naar een resource instance, dan:

• moet het base deel van deze URL overeenkomen met de in AORTA vereiste <base>

• moet de Resource Broker ook daadwerkelijk een FHIR-read kunnen uitvoeren op de opgeleverde absolute URL.

Base URL van Resource Broker XX-in

De base URL (<broker-base>) Resource Broker ZA-in is:

• https://<FQDN>{</path extension>}/fhir/<fhir-version>/<aorta-interface-version>

Dus bijvoorbeeld: https://zim.prf001.lsp.aorta-zorg.nl/rbzain/fhir/stu3/v1

De base URL (<broker-base) van Resource Broker MedMij-in is:

• https://<FQDN>{</path extension>}/fhir/<fhir-version>/<gegevensdienst-ID>

Dus bijvoorbeeld: https://accmedmij-pgo2.vzvz.nl/1.6.0/fhir/stu3/48

Self link

Zie:

• https://build.fhir.org/search.html#selflink

De FHIR core stelt het volgende:

• In order to allow the client to be confident about what search parameters were used as criteria by a server, servers SHALL return the parameters that were actually used to process a search.

• Applications processing search results SHALL check these returned values where necessary.

• Self links SHALL be expressed as an HTTP GET-based search with the relevant parameters included as query parameters, because of the semantics around the link types TU. This means that the same self link is a valid response for any equivalent search, regardless of how a search is performed (e.g., HTTP GET, HTTP POST, Messaging, etc.).

• Self links MAY be returned as absolute URIs or URIs relative to the base URL of a server, and MAY or MAY NOT be resolvable TU.

• A server that does not support search via GET will return links in the same style as a server that does not support search via POST. Note that this makes the self link special in the context of bundle links, as all other links are intended to be resolvable by a client.

Resource Server (slechts FHIR-bronnen doen dit) levert op aan Resource Broker (delen weggelaten):

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "http://nictiz2.wildfhir.org/fhir3-0-2-i2/Encounter?class=http%3A%2F%2Fhl7.org%2Ffhir%2Fv3%2FActCode%7CIMP%2Chttp%3A%2F%2Fhl7.org%2Ffhir%2Fv3%2FActCode%7CACUTE%2Chttp%3A%2F%2Fhl7.org%2Ffhir%2Fv3%2FActCode%7CNONAC"
    }
  ]
}

Resource Broker XX-in retourneert aan FHIR Resource Client:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://zim.prf001.lsp.aorta-zorg.nl/rbzain/fhir/stu3/v1/<app-id>/Encounter?class=http%3A%2F%2Fhl7.org%2Ffhir%2Fv3%2FActCode%7CIMP%2Chttp%3A%2F%2Fhl7.org%2Ffhir%2Fv3%2FActCode%7CACUTE%2Chttp%3A%2F%2Fhl7.org%2Ffhir%2Fv3%2FActCode%7CNONAC"
    }
  ]
}

Resource Broker XX-in retourneert aan v3 Resource Client:

• Deze ontvangen niets. Bestaat niet in v3.

Attachment in DocumentReference

Zie:

• https://hl7.org/fhir/R4B/documentreference.html

• https://hl7.org/fhir/R4B/datatypes-definitions.html#Attachment.url

De FHIR core stelt het volgende:

• If both data and url are provided, the url SHALL point to the same content as the data contains.

• Urls may be relative references or may reference transient locations such as a wrapping envelope using cid: though this has ramifications for using signatures.

• Relative URLs are interpreted relative to the service url, like a resource reference, rather than relative to the resource itself.

• If a URL is provided, it SHALL resolve to actual data.

Resource Server levert op aan Resource Broker (delen weggelaten):

{
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "url": "Binary/pdfa-binary1"
      }
    }
  ]
}

Zie ook de AoF specificaties:

• https://aorta-on-fhir.scrollhelp.site/aorta-on-fhir-specificaties/Working-version/use-cases-resource-server#UseCasesResourceServer-Vullingcontent.attachment.url

Wanneer een Resource Server een DocumentReference retourneert, dan dient content.attachment.url als volgt te worden gevuld:

• <base endpointadres van resource server>/Binary/<id>, of

• Binary/<id>

Resource Broker XX-in retourneert aan FHIR Resource Client:

{
  "content": [
    {
      "attachment": {
        "contentType": "application/pdf",
        "url": "<broker-base>/<app-id>/Binary/pdfa-binary1"
      }
    }
  ]
}

Resource Broker XX-in retourneert aan v3 Resource Client:

• Waarschijnlijk is hiervoor geen use case.

FHIR Resource Client (PGO Server of GBx-applicatie) haalt de Binary op:

GET <broker-base>/<app-id>/Binary/pdfa-binary1

Paging

Zie:

• https://build.fhir.org/http.html#paging

• https://build.fhir.org/search.html#paginglinks

De FHIR core stelt het volgende:

• In addition to the self link, many bundles MAY contain links relevant to paging. These are identified via the relation value in the links. Common links include: first, last, next, prev, and previous. Note that prev and previous are widely-used synonyms and are interchangeable.

• Servers SHOULD support paging for the results of a search or history interaction.

• The links in the search are opaque to the client, have no dictated structure, and only the server understands them.

• The client must use the server supplied links in order to traverse the pages.

• In the case of a search, the initial request may be made via a POST, but the follow up page requests will be made via GET requests. However servers SHOULD allow for a client to convert the follow up requests to be made via a POST.

• As with the self link, all relevant paging links SHALL be expressed as GET requests TU.

• Servers SHOULD NOT include content that is considered sensitive in the URLs TU.

De Resource Broker moet dus een GET kunnen uitvoeren op paging links die een Resource Server oplevert.

Resource Server (slechts FHIR-bronnen doen dit) levert op aan Resource Broker (delen weggelaten):

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "next",
      "url": "http://nictiz2.wildfhir.org/fhir3-0-2-i2/Encounter?patient=Patient/abc12345&_getpages=f75fb7d5&_getpagesoffset=500&_count=500"
    }
  ]
}

Resource Broker XX-in retourneert aan FHIR Resource Client:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "next",
      "url": "https://zim.prf001.lsp.aorta-zorg.nl/rbzain/fhir/stu3/v1/80000002/Encounter?patient=Patient/abc12345&_getpages=f75fb7d5&_getpagesoffset=500&_count=500"
    }
  ]
}

Resource Broker XX-in retourneert aan v3 Resource Client:

• VnC zou hier alle pagina’s eerst op kunnen vragen bij de FHIR-bron en ze vervolgens consolideren voor de v3-client. TODO: bespreken met MO. Is er een use case op dit moment? Ook: hoe omgaan met sortering die de client wellicht wenst.

References en fullUrl

Zie:

• https://build.fhir.org/references-definitions.html#Reference.reference

De FHIR core stelt het volgende:

• A reference to a location at which the other resource is found.

• The reference may be a relative reference, in which case it is relative to the service base URL, or an absolute URL that resolves to the location where the resource is found.

• The reference may be version specific or not. If the reference is not to a FHIR RESTful server, then it should be assumed to be version specific.

• Internal fragment references (start with '#') refer to contained resources.

• Using absolute URLs provides a stable scalable approach suitable for a cloud/web context, while using relative/logical references provides a flexible approach suitable for use when trading across closed eco-system boundaries.

• Absolute URLs do not need to point to a FHIR RESTful server, though this is the preferred approach. If the URL conforms to the structure "[type]/[id]" then it should be assumed that the reference is to a FHIR RESTful server.

De Nictiz informatiestandaard stelt het volgende:

• https://informatiestandaarden.nictiz.nl/wiki/FHIR:V1.0_FHIR_IG_R4#Logical_ids.2C_.fullUrls_and_references_in_Bundles

• There are several FHIR operations, like searching or batch create operations, where multiple instances are placed together in a Bundle. These instances will usually contain references to each other. These internal references cannot be resolved simply by inspecting the .id element of every instance; it is not guaranteed that all instances have a logical id.

• Instead, Bundles allow an .entry.fullUrl element for each instance which may be used for references. This is an additional mechanism to the logical id, not a replacement.

• Instances with a logical id

  • If an instance can be accessed on the server using RESTful operations, the .id of that instance in the Bundle will be populated. The corresponding .fullUrl in this case SHALL be the absolute URL to the instance on the server.

  • Instances within the Bundle may use relative references to each other, like they are on the same server. The FHIR machinery specifies how to find the matching instance based on the .fullUrl.

• Instances without a logical id

  • When instances are to be created on a server or when the server doesn't support reading individual instances, they don't have a logical id. When these id-less instances need to be referenced from within a Bundle, there are two alternatives:

    • UUIDs can be used as single-use ids that will change each time the Bundle is generated. The .fullUrl for the instance will be the UUID prefixed with urn:uuid:.

    • OIDs can be used if the instance has an OID-based business identifier (i.e. the .identifier field), like the UZI number of a healthcare provider. The .fullUrl will be the OID prefixed with urn:oid:

  • Instances within the Bundle should use the prefixed version of the UUID/OID for referencing.

Zie:

• https://hl7.org/fhir/R4B/bundle-definitions.html#Bundle.entry.fullUrl

De FHIR core stelt het volgende:

• The Absolute URL for the resource.

• The fullUrl SHALL NOT disagree with the id in the resource - i.e. if the fullUrl is not a urn:uuid, the URL shall be version-independent URL consistent with the Resource.id.

• The fullUrl is a version independent reference to the resource.

• The fullUrl element SHALL have a value except that:

  • fullUrl can be empty on a POST (although it does not need to when specifying a temporary id for reference in the bundle)

  • Results from operations might involve resources that are not identified.

AoF specificaties:

• https://aorta-on-fhir.scrollhelp.site/aorta-on-fhir-specificaties/Working-version/interfaces-resource-server#InterfacesResourceServer-Omgangmetid,fullUrlenreference

AORTA eis m.b.t. vulling van resource.id

Een FHIR resource die door een bronsysteem wordt opgeleverd in een search kan zijn voorzien van een id attribuut, binnen FHIR ook wel aangeduid als een logical id. Dit is een technische sleutel die geacht wordt uniek te zijn en hetzelfde te blijven binnen een resource server, zodat duplicaten eenduidig kunnen worden herkend. Het id attribuut is verplicht wanneer de implementatie van een informatiestandaard voor een gegevensdienst één of meerdere interacties bevat (bijvoorbeeld een read- of een update-interactie) waarvoor het resource.id attribuut nodig is.

Wanneer een resource server resource.id vult, dan dient deze te voldoen aan de eisen die FHIR stelt aan logical id's.

Vulling van bundle.entry.fullUrl

Een absolute fullUrl, die wijst naar de instance op de server, is slechts vereist wanneer een resource instance in de Bundle middels een FHIR-read, FHIR-update, FHIR-patch of een FHIR-delete moet kunnen worden benaderd. Een fullUrl in de bundle entry wordt in andere situaties gevuld met een single-use UUID, of met een OID.

Wanneer een Resource Server een FHIR Bundle retourneert met een absolute URL (fullUrl of reference), dan dient deze URL het volgende formaat te hebben:

• <base>/<type>/<id>

Resource Server (slechts FHIR-bronnen doen dit) levert op aan Resource Broker (delen weggelaten):

<Bundle	xmlns="http://hl7.org/fhir">
	<type value="searchset"/>
	<entry>
		<fullUrl value="https://connectathon-nl-lsp.epic.com/interconnect-fhir-poc/api/FHIR/STU3/Patient/eiis8MulmavsBP8TZy3Ef7w3"/>
		<resource>
			<Patient>
				<id value="eiis8MulmavsBP8TZy3Ef7w3"/>
				..
				<generalPractitioner>
					<reference value="Practitioner/eSJ0snyPHnODJzVMz1qE3Qw3"/>
				</generalPractitioner>
				<managingOrganization>
					<reference value="https://connectathon-nl-lsp.epic.com/interconnect-fhir-poc/api/FHIR/STU3/Organization/exRTp91TIiYuYvNeWKhPEHA3"/>
					<display value="Amphia Ziekenhuis"/>
				</managingOrganization>
			</Patient>
		</resource>
	</entry>
	<entry>
		<resource>
			<Practitioner>
				<id value="eSJ0snyPHnODJzVMz1qE3Qw3"/>
				..
			</Practitioner>
		</resource>
	</entry>
</Bundle>

Resource Broker XX-in retourneert aan FHIR Resource Client:

<Bundle	xmlns="http://hl7.org/fhir">
	<type value="searchset"/>
	<entry>
		<fullUrl value="https://zim.prf001.lsp.aorta-zorg.nl/rbzain/fhir/stu3/v1/80000002/Patient/eiis8MulmavsBP8TZy3Ef7w3"/>
		<resource>
			<Patient>
				<id value="eiis8MulmavsBP8TZy3Ef7w3"/>
				..
				<generalPractitioner>
					<reference value="Practitioner/eSJ0snyPHnODJzVMz1qE3Qw3"/>
				</generalPractitioner>
				<managingOrganization>
					<reference value="https://zim.prf001.lsp.aorta-zorg.nl/rbzain/fhir/stu3/v1/80000002/Organization/exRTp91TIiYuYvNeWKhPEHA3"/>
					<display value="Amphia Ziekenhuis"/>
				</managingOrganization>
			</Patient>
		</resource>
	</entry>
	<entry>
		<resource>
			<Practitioner>
				<id value="eSJ0snyPHnODJzVMz1qE3Qw3"/>
				..
			</Practitioner>
		</resource>
	</entry>
</Bundle>

Resource Broker XX-in retourneert aan v3 Resource Client:

• De informatie zit dan in de response, of ontbreekt in de response.

Transformatie van v3-response naar FHIR-result

Self link

BTD levert op aan RB VnC:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://ontmedmij-vzvz.ezorg.aorta-zorg.nl"
    }
  ]
}

De kennis over welke v3-query is uitgevoerd ligt bij RB VnC. De v3-query is opgebouwd o.b.v. de smart scope in het access_token. Deze scope kan dus ook worden gebruikt om de juiste FHIR parameters op te nemen in de self link. RB VnC weet ook via welke RB XX-in de FHIR-search is binnengekomen.

Het zou kunnen gebeuren dat niet alle parameters in de scope van het access_token een plaats hebben in de uitgestuurde v3-query. Voor nu gaan we ervan uit dat dit wel dekkend is.

De werkelijke self link wordt gemaakt door VnC zelf.

Resource Broker XX-in retourneert aan FHIR Resource Client:

{
  "resourceType": "Bundle",
  "type": "searchset",
  "link": [
    {
      "relation": "self",
      "url": "https://zim.prf001.lsp.aorta-zorg.nl/rbzain/fhir/stu3/v1/Appointment"
    }
  ]
}

References en fullUrl

BTD voegt UUID’s toe om referenties te kunnen maken.