FHIRPath

Instantiate HS.FHIRPath.API

The process of using FHIRPath to evaluate and extract data from a resource begins with calling HS.FHIRPath.API.getInstance()Opens in a new tab. When you call this method, you must specify the FHIR package that corresponds to a version of FHIR. For example, if the resources you are evaluating conform to FHIR R4, the corresponding package ID is currently hl7.fhir.r4.core@4.0.1. In this case, instantiating HS.FHIRPath.APIOpens in a new tab would look like:

 set fhirPathAPI = ##class(HS.FHIRPath.API).getInstance($lb("hl7.fhir.r4.core@4.0.1"))

You can obtain the IDs of the currently loaded packages using the Management Portal or ObjectScript:

• Management Portal — Navigate to Home > Health > MyFHIRNamespace > FHIR Configuration, and select the Package Configuration card. The package ID is obtained by appending the @ symbol and version number to the name of the package. For example, the ID of the following package is hl7.fhir.r4.core@4.0.1:

  

• ObjectScript — To list package IDs programmatically, see Listing Available Packages.

The HS.FHIRPath.APIOpens in a new tab object includes the methods used to parse FHIRPath expressions and evaluate resources. This object is also included as a property on the HS.FHIRMeta.APIOpens in a new tab object under the FHIRPathAPI property.

Parse the FHIRPath Expression

Once you have instantiated the HS.FHIRPath.APIOpens in a new tab object, you are ready to parse the FHIRPath expression. The method that parses the expression, HS.FHIRPath.API.parse()Opens in a new tab, returns a tree structure that is used by the methods that evaluate a resource. For example, assuming you have an object named fhirPathAPI instantiated as shown in the previous section:

 set tree = fhirPathAPI.parse("name.given.empty()")

Evaluate the Resource

Once you have parsed the FHIRPath expression, you can use its tree structure to evaluate or extract data from a resource. Two evaluation methods are available:

• HS.FHIRPath.API.evaluate()Opens in a new tab — The evaluate() method returns the results of the evaluation in a multidimensional array.

• HS.FHIRPath.API.evaluateToJson()Opens in a new tab — The evaluateToJson() method returns the collection in a dynamic array.

In both cases, the resource being evaluated is passed into the method as a dynamic object. The tree that was returned by the parse() method is also passed as an argument. For example:

 set tree = fhirPathAPI.parse("name.given.empty()")
 // myResource is a dynamic object
 do fhirPathAPI.evaluate(myResource, tree, .OUTPUT)
 set DynArray = fhirPathAPI.evaluateToJson(myResource, tree)

An additional method, HS.FHIRPath.API.evaluateArray()Opens in a new tab, can be used to parse the multidimensional array returned by the evalaute() method.

Work with the Results

While working with results in a dynamic array that is produced by evaluateToJson() has its benefits, the multidimensional array produced by evaluate() contains additional information that is not otherwise available. The following provides a guide to the data in the multidimensional array, assuming that your response to evaluate() was returned in a variable named OUTPUT.

You can further parse the returned multidimensional array using the evaluateArray() method.

By contrast. when using the evaluateToJson() method to produce a dynamic array, you can determine whether the data type is a string, boolean, number, or object from looking at the values in the array, but you cannot determine the FHIR data type.

Workflow Example: evaluate() Method

This example includes the resource being evaluated, the ObjectScript needed to evaluate the resource, and a look at the multidimensional array produced by the evaluation.

Sample Resource

 set myResource = {
   "resourceType":"Patient",
   "telecom": [
     {
       "system": "phone",
       "value": "(03) 5555 6473",
       "use": "official"
    },
    {
      "system": "phone",
      "value": "(03) 5555 6473",
      "use": "home"
    },
    {
      "system": "email",
      "value": "myName@email.com",
      "use": "official"
     }
   ]
 }

Extracting Data from the Resource

 set fhirVersion = $lb("hl7.fhir.r4.core@4.0.1")
 set fhirPathAPI = ##class(HS.FHIRPath.API).getInstance(fhirVersion)
 set tree = fhirPathAPI.parse("telecom.where(use = 'official')")
 do fhirPathAPI.evaluate(myResource, tree, .OUTPUT)

Viewing the Multidimensional Array

If you used the zw OUTPUT command in the InterSystems Terminal to view the multidimensional array returned by evaluate(), the result would be:

OUTPUT=2
OUTPUT(1)={"system":"phone","value":"(03) 5555 6473","use":"official"}
OUTPUT(1,"t")="ContactPoint"
OUTPUT(2)={"system":"email","value":"myName@email.com","use":"official"}
OUTPUT(2,"t")="ContactPoint"

Notice that the values are identified as a ContactPoint FHIR data type.

Workflow Example: evaluateArray() Method

This example takes the multidimensional array produced by the evaluation in the evaluate() example above as input and demonstrates the ObjectScript needed to evaluate the resulting array, and looks at the multidimensional array produced by the evaluation.

Extracting Data from the Output Array

 Merge INPUT = OUTPUT
 Kill OUTPUT

 Set tree = fhirPathAPI.parse("ContactPoint.value")

 do fhirPathAPI.evaluateArray(.INPUT, tree, .OUTPUT)

Viewing the Multidimensional Array

If you used the zw OUTPUT command in the InterSystems Terminal to view the multidimensional array returned by evaluateArray(), the result would be:

OUTPUT=2
OUTPUT(1)="(03) 5555 6473"
OUTPUT(1,"t")="string"
OUTPUT(2)=”myName@email.com"
OUTPUT(2,"t")="string"

Notice that the values are identified by their ObjectScript data type (string, boolean, number, or object).

Workflow Example: evaluateToJson() Method

This example includes the resource being evaluated, the ObjectScript needed to evaluate the resource, and a look at the dynamic array produced by the evaluation.

Sample Resource

 set myResource = {
   "resourceType":"Patient",
   "name": [
     {
       "family": "Cooper",
       "given": [
         "James",
         "Fenimore"
       ]
     }]
 }

Evaluating the Resource

 set fhirVersion = $lb("hl7.fhir.r4.core@4.0.1")
 set fhirPathAPI = ##class(HS.FHIRPath.API).getInstance(fhirVersion)
 set tree = fhirPathAPI.parse("name.given.empty()")
 set dynArray = fhirPathAPI.evaluateToJson(myResource, tree)

Viewing the Dynamic Array

If you used the zw dynArray command in the InterSystems Terminal to view the dynamic array, the result would be:

dynArray=[false]