About FHIR helpers

FHIR models (Fast Healthcare Interoperability Resources) are used with generic methods to create resources. Each supported data model has helper methods to more easily create and fetch data.

List of FHIR helpers in the iOS SDK

The following section describes the available FHIR helpers in the SDK.

Patient

FHIR reference: Patient

The Patient resource is used to create patients with their first and last name.

static func with(firstname: String, lastname: String) -> Patient

To access stored data in the Patient resource.

func getFirstName() -> String?
func getLastName() -> String?

Practitioner

FHIR reference: Practitioner

Used to create a practitioner with first name and last name.

static func with(firstname: String, lastname: String) -> Practitioner

Used to create a practitioner if there’s additional information that needs to be stored but there’s no appropriate property.

static func with(text: String) -> Practitioner

Used to more easily access stored data in the Practitioner resource.

func getFirstname() -> String?
func getLastname() -> String?
func getPrefix() -> String?
func getSuffix() -> String?
func getStreet() -> String?
func getPostalCode() -> String?
func getCity() -> String?
func getTelephone() -> String?
func getWebsite() -> String?
func getText() -> String?

Medication

FHIR reference: Medication

Used to create medications.

static func with(productName: String, form: String) -> Medication

Used to add ingredients to a medication.

func addIngredient(name: String, value: Float, unit: String) throws

Used to more easily access stored data in the Medication resource.

func getProductName() -> String?
func getForm() -> String?
func getIngredients() -> [(name: String, value: Float, unit: String)]

Dosage

FHIR reference: Dosage

Used to create medication dosage.

static func with(value: Float, unit: String, when: String) -> Dosage

Used to more easily access stored data in the Dosage resource

func getValue() -> Float?
func getUnit() -> String?
func getWhen() -> String?

MedicationRequest

FHIR reference: MedicationRequest

Used to store information about a patient and medication along with the dosage and other optional information.

static func with(patient: Patient, medication: Medication, dosage: [Dosage]?, note: String?, reason: String?) throws -> MedicationRequest

Used to more easily access stored data in the MedicationRequest resource.

func getReason() -> String?
func getNote() -> String?
func getPatient() -> Patient?
func getMedication() -> Medication?
func getDosage() -> [Dosage]?

CarePlan

FHIR reference: CarePlan

Used to create a care plan with information about the patient, practitioner, and medications.

static func with(patient: Patient, author: Practitioner, medications: [MedicationRequest]) throws -> CarePlan

Used to more easily access stored data in the CarePlan resource.

func getAuthor() -> Practitioner?
func getPatient() -> Patient?
func getMedicationRequests() -> [MedicationRequest]?
func getMedications() -> [Medication]?

Observation

FHIR reference: Observation

Used to store observational information.

static func with(type: CodeableConcept, text: String, status: ObservationStatus, issuedDate: Instant,
    effectiveDate: DateTime? = nil, referenceRange: ObservationReferenceRange? = nil,
    category: CodeableConcept? = nil) -> Observation
static func with(type: CodeableConcept, observationValue: Float, observationUnit: String,
    status: ObservationStatus, issuedDate: Instant, effectiveDate: DateTime? = nil,
    referenceRange: ObservationReferenceRange? = nil, category: CodeableConcept? = nil) -> Observation
static func with(type: CodeableConcept, quantity: HCFHIR.Quantity, status: ObservationStatus,
    issuedDate: Instant, effectiveDate: DateTime? = nil, referenceRange: ObservationReferenceRange? = nil,
    category: CodeableConcept? = nil) -> Observation

Used to more easily access stored data in the Observation resource.

func getIssuedDate() -> Instant?
func getEffectiveDate() -> DateTime?
func getType() -> CodeableConcept
func getObservationValue() -> Float?
func getObservationUnit() -> String?
func getObservationText() -> String?
func getCategory() -> CodeableConcept?
func getStatus() -> ObservationStatus?
func getQuantity() -> Quantity?
func getType() -> CodeableConcept?

ObservationReferenceRange

FHIR reference: ObservationReferenceRange

Used to store observation reference range information.

static func with(type: CodeableConcept, lowValue: Float?, highValue: Float?, unit: String) -> ObservationReferenceRange
static func with(type: CodeableConcept, lowQuantity: HCFHIR.Quantity?, highQuantity: HCFHIR.Quantity?) -> ObservationReferenceRange

Used to more easily access stored data in the ObservationReferenceRange resource.

func getHighQuantity() -> Quantity?
func getLowQuantity() -> Quantity?
func getLowValue() -> Float?
func getHighValue() -> Float?
func getUnit() -> String?

DiagnosticReport

FHIR reference: DiagnosticReport

Used to link multiple observations into a single report.

static func with(code: CodeableConcept, status: DiagnosticReportStatus, laboratoryName: String, issued: Instant, observations: [HCFHIR.Observation]) throws -> DiagnosticReport

Used to more easily access stored data in the DiagnosticReport resource.

func getStatus() -> DiagnosticReportStatus?
func getCode() -> CodeableConcept?
func getLaboratoryName() -> String?
func getObservations() -> [Observation]

DocumentReference

FHIR reference: DocumentReference

Used to create documents with attachments and author.

static func with(title: String, indexed: Instant, status: DocumentReferenceStatus, attachments: [HCFHIR.Attachment], type: CodeableConcept, author: HCFHIR.Practitioner, practiceSpeciality: CodeableConcept? = nil) -> DocumentReference
static func with(title: String, indexed: Instant, status: DocumentReferenceStatus, attachments: [HCFHIR.Attachment], type: CodeableConcept, author: HCFHIR.Organization, practiceSpeciality: CodeableConcept? = nil) -> DocumentReference

Used to more easily access stored data in the DocumentReference resource

func getTitle() -> String?
func getAttachments() -> [Attachment]?
func getAdditionalIds() -> [String]?
func getPracticeSpeciality() -> CodeableConcept?
func getOrganization() -> Organization?
func getPractitioner() -> Practitioner?
func getIndexedDate() -> Instant?
func getStatus() -> DocumentReferenceStatus?
func getType() -> CodeableConcept?

Attachment

FHIR reference: Attachment

Used to create an Attachment element.

static func with(title: String, creationDate: DateTime, contentType: String, data: Data) throws -> HCFHIR.Attachment

Additionally, the SDK provides FHIR helpers to detect data MIME types. If no MIME type is found, data is invalid for upload.

guard let contentType = MIMEType.of(imageData)?.rawValue else { fatalError("Invalid MIME type") }
let attachment = Attachment.with(title: title, creationDate: date, contentType: mimeTypeString, data: data)

Used to more easily access stored data in the Attachment element.

func getTitle() -> String?
func getCreationDate() -> DateTime?
func getContentType() -> String?
func getData() -> Data?

Organization

FHIR reference: Organization

Used to create an Organization resource.

static func with(type: CodeableConcept, name: String, street: String? = nil, postalCode: String? = nil, city: String? = nil, telephone: String? = nil, website: String? = nil) -> Organization

Used to more easily access stored data in the Organization resource.

func getName() -> String?
func getType() -> CodeableConcept?
func getStreet() -> String?
func getPostalCode() -> String?
func getCity() -> String?
func getTelephone() -> String?
func getWebsite() -> String?

FHIR helper examples

The following section provides examples for Fast Healthcare Interoperability Resources (FHIR) helpers.

Example: DocumentReference

Creating a document with attachments provided by an author.

Creating an attachment

To create an attachment.

let attachment = try Attachment.with(title: "Image", creationDate: .now, contentType: "image/png", data: image.pngData())

Creating an author (Practitioner or Organization)

To create an author.

let practitioner = Practitioner.with(firstname: "John", lastname: "Miller")

or

let organizationType = CodeableConcept(code: "dept", display: "Hospital Department", system: "https://www.hl7.org/fhir/valueset-organization-type.html")
let organization = Organization.with(type: organizationType, name: "123 Hospital")

Creating a document with attachment, author, and other information.

To create a document with an attachment and various other information.

let practiceSpeciality = CodeableConcept(code: "394612005", display: "Urology", system: "http://loinc.org")
let documentType = CodeableConcept(code: "18782-3", display: "Radiology Study observation (findings)", system: "http://loinc.org")
let document = try DocumentReference.with(title: "Scan",
                                          indexed: .now,
                                          status: .current,
                                          attachments: [attachment],
                                          type: documentType,
                                          author: practitioner,
                                          practiceSpeciality: practiceSpeciality)

Uploading a document using the SDK generic resource method

HCSDKClient.default.createRecord(document) { result in
    // handle result
}

Fetching and reading information from a document

HCSDKClient.default.createRecord(document) { result in
    guard let document = result.value?.resource as? DocumentReference else {
        return
    }

    let attachments = document.getAttachments()
    let author = document.getPractitioner()
}

Downloading attachment data

If a DocumentReference resource is fetched using the fetchResource method, all of the attachments only have metadata (for example, title and contentType) but no data payload. To download an attachment including the data payload, use the downloadAttachment method or the downloadAttachments method.

HCSDKClient.default.downloadRecord(withId: "identifier") { result in
    guard let document = result.value?.resource as? DocumentReference else {
        return
    }

    guard let attachments = document.getAttachments() else {
        return
    }

    let data = attachments.first?.getData()
}
You can download a single attachment or a list of attachments, see API docs.

Example: Creating a CarePlan recource

Creating a CarePlan resource for a Patient resource by some Practitioner resource that includes the Medication resource and info about the dosage in the Dosage resource.

Creating patient and author

let patient = Patient.with(firstname: "John", lastname: "Doe")
let doctor = Practitioner.with(text: "Dr. John Miller, Practice for general medicine")

Creating a medication and adding ingredients if necessary

let medication = Medication.with(productName: "Ibuprofen-ratiopharm", form: "tablets")
medication.addIngredient(name: "Ibuprofen", value: 40, unit: "mg")

Creating a medication request with patient, medication, dosage, and optional information

let morningDosage = Dosage.with(value: 2, unit: "Piece", when: "morning")
let eveningDosage = Dosage.with(value: 2, unit: "Piece", when: "evening")

let medicationRequest = try MedicationRequest.with(patient: patient,
                                                   medication: medication,
                                                   dosage: [morningDosage, eveningDosage],
                                                   note: "For oral ingestion",
                                                   reason: "Combat cystitis")

Creating a care plan using previously defined resources

let carePlan = try CarePlan.with(patient: patient, author: doctor, medications: [medicationRequest])

Uploading the care plan using the SDK generic resource method

HCSDKClient.default.createRecord(carePlan) { result in
    // Handle result
}

Fetching and reading information from the care plan

HCSDKClient.default.fetchRecord(withId: "some-uuid") { result in
    guard let carePlan = result.value?.resource as? CarePlan else {
        return
    }

    let author = carePlan.getAuthor()
    let patient = carePlan.getPatient()
    let requests = carePlan.getMedicationRequests()
    let medications = carePlan.getMedications()
}

Example: Storing custom identifiers

Most of the FHIR resources support adding custom identifiers per client. The following resources are supported:

  • DocumentReference

  • Observation

  • DiagnosticReport

  • CarePlan

  • Organization

  • Practitioner

  • Patient

You can use the following helper functions on all supported resources:

func addAdditionalId(_ id: String)
func setAdditionalIds(_ ids: [String])
func getAdditionalIds() -> [String]?

To add and fetch a custom identifier.

let document = DocumentReference(...)
document.addAdditionalId("some-custom-identifier")

guard let ids = document.getAdditionalIds() else { return }
let storedIdentifier = ids.first

To overwrite custom identifiers with new values.

let document = DocumentReference(...)
let identifiers = ["some-custom-identifier-one", "some-custom-identifier-two"]
document.setAdditionalIds(identifiers)

To delete all of the custom identifiers.

let document = DocumentReference(...)
document.setAdditionalIds([])

With your consent, we will analyze your behaviour on the website to improve the website for all users. If you consent to the transmission of analysis data, click “Accept”. You can use the website without giving consent to analyze your behaviour. For further information, visit the privacy policy.