microsoft / graphir

GraphQL interface over FHIR API

Table of Contents

• Introduction
• Getting Started
• Calling Graphir
• How It Works
• Contributing
• Trademarks

Introduction

What?

Graphir is an example lightweight proxy that reshapes GraphQL queries and mutations into standard FHIR REST requests.

This example uses the Azure implementation of FHIR as its backend.

Why?

The FHIR schema encompasses large objects that can be cumbersome to develop client applicatons with. By providing a Graph QL interface over a FHIR API, we hope to accelerate client app development agility.

Getting Started

Requirements

To follow this guide for running locally you will need the following

• dotnet 6.0
• Visual Studio 2022 (Professional or Enterprise)
• Prerequisites API app registration & client App Registration

Running Locally

• Open Solution with Visual Studio
• Right click on the Graphir.API poject and select "Manage User Secrets"
• Add your information from app registrations

{
	"AzureAd": {
    	"Instance": "https://login.microsoftonline.com/", // ???
    	"Domain": "hlshack.onmicrosoft.com", // ???
    	"TenantId": "<add the tenant id from the azure tenant containing your app registrations here>",
    	"ClientId": "<add the client id from your client app registration here>",
    	"ClientSecret": "<add the client secret from your client app registration here>"
  }
}

• Compile
• Run/debug local

Calling Graphir

With Postman

• Install Postman
• Add a new POST request
• Add the URI https://localhost:5001/GraphQL
• Add the body of your request in the "Body" tab e.g.

query patientList {
  PatientList {
    id
    name { given family }
    birthDate
  }
}

• Open up the Authorization tab
• For Type, select 'OAuth 2.0'
• In the Configure New Token section
  • select 'Authorization Code' for Grant Type (*if you have multi-factor enabled, select 'Authorization Code (with PKCE)')
  • Leave 'Authorize with browser' checked
  • Auth URL: https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/authorize
  • Access Token URL: https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token
  • ClientId:
  • Scope:
• Click 'Get New Access Token'

In Banana Cake Pop UI

• You will need to complete the section "With Postman" so that you can generate a valid access token.

How It Works

Application Startup and App Registrations

See Graphir API Authentication and Authorization

Capabilities

Supported FHIR Resources

• Patient
• Practitioner
• Organizations
• Locations
• Appointments
• Schedules
• Medications
• MedicationRequests
• MedicationAdministrations
• HealthcareServices

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Code Quality

1. Style should match our team style
2. Documentation up to date (in code and outside of code docs)
3. Instructions on how to run code updated if new things are added (ex new secrets, new dependencies)
4. Check that there isn't unneeded hardcoding

CI

CI for this project is enabled through GitHub Actions

Community Discord

If you are interested in projects like this or connecting with the health and life sciences developer community, please join our Discord server at https://aka.ms/HLS-Discord. We're a technology agnostic community seeking to share and collaborate on all things related to developing healthcare solutions. For in-depth questions specific to this project, please use the "Discussions" tab on GitHub. We welcome your thoughts and feedback.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

graphir's Issues

Administration Types

Add implementation for:

• Care Team
• Device
• PractitionerRole
• RelatedPerson

Workflow Schema Types

Add implementation for:

• Task
• PlanDefinition

How to figure out the relationship for resolvers

Hi everyone. @pjirsa @mjschanne @i-am-dan @jkarasha @msftgits We are currently working on implementing this project for accessing our Azure FHIR resources via GraphQL. But we are facing issues while finding the relation between resources and figuring out the way to implement the resolvers. If anyone can provide some guidelines on that, we can implement this project internally and are happy to contribute all the code to this project to make it completely usable without any additional hassle

Can we use graphql-mesh?

Is it a good solution to use graphql-mesh https://github.com/Urigo/graphql-mesh over Graphir? Since it provides distributed SDK to interact with the FHIR resources via GraphQL queries and mutations. I find creating resolvers to all the resources seems to be a tedious task. Any suggestions, please

Add Application Insights Instrumentation

Use Instrumentation guidance from HotChocolate to add App Insights logging.

We are trying to access our FHIR resources from Azure

We are trying to access our Azure FHIR resources through Azure AD
Our App registrations details are as follows

Client App Details

Configured API permission

App Role

Although we followed all the instructions on fetching tokens through Postman as mentioned in the documentation, still we are getting the following error message

ResponseBody: {"error":"invalid_grant","error_description":"AADSTS65001: The user or administrator has not consented to use the app
lication with ID '898cba89-b86d-4099-a6c3-6cfe502009b3' named 'GraphirAPI-Dev'. Send an interactive authorization request for this user and
resource.\r\nTrace ID: 4637e900-9b41-414d-b9e4-0c8df37a7a00\r\nCorrelation ID: 0f4d94a6-3fb6-4513-90fc-adfb5cdb98ef\r\nTimestamp: 2022-09-
22 09:00:03Z","error_codes":[65001],"timestamp":"2022-09-22 09:00:03Z","trace_id":"4637e900-9b41-414d-b9e4-0c8df37a7a00","correlation_id":"
0f4d94a6-3fb6-4513-90fc-adfb5cdb98ef","suberror":"consent_required","claims":"{"access_token":{"capolids":{"essential":true,"values
":["98985d48-5ae5-4b44-b117-c476e5d318b6"]}}}"}

Please let us know if anyone faces the same issue or known any solutions

Msal Exception

Line no 26 always runs into Msal exception challenging user.
If I pass the token directly then I'm able to fetch data from FHIR server. Pls help.

Resovers throw exception while reference are null

I am working on resolvers now, I am getting into an issue that when we try to fetch any related resource for a resource reference [with 1:1 cardinality ratio] which does not have any related resource (null) for any particular object, it is throwing an "object set to null reference" exception. I cannot return an empty object as well cos related resource's primary key required a value to be assigned. otherwise, it is throwing an error as "cannot assign a null value for a non-nullable type", any suggestions?

Security & Privacy Schema Types

Add implementation for:

• Consent

URLs for Authorization and Access token are not valid

Auth URL: https://login.microsoftonline.com//oauth2/v2.0/authorize
Access Token URL: https://login.microsoftonline.com//oauth2/v2.0/token

Both these URL`s are not working as expected.

When we have a reference in a resource which can be more than one type of resource...

When we have a reference in a resource which can be more than one type of resource, How we can define the return type in the resolver since we do not know it can be a reference to any type of them

For example, in Appointment Resource, we have a participant field which can be
"Patient", "Practitioner", "PractitionerRole", "RelatedPerson", "Device", "HealthcareService", "Location"

How to define the return type of the resolver in such scenarios?

Could not create a ContactComponent for Organization Resource

When I tried to create a OrganizationContactType I get the following error while trying to fetch the schema

but I don't have any existing types which register Organization.ContactComponent, I have registered Patient.ContactComponent
but that is not the same as Organization.ContactComponent

Organization.ContactComponent

Patient.ContactComponent

Add implementation for `ServiceRequest` FHIR resource

The resolver was unable to cast the parent type to the requested type

 "errors": [
    {
      "message": "The resolver parent type of field `Patient.name` is `System.Collections.Generic.KeyValuePair`2[System.String,System.Object]` but the resolver requested the type `Hl7.Fhir.Model.Patient`. The resolver was unable to cast the parent type to the requested type.",
      "path": [
        "Patient",
        0,
        "name"
      ],
      "extensions": {
        "field": "Patient.name",
        "code": "HC0053"
      }
    },

Sample Query Tried

query patientList {
   Patient(id:"67cbf090-4ddb-4799-99ff-a28abe2740b1"){
     name{
       given
       family
      }
     }
   }

Tested on this URL resource https://r4.smarthealthit.org

Data fetching to the data loader without any issues

Do we have to make any modifications to the resolver?

@pjirsa @i-am-dan @jkarasha @msftgits @mjschanne Please help Thank you

Unable to cast object of type 'Hl7.Fhir.Model.OperationOutcome' to type 'Hl7.Fhir.Model.Patient'

It works with default Hapi fhir configuration. The moment when we changed it to use Azure FhirService, we were getting this error. This used to work before.

bundle.Entry was having an additional operation outcome entry along with Patients List. This was the same for all the resources, not just the patient.

query {
PatientList {
id
}
}

"message": "Unable to cast object of type 'Hl7.Fhir.Model.OperationOutcome' to type 'Hl7.Fhir.Model.Patient'.",
"stackTrace": " at Graphir.API.Services.FhirJsonClient.<>c__41.<SearchAsync>b__4_0(EntryComponent p) in C:\\Users\\rvenugopal\\develop\\azure\\Graphir\\Graphir.API\\Services\\FhirJsonClient.cs:line 32\r\n at System.Linq.Enumerable.SelectListIterator2.ToList()\r\n at System.Linq.Enumerable.ToList[TSource](IEnumerable1 source)\r\n at Graphir.API.Services.FhirJsonClient.SearchAsync[T](String query) in C:\\Users\\rvenugopal\\develop\\azure\\Graphir\\Graphir.API\\Services\\FhirJsonClient.cs:line 0\r\n at Graphir.API.Services.FhirJsonClient.SearchAsync[T](IList1 criteria) in C:\Users\rvenugopal\develop\azure\Graphir\Graphir.API\Services\FhirJsonClient.cs:line 38\r\n at Graphir.API.DataLoaders.PatientResolvers.GetPatientListResources(FhirJsonClient client, String family, String given, DateTime birthDate, String generalPractitioner) in C:\Users\rvenugopal\develop\azure\Graphir\Graphir.API\DataLoaders\PatientResolvers.cs:line 30\r\n at HotChocolate.Resolvers.Expressions.ExpressionHelper.AwaitTaskHelper[T](Task`1 task)\r\n at HotChocolate.Types.Helpers.FieldMiddlewareCompiler.<>c__DisplayClass9_0.<b__0>d.MoveNext()\r\n--- End of stack trace from previous location ---\r\n at HotChocolate.Execution.Processing.Tasks.ResolverTask.ExecuteResolverPipelineAsync(CancellationToken cancellationToken)\r\n at HotChocolate.Executi

on.Processing.Tasks.ResolverTask.TryExecuteAsync(CancellationToken cancellationToken)"

Diagnostics Schema Types

Add implementation for:

• Observation

With Postman

1. What value should the client Id and Scope be while calling the graphir from Postman.
2. Even after receiving the token with the user details from Azure AD; there is still Msal exception being thrown while triggering the request from the Banana POP Ui with valid token values.

Add implementation for `Task` FHIR resource

General Practitioner Resolvers are not working

I could not fetch any practitioner details related to Patient resources. Any solutions? @pjirsa

Clinical Schema Types

Add implementation for:

• CarePlan
• Goal
• Condition