Read clinical record data from the HealthKit store.
HealthKit’s clinical record support lets you read Fast Healthcare Interoperability Resources (FHIR) from the HealthKit store. Users can download their FHIR records from supported healthcare institutions. The system then updates the records in the background on a regular basis.
Instead of focusing on documents, FHIR breaks the user's medical history into discrete records. HealthKit then represents each FHIR record as an
HKClinical sample that stores a single condition, procedure, or result.
To use clinical records, you must request permission to read each record type. Then, use HealthKit’s queries to access the individual records. Finally, you need to parse and handle each record’s FHIR JSON data.
Xcode’s simulator provides sample accounts you can use when building and testing your app. For more information, see Accessing Sample Data in the Simulator.
Set Up HealthKit
Due to their sensitive nature, clinical records have additional setup requirements. First, when you enable your app’s HealthKit capabilities, you must also enable Health Records, as shown in Figure 1.
Next, you must provide a Health Records Usage string in your app’s
Info file, as shown in Figure 2. Use this string to describe what your app does with the user’s records, and why it's important for the the user to share this data.
You request authorization to read clinical records using the
HKClinical enumeration. This enumeration specifies the types of FHIR data supported by HealthKit. You must request permission to read all the types that your app intends to use. Additionally, clinical records are read-only, so you can’t request authorization to share clinical record types. You can’t create or save new
You can request authorization of clinical record types and regular HealthKit types in the same method call; however, HealthKit presents the clinical record types in a separate permission sheet to ensure the user understands exactly what they're approving.
Query for Health Records
You can use HealthKit’s regular queries to look up clinical records.
Each query returns a single clinical record type. HealthKit also provides two predicates to further refine your queries:
predicateto search for a particular FHIR record. Note that the FHIR identifier is guaranteed to be unique only for a particular resource type from a given source. To uniquely identify a record, you must check the identifier, type, and source.
For Clinical Records From Source: FHIRResource Type: identifier:
predicateto search for a specific FHIR resource type. In most cases, there’s a one-to-one correspondance between the clinical record types and the FHIR resource types; therefore, most queries already return samples from a single FHIR resource type. However, queries for the
For Clinical Records With FHIRResource Type:
HKClinicaltype can return records from the
Type Identifier Medication Record
Type Medication Order
Type Medication Dispense
HKFHIRResourceFHIR resource types. You can use this predicate to limit your query to one of these FHIR types.
Type Medication Statement
Examine FHIR Data
Once you have an
HKClinical sample, you can access the FHIR data through its
FHIRResource property. The
HKFHIRResource object represents the underlying data from the user’s healthcare institution. While the resource object provides properties to access a few, useful attributes (
source), use the
data property to access the underlying JSON, which contains the complete clinical data.
resource property contains a
HKFHIRResource value. While the
HKFHIRResource enumeration is similar to the
HKClinical values, there isn’t a one-to-one relationship between them. For example, a
HKClinical identifier matches
HKFHIRResource types. Similarly, HealthKit splits the
HKFHIRResource type into the
HKClinical identifiers. This means you must query for lab results and vital signs separately. However—unless you use the
predicate predicate—when you query for medication, you get a mixture of statement, order, and dispense records.
Sample JSON data for an FHIR Condition resource is shown below:
This resource was recorded by Adam Gooseff in 2012. It describes seasonal allergic rhinitis (SNOMED code 367498001), with an onset date of May 12, 1994.
The FHIR data contains a considerable amount of additional information; however, to access this data you need to understand the FHIR specification.
For more information, see the following websites: