Making use of extension methods to extract data from FHIR bundles

This article shows some extension methods to extract data from FHIR bundles, where FHIR stands for Fast Healthcare Interoperability Resources. The standard is used as a global or country specific standard with its own
variants. It is also a standard that allows for extensibility and its goal is to define interoperability and an information model definining resources which are then comprised of smaller elements which can define different kinds of information.
FHIR also defines API standards and is defined in different formats such as XML and json. We will look into some example extension methods for retrieving data deep inside a FHIR Bundle. A bundle is a top level data which got a lot of components in a hierarchical structure as we define the data in XML or JSON for example, i.e. a tree structure. Let us say that we want to retrieve data like medications a pasient is taking as his or her DDD (Defined Daily Dosage). We want to be able to find a medication statement inside our bundle and then retrieve the medication dosage quantity. We know the unit is measured in micrograms (ug) and the medication (drug) is called Fentanyl. Here is a property getter with logic to retrieve this value.

 
   public int? Fentanyl
   {
            get
            {
                var dosageQuantity = _bundle.SearchMedicationStatements("http://someacme.no/fhir/MedicationStatement/")
                    ?.GetMedicationDosageQuantity("Fentanyl", "ug");
                //value is already a decimal? data type and must be parsed 
                if (int.TryParse(dosageQuantity?.Value?.ToString(), out var dosageQuantityParsed))
                {
                    return dosageQuantityParsed;
                }
                return null;
            }
    }
 

We have these two extension methods to help us with retrieving the data :

 
      
        public static List<MedicationStatement>? SearchMedicationStatements(this Bundle bundle, string resourcePath)
        {
            var medicationStatementsMatching = bundle?.Entry?.Where(e => e.FullUrl.StartsWith(resourcePath))?.Select(m => m.Resource)?.OfType<MedicationStatement>()?.ToList();
            return medicationStatementsMatching;
        }

        public static Dosage? GetMedicationDosageDosage(this List<MedicationStatement> medicationStatements, string displayText)
        {
            //find dosage with given display text 

            foreach (var medicationStatement in medicationStatements)
            {
                var medicationStatementMedication = medicationStatement?.Medication as CodeableConcept; 
                if (medicationStatementMedication == null)
                {
                    continue; 
                }
                var medicationCoding = medicationStatementMedication?.Coding?.FirstOrDefault(med => med.Display?.Equals(displayText, StringComparison.InvariantCultureIgnoreCase) == true);  
                if (medicationCoding != null)
                {
                    var quantity = medicationStatement?.Dosage?.FirstOrDefault();
                    return quantity; 
                }           
            }

            return null;
        }
 
 

And our unit test will then be very simply with some static Fhir bundle data like this :

 
 
    [TestFixture]
    public class SomeAcmeManagerTests
    {
        private Bundle? _bundle = new();
        private SomeAcmeColoscopyDomainModel? _domainModel;

        [SetUp]
        public void TestInitialize()
        {
            _bundle = new FhirJsonParser().Parse<Bundle>(File.ReadAllText(@"TestData/JSON_someacme.json"));
            _domainModel = new SomeAcmeColoscopyDomainModel(_bundle, _metadataVersionId);
        }
 
        [Test]
        public void Map_Fhir_Bundle_To_Property_Fentanyl()
        {
            _domainModel?.Fentanyl.Should().Be(2);
        }
 

Now, we have used some classes here as you have seen called FhirJsonParser and MedicationStatements. These classes and functionality is available in some selected nuget packages :

 
  <PackageReference Include="Hl7.Fhir.R4" Version="4.0.0" />
  <PackageReference Include="Hl7.Fhir.Serialization" Version="4.0.0" />
  <PackageReference Include="Hl7.Fhir.Support" Version="4.0.0" />
  <PackageReference Include="Hl7.Fhir.Support.Poco" Version="4.0.0" />
 

This packages are licensed under BSD-3 license and are 'free' as long as you include the copyright notice. See this url for more info - it is the HL7 FHIR SDK for Microsoft .net platform. As you see we have additional nuget packages for (de)serialization and Poco objects. We also have common interfaces and classes in the HL7.Fhir.Support and HL7.Fhir.Poco nuget packages. This makes it way easier to work with a large bundle of Fhir data. Now, about sample data - this is often given in a .json file by the for example another organization, that you want to integrate with. FHIR is about interoperability and a common understanding of different health information systems via a common standard. The sample data starts with these data at the top - a bundle and a diagnosticreport. Of course, FHIR is a very large standard and which data you work against will vary a lot.

 
 {
  "resourceType": "Bundle",
  "meta": {
    "profile": [
      "http://someacmeregistries.no/fhir/StructureDefinition/colonoscopyreport-bundle-someacme"
    ]
  },
  "identifier": {
    "system": "http://someacmeotherorg.no/fhir/NamingSystem/colonoscopy-report-id",
    "value": "IdPlaceholder"
  },
  "type": "collection",
  "timestamp": "2022-05-10T10:26:40.6221425+02:00",
  "entry": [
    {
      "fullUrl": "http://somethirdacme.no/fhir/DiagnosticReport/c83b2f53-2d01-46e7-aed4-703396d5433f",
      "resource": {
        "resourceType": "DiagnosticReport",
        "meta": {
          "profile": [
            "http://someacmeregistries.no/fhir/StructureDefinition/colonoscopyreport-diagnosticreport-gastronet"
          ]
        },
        "status": "final",
        "code": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "73761001",
              "display": "Koloskopi"
            }
          ]
        },
        "subject": {
          "reference": "http://someacme.no/fhir/Patient/84c51e6c-020c-469b-b6c8-a6e9b2db6ff6"
        },
 
 

As you can see we also have something called Snomed SCT codes in our data. The meaning of these codes can be looked up online. International edition is here: https://browser.ihtsdotools.org/? Our medication drug statment for Fentanyl is defined further into the FHIR json bundle.

    {
      "fullUrl": "http://someacme.no/fhir/MedicationStatement/ae48d3bf-c289-4290-b7ed-78ef7bb6f1b5",
      "resource": {
        "resourceType": "MedicationStatement",
        "meta": {
          "profile": [
            "http://someame.no/fhir/StructureDefinition/colonoscopyreport-medicationstatement-gastronet"
          ]
        },
        "partOf": [
          {
            "reference": "http://someacme.no/fhir/Procedure/14f9f2e3-0d53-46c9-936f-3f0f85dd8cce"
          }
        ],
        "status": "active",
        "medicationCodeableConcept": {
          "coding": [
            {
              "system": "http://snomed.info/sct",
              "code": "373492002",
              "display": "Fentanyl"
            }
          ]
        },
        "subject": {
          "reference": "http://someacme.no/fhir/Patient/84c51e6c-020c-469b-b6c8-a6e9b2db6ff6"
        },
        "dosage": [
          {
            "doseAndRate": [
              {
                "doseQuantity": {
                  "value": 2,
                  "unit": "ug",
                  "system": "http://unitsofmeasure.org",
                  "code": "ug"
                }
              }
            ]
          }
        ]
      }
    },

As you can see, a FHIR json bundle will be quite lengthy and my sample file, which is a sample diagnostic report for coloscopy is right above 1000 lines and 33 kilobytes. To retrieve the medication dosage we need to go deep into the FHIR json structure sometimes and sometimes look at sibling nodes or further down. What helped me a lot while creating the extension methods I will mention next, was debugging and looking into the immediate window and inspect which kind of Entry it is. An Entry is a generic term which describes that our component is a general term in FHIR which can be many different types, such as a MedicationStatment and contain a Codable concept which ultimately will contain the dose and quantity of our medication (drug). What I did was the following to make working with the FHIR bundle in a more code friendly manner :

GENERIC APPROACH - Implement a mapping from a FHIR bundle into a DOMAIN MODEL which then can be used in your SYSTEM

• Use the debugger and unit tests and explore in the immediate window which kind of Entry each component in the FHIR bundle is. Identity if we can cast an Entry into a correct subtype, such as a MedicationStatement. These POCO objects are available in the noted nuget packages above.
• After finding a way to retrieve the data - generalize the retrival into extension methods, which can be chained and then make use of these extension methods into property getter logic.
• Use a TDD approach to retrieve the data. Each property was found in the sample doc for me (about 100 properties) and I was trying to find generic ways to find these property values
• Sometimes you need fine tuned logic too to find data. FHIR contains some extensions and different FHIR bundles, although it is a standard, may vary some.

Okay, here is all the extension methods I made for this case. I have masked the real organization names here. My approach can be used in many different scenarios for retrieving FHIR bundle data.

 
 
 
using Hl7.Fhir.Model;
using static Hl7.Fhir.Model.Observation;

namespace SomeAcme.FhirFacade.SomeProduct.HelperMethods
{

    /// <summary>
    /// Helper methods for Fhir bundle. Generic use helper methods.  
    /// </summary>
    public static class FhirHelperExtensions
    {


        public static string? SearchForPractitioner(this Bundle bundle, string procedurePath, string functionRole)
        {
            var performer = bundle.SearchForProcedure(procedurePath)?
                .Performer?.FirstOrDefault(p => p?.Function?.Coding?.FirstOrDefault()?.Display?.Equals(functionRole, StringComparison.InvariantCultureIgnoreCase) == true);
            return performer?.Function?.Coding?.FirstOrDefault()?.Code;
        }

        /// <summary>
        /// Looks up an identifier value (e.g. hpr number or similar) of practitioner
        /// </summary>
        /// <param name="practitioner"></param>
        /// <returns></returns>
        public static string? GetPractitionerIdentifierValue(this Practitioner practitioner)
        {
            return practitioner?.Identifier?.FirstOrDefault()?.Value; 
        }

        public static Organization? SearchForOrganization(this Bundle bundle, string resourcePath, bool startsWith = true)
        {
            if (startsWith)
            {
                var organizationMatching = bundle?.Entry.FirstOrDefault(e => e.FullUrl.StartsWith(resourcePath))?.Resource as Organization;
                return organizationMatching;
            }

            var organization = bundle?.FindEntry(resourcePath).FirstOrDefault()?.Resource as Organization;
            return organization; 
        }

        public static MedicationStatement? SearchMedicationStatement(this Bundle bundle, string resourcePath, bool startsWith = true)
        {
            if (startsWith)
            {
                var medicationStatementMatching = bundle?.Entry.FirstOrDefault(e => e.FullUrl.StartsWith(resourcePath))?.Resource as MedicationStatement;
                return medicationStatementMatching;
            }

            var medicationStatement = bundle?.FindEntry(resourcePath).FirstOrDefault()?.Resource as MedicationStatement;
            return medicationStatement;
        }

        public static List<MedicationStatement>? SearchMedicationStatements(this Bundle bundle, string resourcePath)
        {
            var medicationStatementsMatching = bundle?.Entry?.Where(e => e.FullUrl.StartsWith(resourcePath))?.Select(m => m.Resource)?.OfType<MedicationStatement>()?.ToList();
            return medicationStatementsMatching;
        }

        public static Dosage? GetMedicationDosageDosage(this List<MedicationStatement> medicationStatements, string displayText)
        {
            //find dosage with given display text 

            foreach (var medicationStatement in medicationStatements)
            {
                var medicationStatementMedication = medicationStatement?.Medication as CodeableConcept; 
                if (medicationStatementMedication == null)
                {
                    continue; 
                }
                var medicationCoding = medicationStatementMedication?.Coding?.FirstOrDefault(med => med.Display?.Equals(displayText, StringComparison.InvariantCultureIgnoreCase) == true);  
                if (medicationCoding != null)
                {
                    var quantity = medicationStatement?.Dosage?.FirstOrDefault();
                    return quantity; 
                }           
            }

            return null;
        }

        public static Quantity? GetMedicationDosageQuantity(this List<MedicationStatement> medicationStatements, string displayText, string? expectedUnitname = null)
        {
            //find quantity for dosage with given display text 

            foreach (var medicationStatement in medicationStatements)
            {
                var medicationStatementMedication = medicationStatement?.Medication as CodeableConcept;
                if (medicationStatementMedication == null)
                {
                    continue;
                }
                var medicationCoding = medicationStatementMedication?.Coding?.FirstOrDefault(med => med.Display?.Equals(displayText, StringComparison.InvariantCultureIgnoreCase) == true);
                if (medicationCoding != null)
                {
                    if (medicationStatement?.Dosage?.FirstOrDefault()?.DoseAndRate?.FirstOrDefault()?.Dose is Quantity quantity)
                    {
                        if (!string.IsNullOrWhiteSpace(expectedUnitname) && expectedUnitname.Equals(expectedUnitname, StringComparison.InvariantCultureIgnoreCase))
                        {
                            return quantity; 
                        }
                        return null; //found the right dosage - but the unit name does not agree 

                    }
                }
            }
            return null; 
        }


        public static string? GetOrganizationIdentifierValue(this Organization organization)
        {
            return organization?.Identifier?.FirstOrDefault()?.Value;   
        }

        public static Observation? SearchForObservation(this Bundle bundle, string resourcePath, bool startsWith = true)
        {
            if (startsWith)
            {
                var observationMatching = bundle?.Entry?.FirstOrDefault(e => e.FullUrl.StartsWith(resourcePath))?.Resource as Observation;
                return observationMatching;
            }

            var observation = bundle?.FindEntry(resourcePath).FirstOrDefault()?.Resource as Observation;
            return observation;
        }
     
        public static ComponentComponent? GetObservationComponent(this Observation observation, string observationComponentDisplayText)
        {
            //TODO : these observations is not the same as the observation in SomeProduct and must be additionally mapped (enums does not agree) 
            foreach (var observationComponent in observation.Component)
            {
                if (observationComponent?.Code?.Coding?.Any() != true)
                {
                    continue;
                }
                foreach (var observationEntry in observationComponent.Code.Coding)
                {
                    if (observationEntry?.Display.Contains(observationComponentDisplayText, StringComparison.InvariantCultureIgnoreCase) == true)
                    {
                        return observationComponent;
                    }
                }
            }
            return null;
        }

        public static string? GetObservationComponentCodeValue(this Observation observation, string observationComponentDisplayText)
        {
            //TODO : these observations is not the same as the observation in Gastronet and must be additionally mapped (enums does not agree) 
            foreach (var observationComponent in observation.Component)
            {
                if (observationComponent?.Code?.Coding?.Any() != true)
                {
                    continue; 
                }
                foreach (var observationEntry in observationComponent.Code.Coding)
                {
                    if (observationEntry?.Display.Contains(observationComponentDisplayText, StringComparison.InvariantCultureIgnoreCase) == true)
                    {
                        return observationEntry?.Code; 
                    }
                }                
            }

            return null; 
        }

        public static Patient? SearchForPatient(this Bundle bundle, string resourcePath, bool startsWith = true)
        {
            if (startsWith)
            {
                var patientMatching = bundle?.Entry?.FirstOrDefault(e => e.FullUrl.StartsWith(resourcePath))?.Resource as Patient;
                return patientMatching;
            }
            var patient = bundle?.FindEntry(resourcePath).FirstOrDefault()?.Resource as Patient;
            return patient;
        }

        public static CodeableConcept? SearchForProcedureReason(this Procedure procedure, string code)
        {
            return procedure?.ReasonCode?.FirstOrDefault(c => c?.Coding?.FirstOrDefault()?.Code?.Equals(code, StringComparison.InvariantCultureIgnoreCase) == true);
        }

        public static CodeableConcept? SearchForProcedureReasonViaDisplay(this Procedure procedure, string display)
        {
            return procedure?.ReasonCode?.FirstOrDefault(c => c?.Coding?.FirstOrDefault()?.Display?.Equals(display, StringComparison.InvariantCultureIgnoreCase) == true);
        }

        public static Procedure? SearchForProcedure(this Bundle bundle, string resourcePath, bool startsWithMatching = true)
        {
            if (startsWithMatching)
            {
                var procedureMatching = bundle?.Entry.FirstOrDefault(e => e.FullUrl.StartsWith(resourcePath))?.Resource as Procedure;
                return procedureMatching;
            }
            var procedure = bundle?.FindEntry(resourcePath).FirstOrDefault()?.Resource as Procedure;
            return procedure;
        }

        public static bool SearchForProcedureComplication(this Bundle bundle, string resourcePath, string displayText)
        {
            var procedure = SearchForProcedure(bundle, resourcePath); 
            if (procedure?.Complication?.Any() == true)
            {
                var complications = procedure.Complication.ToList();
                var complicationMatching = complications.FirstOrDefault(x => x.Coding?.FirstOrDefault()?.Display?.ToLower() == displayText);
                //TODO : consider complicaitonCode here or just mere precense ? Ask Kreftreg ? string complicationCode = complicationMatching?.Coding?.FirstOrDefault()?.Code;
                //Other developer confirmed checking mere precense is okay. going for this then.
                return complicationMatching != null;
            }
            return false; 
        }

        public static Quantity? GetObservationQuantity(this Observation observation)
        {
            var quantity = observation?.Value as Quantity;
            return quantity;             
        }

        public static DiagnosticReport? SearchForDiagnosis(this Bundle bundle, string resourcePath, bool startsWithMatching = true)
        {
            if (startsWithMatching)
            {
                var diagnosisMatching = bundle?.Entry.FirstOrDefault(e => e.FullUrl.StartsWith(resourcePath))?.Resource as DiagnosticReport;
                return diagnosisMatching;

            }
            var diagnosticReport = bundle?.FindEntry(resourcePath).FirstOrDefault()?.Resource as DiagnosticReport;
            return diagnosticReport;
        }

        public static string? GetDiagnosticProcedureCode(this DiagnosticReport diagnosticReport, int nthProcedureCode)
        {
            var codes = diagnosticReport?.Code?.Coding?.ToList();
            if (codes == null || !codes.Any() || codes.Count < nthProcedureCode+1)
            {
                return null;
            }
            var coding = codes.ElementAt(nthProcedureCode) as Coding;
            return coding.Display;
        }

        public static string? GetDiagnosisCode(this DiagnosticReport diagnostic, int position)
        {
            var diagnoses = diagnostic?.ConclusionCode?.ToList();
            if (diagnoses == null)
            {
                return null; 
            }
            if (diagnoses?.Count -1 >= position)
            {
                try
                {
                    return $"{diagnoses![position]?.Coding?.First().Code} {diagnoses[position]?.Coding.First().Display}";
                }
                catch { return null; }
            }
            return null;         
        }

        public static Extension? SearchForExtensionInsideProcedure(this Procedure procedure, string extensionUrl)
        {
            var extension = procedure?.Extension?.FirstOrDefault(e => e?.Url == extensionUrl) as Extension;
            return extension; 
        }

        public static List<Extension>? SearchForExtensionsInsideProcedure(this Procedure procedure, string extensionUrl)
        {
            var extensions = procedure?.Extension?.Where(e => e?.Url == extensionUrl)?.ToList();
            return extensions;
        }

        public static CodeableConcept? GetCodeableConceptInsideExtension(this Extension extension)
        {
            if (extension?.Value == null)
            {
                return null; 
            }
            var codeableConcept = extension?.Value as CodeableConcept;
            return codeableConcept;            
        }

        public static Extension? SearchForSubExtensionInsideExtension(this Extension extension, string extensionUrl)
        {
            var subExtension = extension?.Extension?.FirstOrDefault(e => e?.Url == extensionUrl);
            return subExtension;
        }

        public static Duration? GetExtensionDuration(this Extension extension)
        {
            var duration = extension?.Value as Duration;
            return duration; 
        }

        public static FhirBoolean? GetExtensionBoolean(this Extension extension)
        {
            return extension?.Value as FhirBoolean;
        }

        public static Coding? GetExtensionCodeValue(this Extension extension, string url, string system)
        {
            var subExtension = extension?.Extension?.FirstOrDefault(e => e?.Url == url) as Extension;
            var codeContainer = subExtension?.Value as CodeableConcept;
            return codeContainer?.Coding?.FirstOrDefault(c => c.System == system); 
        }      

        public static string? GetPatientIdentifier(this Patient patient)
        {
            return patient?.Identifier?.FirstOrDefault()?.Value;
        }


        public static string GetPatientName(this Patient patient)
        {

            var firstName = (patient?.Name?.FirstOrDefault())?.Given?.FirstOrDefault();
            var lastName = patient?.Name?.FirstOrDefault()?.Family;
            var middleName = (patient?.Name?.FirstOrDefault()?.Extension?.FirstOrDefault())?.Value?.ToString();
            return $"{firstName}{(!string.IsNullOrWhiteSpace(middleName) ? " " + middleName + " " : " ")}{lastName}";

        }

    }


}

 
 

I hope you found this article helpful in case you need to extract data from a FHIR bundle document. I am not specializing into working with FHIR, I just worked 1-2 weeks on such a FHIR bundle document and found my approach to maybe be of general interest and use. At least I found my approach
scalable for mapping each fields. Also note that I made a domain model as a model object where I put logic into the getters of a property and this corresponds to a field in the FHIR JSON bundle we want to retrieve. So I would then repeat the approach by extending the list of steps to successfully map a FHIR bundle into a domain model which THEN can be used as a better prepared model for INPUT to YOUR system. i.e. we go via a domain model that then can be input to your system where mapping will be trivial inside your system, e.g. save a domain model field into a database or similar if you want to input a FHIR json bundle and create a new POCO entity into your system and store it to a database.

GENERIC APPROACH - Implement a mapping from a FHIR bundle into a DOMAIN MODEL which then can be used in your SYSTEM

• Use the debugger and unit tests and explore in the immediate window which kind of Entry each component in the FHIR bundle is. Identity if we can cast an Entry into a correct subtype, such as a MedicationStatement. These POCO objects are available in the noted nuget packages above.
• After finding a way to retrieve the data - generalize the retrival into extension methods, which can be chained and then make use of these extension methods into property getter logic. These properties reside in the DOMAIN MODEL object. For example ColoscopyDomainModel .
• Use a TDD approach to retrieve the data. Each property was found in the sample doc for me (about 100 properties) and I was trying to find generic ways to find these property values
• Sometimes you need fine tuned logic too to find data. FHIR contains some extensions and different FHIR bundles, although it is a standard, may vary some.
• + REMEMBER - then utilize the DOMAIN MODEL which is mapped into YOUR SYSTEM and then save the fields to a database or other storage for example. Or maybe you only want to use the domain model as is without it doing anything else than represent its data from the FHIR bundle.

Of course you will need some more infrastructure around handling FHIR documents, such as a REST API for example, but this article focused on FHIR bundle parsing. And finally, FHIR supports also the formats XML and RDF. The web site of FHIR can explain more, if you want to delve into details. I found it most helpful just to get started coding here with the GENERIC APPROACH mentioned above. HL 7 FHIR web site: http://hl7.org/fhir/

Share this article on LinkedIn.