Page tree
Skip to end of metadata
Go to start of metadata

Short Description

One of the 2020 Argonaut projects is Patient Lists, which enables a standardized way for software to access lists of patients which are commonly used in an EHR setting. For example, "all patients in a location" or "all the patients on my schedule today."

This track will cover some foundational, early-design operations such as list discovery, selecting list member records, and selection of "extra" patient data using various methods.

Long Description

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.

Some project goals that will be addressed (and hopefully clarified with this connectathon experience):

  • Supporting interoperable and standard exchange of existing EHR supported “user-facing lists”.
    1. user-facing lists include both “system-maintained” and “user-maintained”(which are entirely ad-hoc - the user explicitly selects and manages members) lists
  • Defining 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. Discover user-facing lists including searching on existing lists using limited set of predefined characteristics such as location or careteam. 
    2. Fetch the List, allowing apps to enumerate members of a user-facing lists
    3. Provide a framework to convey extra details about the members of a lists

EHR vendors and third party software vendors wishing to use this new API are welcome to participate in this track.

Summary from our September Connectathon


Powerpoint Describing our Project

Agenda

Date

Time

Topic

1/14/2021

10:00 AM ET

Track Kick Off


10:30 AM ET

New to Patient Lists: Get up to speed


11:00 AM ET

Demo of Test Client Apps


2:00 PM ETPL  Servers Review

1/15/2021




10:00 AM ET

Check-in


11:00 AM ET

Q/QR Extension Review


11:30 AM ETEncounter/Appointment Extension Review

12:30 AM ET

Connectathon 26 Track Highlights Presentation


2:00 PM ET

Track Final Discussion (optional review of Big lists)

TRACK SUMMARY SLIDES

Type

Test the design of a Resource/set of Resources

Submitting Work Group/Project/Accelerator/Affiliate/Implementer Group  

Proposed Track Lead

Carl Anderson, carl.anderson@microsoft.com

Eric Haas ehaas@healthedatainc.com

Related Tracks

FHIR Version

FHIR R4

Specification(s) this track uses

Argonaut Patient List Project

NOTE that links to the appropriate sections are provided in the track details below.

meeting notes

Most of the relevant work and examples is present in the  demo apps listed below

Artifacts of focus

Clinical input requested (if any)

We're running with a handful of example patient lists, such as "all the patients in a location" and "all the patients a provider will see in a day / week" - but if there are other more relevant lists, suggestions from clinicians are welcome.

Patient input requested (if any)

Same as above - if there are any well established places where lists of patients are frequently used or useful, patient/caretaker input is welcome.

Expected participants

Please fill out this preconnectathon Patient-List Survey

signup spreadsheet : contact info urls and authorization instructions

Server Implementers:

  • Epic
  • Cerner
  • Meditech
  • Allscripts?
  • MIcrosoft


Client Implementers:

  • Apple
  • Epic?
  • PeraHealth?
  • MIcrosoft (Demo client application)
  • Health eData Inc (Demo client application)

Zulip stream

https://chat.fhir.org/#narrow/stream/227046-Argo-Patient.20Lists

TBD

Track Orientation Date

Wed  Dec 16th 1PM Eastern (10 Pacific)   Link to September track orientation

Track Orientation Details

Track Details

System Roles

  1. Server implementers (EHR vendors):  Source of User-Facing lists: Provide Group resource endpoints for discovering what lists are available and fetching lists
  2. Clients (third-party software vendors): Application to discover what User-facing lists are available and fetching lists for display, processing etc.

FHIR Artifact Formal Definitions:

https://argonautproject.github.io/patient-lists/index.html

Note that the canonical base url for all patient list artifacts is: http://www.fhir.org/guides/argonaut/patient-list

Sample Data:

  1. FHIR Transaction Bundle of sample data used for this Connectathon (meta tag = 2021-Jan)
    and have been loaded onto the UHN HAPI Server: ( click on image to download )


          

These Bundles include all the extensions, references and resources for the following resource types listed below to cover all the scenarios described below.

- 'Patient'
- 'Practitioner'
- 'Organization'
- 'Location'
- 'Coverage'
- 'Appointment'
- 'Questionnaire'
- 'QuestionnaireResponse'
- 'Group'

  1. A dockerized HAPI server will be provided that is populated with a canonical set of Synthea-generated FHIR data.  This server image, and the scripts used to generate it, will be made available both to server implementers and third party vendors for testing purposes prior to the connectathon.  Instructions will be provided in github and in the introductory video.  
  2. A script will also be made available that can generate the Synthea data and load it into an empty server, which will be useful for the server implementer participants.  Instructions to BYOS (bring your own server) will be made available.

demo apps: 

  1. https://aka.ms/patient-lists-demo.
  2. Codelab exercise which walks through some of the implementation of the demo app: https://aka.ms/patient-lists-codelab
  3. Argo Patient List Client (http://www.healthedata1.co/) is an interactive app that walks through all the following scenarios to demonstrate the use using sample data

Scenarios

Workflow Outline

1 - Patient List Discovery: https://hackmd.io/2Rs6Y0hQSMGdt3kImASuZg?view

1.1 - Basic Discovery: GET all User Facing Lists

A server is able to produce a list of the available Patient Lists known.  A client is able to render a list of known Patient Lists.

Action: A client issues a GET request to a server:

        GET Group?_summary=true&type=person

Server Success Criteria

The server responds with a complete Bundle of the available Group entries with type person.

Client Success Criteria

The list of lists is processed, e.g., displayed in HTML.

Example in Postman

1.2 - Organization-Managed Lists: 

A server is able to provide a collection of patient lists that are managed by a particular organization.  A client is able to query for lists, specifying the managing Organization in the request.

Action: A client issues a GET request to a server:

        GET Group?_summary=true&type=person&managingEntity=Organization/42

Server Success Criteria

The server responds with a Bundle of Group entries where each entry is managed by an Organization with an ID of '42'.

Client Success Criteria

The client provides a selector listing available Organizations.  When selected, a query returns the patient lists that are managed by the selected Organization.

Example in Postman

1.3 - Discovery by Characteristic

A server is able to provide a collection of patient lists that all have a common characteristic.  A client is able to query for lists, specifying one of the following characteristic parameters in the request:


  • The following table summarizes the combinations of search parameters to search by patient list characteristic:

characteristiccodevalue-referencereference
characteristiclocationvalue-referenceLocation/[location_id]
characteristicpractitionervalue-referencePractitioner/[practitioner_id]
characteristicorganizationvalue-referenceOrganization/[organization_id]
characteristiccareteamvalue-referenceCareTeam/[careteam_id]

  • value-reference is a custom SearchParameter formally defined here. It is not implemented in the public test servers.

Action: A client issues a GET request to a server: 


        GET Group?_summary=true&type=person&characteristic=[Code value]&characteristic-reference=[Value value]

Server Success Criteria

The server responds with a Bundle of Group entries where each entry has the same characterisic code/value pair  (e.g.,  location=Location/[location_id])

Client Success Criteria

The client provides a selector listing above characteristic name-value pairs.  When selected, a query returns the patient lists that are managed by the selected Organization.

Example in Postman 


2 - Fetching User Facing Patient List Members: https://hackmd.io/tBVF57gERz-REm3_QkWtCg?view

Fetch a Group containing a list a Patient who are members of the Group.  A server returns a Group resource which contains references to patients.


Action: A client issues a GET request to a server:

        GET Group/123

Server Success Criteria

The server responds with a Group resource with ID '123'.

Client Success Criteria

The client queries for a particular list of patients and processes them e.g., displayed in HTML as a list of ids.

Example in Postman 


3 - Getting Extra Details about the patients: https://hackmd.io/ux8TD8LUTpifVq4g0N7LnA?view 


3.1 - Patient Lists - Extra Details via Base FHIR RESTful API Search : https://hackmd.io/ux8TD8LUTpifVq4g0N7LnA#Patient-Based-FHIR-RESTful-Queries?view 
#Patient-Based-FHIR-RESTful-Queries

The Simplest approach for the client to do a series of queries on the Server to Fetch additional data:

When requested, a server can provides patient details for each for each of the members in the Group resource via a series of FHIR RESTful queries for other resources about that patient as described in the base specification and US Core.  

Action: A client issues a GET request, fetching a Group resource.  Then, for each Group.member (aka patient), and Patient resource and a Observation attribute (the most recent lab result) is requested, which is not directly part of the patient resource.

for example:

GET Group/123
for each patientRef in Group.member:
GET Patient/ID
GET Observation/$lastn?patient=Patient/ID&category=laboratory
etc...

Server Success Criteria

The server responds with a search Bundle for each query. 

Client Success Criteria

The request bundle is properly prepared.  All fetched 'extra details' are then also processes them e.g.,displayed in HTML.

Example in Postman 


Bonus 1) Some queries can be combined using the OR search parameter to reduce the number of Client queries.

for example:

GET Patient?_id=ID1,ID2,ID3,...
GET Observation/$lastn?patient=ID1,ID2,ID3,...&category=laboratory

Server Success Criteria

The server responds with a search Bundle for each query. 

Client Success Criteria

The request bundle is properly prepared. All fetched 'extra details' are then also processes them, e.g., displayed in HTML.

Note that US Core does not require servers to support multipleOr for these queries.


Bonus 2) These queries can be done separately as described above or as a single batch interaction

for example:

       POST [base]
{
  "resourceType": "Bundle",
  "id": "bundle-request-groupdetails",
  "type": "batch",
  "entry": [
    {
      "request": {
        "method": "GET",
        "url": "Patient/123"
      }
    },
    {
      "request": {
        "method": "GET",
        "url": "/Observation/$lastn?patient=Patient/123&category=laboratory"
      }
    },
    {
      "request": {
        "method": "GET",
        "url": "Patient/456"
      }
    },
    {
      "request": {
        "method": "GET",
        "url": "/Observation/$lastn?patient=Patient/456&category=laboratory"
      }
    },
    ...
  ]
}

Server Success Criteria

The server SHALL return a Bundle with type set to batch-response that contains the request resource for each entry in the  batch request, in the same order, with the outcome of processing the entry. 

Client Success Criteria

The request bundle is properly prepared.  All fetched 'extra details' are then also processes them, e.g., displayed in HTML.

3.2 - Using _include: https://hackmd.io/tBVF57gERz-REm3_QkWtCg#Using-Includes?view

Support _include for Group so that the Patient resource attributes such as Name, Age, DOB, Gender, Height, Weight, etc can be fetched in a single interaction (this is functionally akin to using the `_list` parameter)

GET [base]/Group/1234?_include=Group:member

Server Success Criteria

The server responds with a complete Bundle of Patient entries, all members of the requested Group with ID '123' AND a Patient resource for each Group.member.

Client Success Criteria

The client queries for a particular list of patients and processes them e.g.,displayed in HTML as a table of patient resource attributes such as Name, Age, DOB, Gender, MRN, Contact info.

Example in Postman 


3.3 - Patient Lists - Extra Details via Questionnaire: https://hackmd.io/ux8TD8LUTpifVq4g0N7LnA#Fetching-Additional-Data-Using-QuestionnaireQuestionnaireResponse?view 

  The Server can elect to define a set of data to accompany a patient list and supply this definition as a Questionnaire. The corresponding data for each patient in the patient list is represented using QuestionnaireResponse and is prepopulated by the ServerThe Argonaut Patient List (Group) Profile supports 2 extension for directly accessing the Group level Questionnaire and the resultant pre-filled QuestionnaireResponse form for each patient on the patient list:

STEP 1:    GET Group/123   with Extensions

Server Success Criteria

The server responds with a  Group resource with ID '123' that has  two extensions: a Questionnaire resource and a QuestionnaireResponse resource for each patient. 

Client Success Criteria

The request bundle is properly prepared.    The Client extracts the reference from the QuestionnaireResponse extension.

 STEP 2 for each patient in Group/123.bundle.entry:

     GET QuestionnaireResponse/[QuestionnaireResponse resource id from Group.member.entity.extension]

Server Success Criteria

The server responds with  a QuestionnaireResponse resources for  containing the requested patient data 

Client Success Criteria

The request bundle is properly prepared.  The Client extracts the extra patient details from the QuestionnaireResponse resources and processes them e.g., populates a table for display.

Example in Postman 


NEW Bonus:   Include Q with QR
    GET QuestionnaireResponse?_id=[QuestionnaireResponse resource id from Group.member.entity.extension]&_include=QuestionnaireResponse:questionnaire
NEW Bonus:   Get all QR for group.member list

 a )  based on Q url

      GET QuestionnaireResponse?questionnaire=[Questionnaire url from Group.extension]

 b)  based on multipleORs or Transaction Bundle

Discussion

1. Discovery of the appropriate questionnaire for a group or particular context.


3.4 - NEW Patient Lists -Fetching Additional Data for Encounter and Appointmenthttps://hackmd.io/ux8TD8LUTpifVq4g0N7LnA#Fetching-Additional-Data-for-Encounter-and-Appointment?view 

When the patient membership on a patient list is defined by a particular encounter or particular appointment, it may be slow or inefficient for the Client to find them using a simple patient based FHIR query. The Argonaut Patient List (Group) Profile supports 2 extension on the Group.member element for directly accessing an Appointment or Encounter for each patient on the patient list:

  STEP 1   GET Group/123      

Server Success Criteria

The server responds with a  Group resource with ID '123' that has one or both Appointment or Encounter extensions for each patient. 

Client Success Criteria

The request bundle is properly prepared.    The Client extracts the reference from the Appointment and/or Encounter extension.

  STEP 2 for each patient in Group/123.bundle.entry get Appointment/Encounter

GET Appointment/[Appointment resource id from Group.member.entity.extension]
   GET Encounter/[Encounter resource id from Group.member.entity.extension]

Server Success Criteria

The server responds with an Encounter or Appointment resource.

Client Success Criteria

The Client extracts the extra patient details from the resource and processes them e.g., populates a table for display.

Example in Postman 


NEW 4.0 Large list (considerations)

When does this process become async and when should bulk data be considered.

Paging - see these recommendations:  https://hackmd.io/tBVF57gERz-REm3_QkWtCg?view

  • The Server SHOULD NOT return first-page results as described here

  • The Server SHOULD return an OperationOutcome indicating that the client needs to call the $getpage operation to return a Group with just the specified subset of its members (offset 0 based, default to 0). This operation uses the following Syntax:

    GET [Base]Group/[id]/$getPage?offset=X&count=Y

Review Da Vinci Membership Attribution specification: http://build.fhir.org/ig/HL7/davinci-atr/spec.html

  • Discovery by identifier
  • Get extra data using the bulk data $export + _type parameters

TestScript(s)

A demo app is provided here: https://microsoft-healthcare-madison.github.io/patient-lists-demo/

The source for the demo lives here: https://github.com/microsoft-healthcare-madison/patient-lists-demo

Instructions for generating and loading sample data can be found in the demo app's README.

Security and Privacy Considerations

Refer to the SMART Launch IG