How to use _include in search
col-panic opened this issue · 4 comments
The documentation for fhir search states that https://www.hl7.org/fhir/search.html#include requests the server to resolve a reference and include it in the bundles answer.
What is the correct way to use this feature in the fhir.js library? My specific example is for Appointment#INCLUDE_ACTOR
I don't necessarily know the correct way to use this feature, but I thought I'd share what has worked for me while playing around with it. Hopefully it can help you move forward, or someone else can step in and clarify.
The $include query operator
The library includes a $include query operator, but it seems to result in an incorrect query string (maybe based on an older version of the spec?). There's an outstanding PR to update it.
As far as I can tell, it would be used in this way:
client.search({
type: 'Appointment',
query: {
$include: {
Appointment: 'actor'
}
}
});This generates the following request: <baseURL>/Appointment?_include=Appointment.actor
In my experiment, this returned no additional resources.
An alternative
What did get the referenced resources into the bundle was to skip the special query operator.
client.search({
type: 'Appointment',
query: {
_include: 'Appointment:actor'
}
});This generates the following request: <baseURL>/Appointment?_include=Appointment:actor
In my experiment, this did return the referenced resources, included in the bundle.
Thank you very much for your elaborate response! I just implemented a backend for this in https://github.com/elexis/elexis-server/blob/master/bundles/es.fhir.rest.core/src/es/fhir/rest/core/resources/AppointmentResourceProvider.java and using it with the enclosed hapi client in the test file https://github.com/elexis/elexis-server/blob/master/tests/es.fhir.rest.core.test/src/info/elexis/server/fhir/rest/core/resources/AppointmentTest.java works out correctly.
The resulting Bundle delivers both the appointments, and the patient resources included. Next up I will try to use it the way you have described it.
I got it working! Now I can retrieve a bundle like
{
"resourceType": "Bundle",
"id": "f721f2bb-04cc-496f-a4e9-ab93d542e3f4",
"meta": {
"lastUpdated": "2018-09-07T13:37:21.425+02:00"
},
"type": "searchset",
"total": 2,
"link": [
{
"relation": "self",
"url": "http://localhost:8380/fhir/Appointment?_include=Appointment%3Aactor&actor=Schedule%2F68a891b86923dd1740345627dbb92c9f&date=ge2016-12-01&date=lt2016-12-30"
}
],
"entry": [
{
"fullUrl": "http://localhost:8380/fhir/Appointment/o497232fd1c63581e093207",
"resource": {
"resourceType": "Appointment",
"id": "o497232fd1c63581e093207",
"status": "booked",
"description": "Notfall",
"start": "2016-12-28T07:00:00.000+01:00",
"end": "2016-12-28T21:00:00.000+01:00",
"minutesDuration": 840,
"slot": [
{
"reference": "Slot/o497232fd1c63581e093207"
}
],
"participant": [
{
"actor": {
"reference": "Patient/zd8d46d1b8d44330501105"
},
"required": "required",
"status": "accepted"
}
]
}
},
{
"fullUrl": "http://localhost:8380/fhir/Appointment/se4bf3d3fa547776b093261",
"resource": {
"resourceType": "Appointment",
"id": "se4bf3d3fa547776b093261",
"status": "booked",
"description": "Notfall",
"start": "2016-12-29T07:00:00.000+01:00",
"end": "2016-12-29T21:00:00.000+01:00",
"minutesDuration": 840,
"slot": [
{
"reference": "Slot/se4bf3d3fa547776b093261"
}
],
"participant": [
{
"actor": {
"reference": "Patient/s9b71824bf6b877701111"
},
"required": "required",
"status": "accepted"
}
]
}
},
{
"fullUrl": "http://localhost:8380/fhir/Patient/zd8d46d1b8d44330501105",
"resource": {
"resourceType": "Patient",
"id": "zd8d46d1b8d44330501105",
"identifier": [
{
"system": "www.elexis.info/objid",
"value": "zd8d46d1b8d44330501105"
},
{
"system": "www.elexis.info/patnr",
"value": "1"
}
],
"name": [
{
"use": "official",
"family": "Testpatient",
"given": [
"Vorname"
]
}
],
"gender": "male",
"birthDate": "1979-03-15",
"address": [
{
"line": [
"Teststrasse 15"
],
"city": "Testort",
"postalCode": "6840"
}
]
},
"search": {
"mode": "include"
}
},
{
"fullUrl": "http://localhost:8380/fhir/Patient/s9b71824bf6b877701111",
"resource": {
"resourceType": "Patient",
"id": "s9b71824bf6b877701111",
"identifier": [
{
"system": "www.elexis.info/objid",
"value": "s9b71824bf6b877701111"
},
{
"system": "www.elexis.info/patnr",
"value": "2"
}
],
"name": [
{
"use": "official",
"family": "Testpatientin",
"given": [
"Vorname"
]
}
],
"gender": "female",
"birthDate": "1988-06-23",
"address": [
{
"line": [
"Teststrasse 22c"
],
"city": "Testhausen",
"postalCode": "68223"
}
]
},
"search": {
"mode": "include"
}
}
]
}
Now the interesting part is, that the contained resources are simply added to the responses. (This behavior is coherent to the FHIR test-server).
But now I am asking myself, whether FHIR.js provides me with a simple means of accessing the Patient entities directly out of the Appointment resource.
E.g. doing something like entry.resource.participant.actor.reference.name?!
That is - does fhir.js have a helper for resolving https://www.hl7.org/fhir/bundle.html#references ?
also need to add revInclude