Patient Lists API

# Patient Lists API ![](https://i.imgur.com/YhRyK05.png) [TOC] ## Background User-facing apps often need to know things like: - "who are the patients I'm seeing today," - "who are the patients I'm responsible for in the hospital right now," - "who are the patients in this ward." This is core functionality supported by existing EHR systems. In FHIR, various methods have been used such as the standard search API or assembling the List or Group resource. However, no standard or guidance for creation of and manipulation of patient lists currently exists. *Note: When we say "EHR" in this document, we don't mean to limit ourselves to electronic health record systems; the same technology can be used in HIEs, care coordination platforms, popoulation health systems, etc. Please read "EHR" here as a short-hand notation for something like "interoperable healthcare platform".* ## Goals * Support interoperable and standard exchange of existing EHR supported "user-facing lists". - user-facing lists include both "system-maintained" and "user-maintained"(which are entirely ad-hoc - the user explicitly selects and manages members) lists * Define a general framework using the FHIR API for exposing existing EHR user-facing patient lists so that EHR systems can expose any list they choose to define. * API would allows user-facing apps to: 1. Discovery of user-facing lists - Search on existing list using very limited set of parameters such as "location characterstics" (for system-maintained lists) or Practitioner (for user-maintained list) - [? identify a "default list"] 1. Fetching the List allowing app to enumerate members of a user-facing list 1. Provide a framework to convey details about the members of a list :::info Out of scope: - write (create/manage) a patient list by explicit membership** - Identify a "default list" - e.g., What list *should* start with - e.g., display on user start? :::  ## API Design Sketch ### Sequence Diagrams Overview of Basic Transactions Option 1: The client can fetch and display other details about the members on the patient list using RESTful data query on USCore ( what about GRAPHQL? ) ```sequence Note left of Client: Discovery:\n Fetch Summary of\n Patients Lists Client->EHR FHIR Server:GET Group?... Note right of EHR FHIR Server: Based on User\n return Bundle of \nUser Facing Lists EHR FHIR Server->Client: Bundle Note left of Client: End User\nselects Patient List\n they want Client->EHR FHIR Server:GET Group/[id] Note right of EHR FHIR Server: Returns full Group\n resource EHR FHIR Server->Client: Group Note left of Client: Client Application\n MAY fetch more data for \neach member using a \nseries of FHIR API\n queries Note right of EHR FHIR Server: Returns search results Client->EHR FHIR Server:Query 1 EHR FHIR Server->Client: Client->EHR FHIR Server:Query 2 EHR FHIR Server->Client: Client->EHR FHIR Server:etc EHR FHIR Server->Client: Note left of Client: Client Application\n processes/displays/etc\n Group Members\nto End User ``` Option 2: The client can fetch and display other details about the members on the patient list using *TBD* framework defined below ```sequence Note left of Client:1. Discovery:\n Fetch Summary of\n Patients Lists Client->EHR FHIR Server:GET Group?... Note right of EHR FHIR Server: Based on User\n return Bundle of \nUser Facing Lists EHR FHIR Server->Client: Bundle Note left of Client: 2. End User\nselects Patient List\n they want Client->EHR FHIR Server:GET Group/[id] Note right of EHR FHIR Server: Returns full Group\n resource EHR FHIR Server->Client: Group Note left of Client: 3. Client Application MAY\n fetches more data for \neach member using a \nTBD transaction Note right of EHR FHIR Server: Returns requested data Client->EHR FHIR Server: requests additional data for patients EHR FHIR Server->Client: Note left of Client: 4. Client Application\n processes/displays/etc\n Group Members\nto End User ``` ### Argonaut Patient List (Group) Profile Rendered output [ArgonautPatientListProfile](https://healthedata1.github.io/Sushi-Sandbox/StructureDefinition-argo-patientlist.html#root) <iframe src="https://healthedata1.github.io/Sushi-Sandbox/StructureDefinition-argo-patientlist.html#root" width="100%" height="500"> </iframe> or this [rendering](https://simplifier.net/snippet/ehaas/1) from Simplifier <iframe src="https://simplifier.net/snippet/ehaas/1" width="100%" height="100%"> </iframe> #### Questions and issue: 1. See comments in for each element by clicking on them. 1. Binding and Valueset for Characteristics: - Starter set: 1.`location` see definition by clicking on the Binding 2. `today`. `tomorrow` ??? coded vs using Group.characteristic.period or both options 3. 'rounds' -whatever that means ??? 1. Must `Group.member` be a literal reference (e.g. "Patient/123" ) or can it be a logical reference (e.g a MRN ) as well ? ### Discovery of user-facing lists ```sequence Note left of Client: Discovery:\n Fetch Summary of\n Patients Lists Client->EHR FHIR Server:GET Group?... Note right of EHR FHIR Server: Based on User\n return Bundle of \nUser Facing Lists EHR FHIR Server->Client: Bundle ``` To get all user-facing lists based on user scopes, it's just FHIR Query on the [Group](http://build.fhir.org/group.html) profile using the required parameter `_summary`. What is returned is *Bundle* of Group resources. :::info **Sidebar Group vs List Resource**: There is some overlapping functionality between List and Group in FHIR. The methodological difference is that: - Group is an actor - a collection that can be a subject of an observation, a recipient of data, etc. It is primarily defined by criteria... - List on the other hand, is NOT an actor. It is an organizer for presentation purposes only. It is always enumerated and has no defined criteria. Whether this difference merits 2 distinct resources remains an open question. The key practical advantages of Group is: 1. Support of the element and searchparameters for both the `type` - "person" in our case - and `managingEntity` for user and system maintained lists. In other words, it allow querying for a patient list based on multiple existing elements and search parameters without having to create extensions and custom search parameters in order to return a targeted list of lists. 1. Ability to display the members for presrentation when fetching an individual list. >Note that Group has no analogous search parameter to [_list](http://build.fhir.org/search.html#list). ::: 1. **SHALL** support fetching all user-facing lists `GET Group?_summary=true&type=person` :::info Note that authorization side deals with user scopes ::: **Example** *Assuming Client for Dr Smith, get all user-facing lists for Dr Smith* **Request**: `GET Group?_summary=true&type=person` **Response Body: A Bundle of Groups ( i.e., group a,b,c )** (example here) 2. **SHOULD** support fetching all “system-maintained” and “user-maintained” lists with managingEntity` search parameter `GET Group?_summary=true&type=person&managingEntity=Organization/organization-123` `GET Group?_summary=true&type=person&managingEntity=Practitioner/practioner-123` :::warning There is no Group element that defines how a member got the list which would differentiate between user-maintained/system-maintained lists. However, the Provenance resource could be used to provide this data. ::: **Example** *Assuming Client for Dr Smith, get all system-mantained patient lists for Dr Smith* **Request**: `GET Group?_summary=true&type=person&managingEntity=Organization/organization-example-2` **Response Body: A Bundle of “system-maintained” lists**: ~~~json { "resourceType": "Bundle", "id": "1bd2b9a1-0feb-405c-bfb1-b4ea83f1d136", "type": "searchset", "total": 6, "entry": [ { "fullUrl": "http://hapi.fhir.org/baseR4/Group/group-active-today-20200505060432348158", "resource": { "resourceType": "Group", "id": "group-active-today-20200505060432348158", "identifier": [ { "system": "http://example.org", "value": "group-active-today-20200505060432348158" } ], "active": true, "type": "person", "actual": true, "name": "active-today", "managingEntity": { "reference": "Organization/example-organization-2", "display": "US Core Example Organization 2" } }, "search": { "mode": "match" } }, ... ]} ~~~ 3. **MAY** Search on existing list using very limited set of parameter Searching for lists: functional requirements * We definitely want a way to search for all lists that a user is allowed to see * We definitely want a way to search for user-managed lists that are managed by a specific practitioner * System-managed lists and user-managed lists SHALL have a name/title * System-managed lists **SHOULD** support characteristics: - **SHOULD** have characteristics for location-based lists and maybe a couple of other categories we define; and they - **MAY** have characteristics for other categories - Servers **SHOULD** support *search* based on characteristics (things like `GET Group?characteristic-value=`) :::warning This does not enable apps to filter a list client-side to show only certain members, since all the members will meet the group characteristic. ::: Starter set of parameters: <table border="black"> <thead> <tr> <th>Characteristic</th> <th>code</th> <th>Characteristic Value</th> <th>Value</th> </tr> </thead> <tbody><tr> <td>characteristic</td> <td>location</td> <td>value-reference</td> <td>Location/[location_id]</td> </tr> <tr> <td>characteristic</td> <td>practitioner</td> <td>value-reference</td> <td>Practitioner/[practitioner_id]</td> </tr> <tr> <td>characteristic</td> <td>organization</td> <td>value-reference</td> <td>Organization/[organization_id]</td> </tr> <tr> <td>characteristic</td> <td>team</td> <td>value-reference</td> <td>CareTeam/[careteam_id]</td> </tr> </tbody></table> [CodeSystem definition](https://healthedata1.github.io/Sushi-Sandbox/CodeSystem-argo-group-characteristic.html#root) <iframe src="https://healthedata1.github.io/Sushi-Sandbox/CodeSystem-argo-group-characteristic.html#root" width="100%" height="500"> </iframe> `value-reference` is a custom SearchParameter formally defined here: (see FHIR-NNNN for addition to the base FHIR specification for R5) [GroupValueReference](https://healthedata1.github.io/Sushi-Sandbox/docs/SearchParameter-Group-value-reference.html#root) <iframe src="https://healthedata1.github.io/Sushi-Sandbox/SearchParameter-Group-value-reference.html#root" width="100%" height="500"> </iframe> or this [rendering](https://simplifier.net/snippet/ehaas/2) from Simplifier <iframe src="https://simplifier.net/snippet/ehaas/1" width="100%" height="100%"> </iframe> **Usage:** A client issues a GET request to a server: `GET Group?_summary=true&type=person&characteristic=[Code value]&value-reference=[Value value]` example todo: ### Fetching the List ```sequence Note left of Client: End User\nselects Patient List\n they want Client->EHR FHIR Server:GET Group/[id] Note right of EHR FHIR Server: Returns full Group\n resource EHR FHIR Server->Client: Group ``` The Group/List resource are enumerated ('actual' = true) lists. It would be basic FHIR RESTful GET operation **SHALL** be used to fetch the List and all the members references in it. GET Group/[id] :::warning Issue: Paging when the lists are big See [this chat](https://chat.fhir.org/#narrow/stream/179166-implementers/topic/Operations.20to.20manage.20big.20List.20and.20Group.20resources) about managing big Group resources ::: **Example**: GET Group/all-patients-example **Example Response body**: ~~~ { "resourceType": "Group", "id": all-patients-example "active": true, "type": "person", "actual": true, "name": "all_patients", "managingEntity": { "reference": "Organization/example", "display": "example managingEntity" }, "member": [ { "entity": { "identifier": { "system": "http://example.org", "value": "123" }, "display": "Name = Amy Brown (MRN = 123)" }, "inactive": false }, { "entity": { "identifier": { "system": "http://example.org", "value": "234" }, "display": "Name = Bert Black (MRN = 234)" }, "inactive": false }, ... ] } } ~~~ ### Provide a framework to convey details about the members of a list ```sequence Note left of Client: Client Application\n MAY fetch more data about \n members Client->EHR FHIR Server: EHR FHIR Server->Client: Note left of Client: Client Application\n processes/displays/etc\n Group Members\nto End User ``` What about the rest of the columns beside patient name and id ?... End users often sort through a list of patient to stratify them on some information about those patient. name, age, sex, when last viewed, todo, orders, some score, etc. Leverage existing FHIR Models and APIs to provide the additional information in addition to patients that offers consistency, availability and scalability? Options: 1. The client can fetch and other display data using RESTful data query on USCore ```sequence Note left of Client: Client Application\n MAY fetch more data for \neach member using a \nseries of FHIR API\n queries Note right of EHR FHIR Server: Returns search results Client->EHR FHIR Server:Query 1 EHR FHIR Server->Client: Client->EHR FHIR Server:Query 2 EHR FHIR Server->Client: Client->EHR FHIR Server:etc EHR FHIR Server->Client: Note left of Client: Client Application\n processes/displays/etc\n Group Members\nto End User ``` - Get Patient List then for each member Get X resources :::warning - This approach may be prohibitively expensive for client - is GraphQL an option? ::: 2. Source System can define the other display data using an existing [FHIR Questionnaire](http://build.fhir.org/questionnaire.html): ```sequence Note left of Client: Client Application MAY\n fetches more data for \neach member using a \ntransaction defined here Note right of EHR FHIR Server: Returns requested data Client->EHR FHIR Server: requests additional data for patients EHR FHIR Server->Client: Note left of Client: Client Application\n processes/displays/etc\n Group Members\nto End User ``` - discovery of a form definition that is bound to certain types of lists and interoperably defines each column. - retrieval of List along with the associated member metadata (structured or unstructured) as associated QuestionnaireResponse for each member. 3. A hybrid approach where both system and client supplied display data. Options depend on use cases: - In some contexts the display data is static and known by the list source. - In other use cases the list source doesn't know the context of usage (e.g., an ER status board) then it is up to the client to fetch the additional data. :::info **Ideas for conveying Questionnaires with extensions** An extension on Group that references Questionniare then you can issue queries for the column data, (maybe with a custom operation) i.e. * let client issue batch queries for the columns associated row data which would be returned as FHIR QA * ...or a single transaction to get a Bundle with Group and QA entries or (contained QAs), one for each member. and references via an extension on each Group.member. * ...or a single transaction to get a Group with extensions on each member supplying both a reference to a resource and the raw column data. ::: ### Patients with column data **Request**: `GET http://hapi.fhir.org/baseR4/Group/1171742` **Response body**: :::success #### Extensions for "column" data We can convey these additional per-member data using two extensions on Group: 1) http://registry.fhir.org/argonaut/patientlistsquestionnairev1 at `Group.extension` defines a "template" of the additional columns of data in a patient list. <iframe src="https://healthedata1.github.io/Sushi-Sandbox/StructureDefinition-patientlistquestionnaire.html#root" width="100%" height="500"> </iframe> 3) http://registry.fhir.org/argonaut/patientlistsquestionnaireresponsev1 at `Group.member.entity.extension` contains the actual row-level data with one QuestionnaireResponse for each patient in the list. <iframe src="https://healthedata1.github.io/Sushi-Sandbox/StructureDefinition-patientlistquestionnaireresponse.html#root" width="100%" height="500"> </iframe> ::: ~~~js { "resourceType": "Group", "extension": [{ "url": "http://registry.fhir.org/argonaut/patientlistsquestionnairev1", "valueReference": { "reference": "Questionnaire/1169270" } }], "identifier": [{ "system": "http://example.org", "value": "dba0a9f9-82cb-4d42-ad92-3250756a9420" }], "active": true, "type": "person", "actual": true, "name": "ICU List", "managingEntity": { "reference": "Organization/example-organization-2", "display": "Dairyland Hospital" }, "member": [{ "entity": { "identifier": { "system": "http://example.org", "value": "456" }, "display": "Name = Daniel Crimson (MRN = 456)", "extension": [{ "url": "http://registry.fhir.org/argonaut/patientlistsquestionnaireresponsev1", "valueReference": { "reference": "http://hapi.fhir.org/baseR4/QuestionnaireResponse/1169472" } }] }, "inactive": false }, { "entity": { "identifier": { "system": "http://example.org", "value": "567" }, "display": "Name = Peter Silie (MRN = 567)", "extension": [{ "url": "http://registry.fhir.org/argonaut/patientlistsquestionnaireresponsev1", "valueReference": { "reference": "http://hapi.fhir.org/baseR4/QuestionnaireResponse/1171740" } }] }, "inactive": false }, { "entity": { "identifier": { "system": "http://example.org", "value": "901" }, "display": "Name = Caleb Cushing (MRN = 901)" "extension": [{ "url": "http://registry.fhir.org/argonaut/patientlistsquestionnaireresponsev1", "valueReference": { "reference": "QuestionnaireResponse/1171741" } }] }, "inactive": false }] } ~~~ Check column definitions by retrieving Questionnaire. `GET http://hapi.fhir.org/baseR4/Questionnaire/1169270` Pulls columnar data for each patient in Group. `GET http://hapi.fhir.org/baseR4/QuestionnaireResponse?_id=1169472,1171740,1171741` Optionally, query other USCDI data for more information about each patient. `GET http://hapi.fhir.org/baseR4/Observation?subject=Patient/456`  ## Definition of Success By the end of 2020, Argonaut publishes an Patient LIst guide that enables an authorized SMART on FHIR client application to access patient lists for the defined use cases - IG implemented in an open-source sandbox + sample data + demo app - IG prototyped by at least two server vendors, tested in September connectathon - IG prototyped by at least two client vendors, tested in September connectathon - IG incorporates feedback from September connectathon - IG considered "implementable" by participating EHR vendors - At least two server vendors propose timeline to beta deployment (i.e., at real sites) - At least two client vendors propose timeline to beta deployment (i.e., at real sites) - Hand off to ? (FHIR-I/US Core/Other HL7 entity for Publishing)

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.