Getting Data From a Zus Form

Overview

This document covers the data generated when submitting a Zus form. All data is initially written to a FHIR QuestionnaireResponse in Zus ODS. Structured clinical data that exists in the form submission, such as medications or conditions, are then "extracted" to the appropriate FHIR resources. Below you will find an explanation of this data along with some example FHIR resources.

📘
Pre-Requisites
This document assumes that you're familiar with how to embed a Zus form in your application and assumes that you have some familiarity with HL7 FHIR as a way of representing healthcare data.

QuestionnaireResponse

All form submissions are written as a QuestionnaireResponse resource with the individual answers written to the item array. Writes to QuestionnaireResponse begin as soon as the user starts filling out a form with the resource marked with a status of completed. Extraction of structured data to additional FHIR resources does not begin until the form is submitted and the status is updated to completed. Below are the noteworthy properties of the Zus form generated QuestionnaireResponse resources, along with an example.

3 meta.tag objects containing the form ID, the form version, and the builder ID that owns the form.
status - completed when a form has been submitted, in-progress when a user has begun answering the form but has not submitted it yet, or entered-in-error when a user has canceled a form submission.
subject referencing the patient who the form was submitted for.
item array containing answers to all the questions in the form. The format of these objects may vary depending on how the individual form question was built, but they are all identified by unique linkId values.

{
    "resourceType": "QuestionnaireResponse",
    "id": "{uuid}",
    "meta": {
        "versionId": "2",
        "lastUpdated": "2022-07-19T19:39:26.122+00:00",
        "tag": [
            {
                "system": "https://zusapi.com/accesscontrol/owner",
                "code": "builder/{builderId}"
            },
            {
                "system": "https://zusapi.com/fhir/tag/form-id",
                "code": "9f190f1f-cd4b-4a58-b4e0-29aff327a4ae",
                "display": "Form being answered"
            },
            {
                "system": "https://zusapi.com/fhir/tag/form-version",
                "code": "41",
                "display": "Version of the form being answered"
            }
        ]
    },
    "status": "in-progress",
    "subject": {
        "reference": "Patient/{patientId}",
        "type": "Patient"
    },
    "authored": "2022-07-19T19:39:21Z",
    "item": [
        {
            "linkId": "preferredPronouns",
            "answer": [
                {
                    "valueString": "sheHer"
                }
            ]
        }
    ]
}

New Medications

If a form contains the "Additional Medications" Zus custom component then any user input medications are extracted to the MedicationStatement resource with the following noteworthy properties:

status of active
medicationCodeableConcept with a single coding object containing the RxNorm code for the selected med
medicationCodetableConcept.text with a free-text description of the medication that the user selected
subject referencing the patient the form was submitted for
dateAsserted as the date the form was submitted
note with a single object containing any free-text note provided in the form
dosage with a single object containing a free-text description of the dosage

{
    "resourceType": "MedicationStatement",
    "id": "{uuid}",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2022-07-19T20:14:57.885+00:00",
    },
    "status": "active",
    "medicationCodeableConcept": {
        "coding": [
            {
                "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                "code": "1649560"
            }
        ],
        "text": "Albuterol (Inhalant) 90 mcg/puff DPI 200 puff"
    },
    "subject": {
        "reference": "Patient/{patientId}",
        "type": "Patient"
    },
    "dateAsserted": "2022-07-19T20:14:57Z",
    "note": [
        {
            "authorReference": {
                "reference": "Patient/{patientId}",
                "type": "Patient"
            },
            "time": "2022-07-19T20:14:57Z",
            "text": "free text note"
        }
    ],
    "dosage": [
        {
            "text": "90 mcg/puff DPI 200 puff"
        }
    ]
}

Affirmation/Negation of Pre-populated Medications

If a form contains the "Active Medications" Zus custom component then the user is given a list of pre-populated medications that Zus determined to be active for the patient. The user then affirms/negates each medication providing additional context. These data are all extracted as new MedicationStatement resources with the following noteworthy properties:

status of active, entered-in-error, not-taken, completed or on-hold depending on what the user selected in the status dropdown in the form
medicationCodeableConcept copied from the source medication data
subject referencing the patient the form was submitted for
dateAsserted as the date the form was submitted
note with a single object containing any free-text note provided in the form
informationSource referencing the patient if they were the user filling out the form
derivedFrom containing references to all the medication activity FHIR resources that Zus used to pre-populate the form

{
    "resourceType": "MedicationStatement",
    "id": "{uuid}",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2022-07-19T20:43:16.628+00:00",
        "tag": [
            {
                "system": "https://zusapi.com/accesscontrol/owner",
                "code": "builder/{builderId}"
            }
        ]
    },
    "status": "on-hold",
    "medicationCodeableConcept": {
        "coding": [
            {
                "system": "http://www.nlm.nih.gov/research/umls/rxnorm",
                "code": "617313",
                "display": "atorvastatin 10 MG [Lipitor]"
            }
        ],
        "text": "atorvastatin 10 MG [Lipitor]"
    },
    "subject": {
        "reference": "Patient/{patientId}",
        "type": "Patient"
    },
    "dateAsserted": "2022-07-19T20:43:16Z",
      "note": [
        {
            "authorReference": {
                "reference": "Patient/{patientId}",
                "type": "Patient"
            },
            "time": "2022-07-19T20:14:57Z",
            "text": "free text note"
        }
    ],
    "informationSource": {
        "reference": "Patient/{patientId}",
        "type": "Patient"
    },
    "derivedFrom": [
        {
            "reference": "MedicationDispense/{uuid}",
            "type": "MedicationDispense"
        },
        {
            "reference": "MedicationRequest/{uuid}",
            "type": "MedicationRequest"
        },
        {
            "reference": "MedicationStatement/{uuid}",
            "type": "MedicationStatement"
        }
    ]
}

Conditions

If a form contains the "Conditions" Zus custom component then the user is given a checklist of conditions to select from. These are extracted to the Condition resource with the following noteworthy properties:

clinicalStatus.coding with a single object indicating that the condition is active
verificationStatus.coding with a single object indicating that the condition is unverified since it was submitted via a form and not yet confirmed by a clinician
code with a single object containing the SNOMED-CT code for the selected condition
subject and asserter referencing the patient that the form was submitted for. If the patient was also the user filling out the form then they would be referenced as the recorder as well.

{
    "resourceType": "Condition",
    "id": "{uuid}",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2022-07-19T14:16:19.412+00:00",
        "tag": [
            {
                "system": "https://zusapi.com/accesscontrol/owner",
                "code": "builder/{builderId}"
            }
        ]
    },
    "clinicalStatus": {
        "coding": [
            {
                "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                "code": "active"
            }
        ]
    },
    "verificationStatus": {
        "coding": [
            {
                "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                "code": "unconfirmed"
            }
        ]
    },
    "code": {
        "coding": [
            {
                "system": "http://snomed.info/sct",
                "code": "195967001"
            }
        ]
    },
    "subject": {
        "reference": "Patient/{patientId}",
        "type": "Patient"
    },
    "recordedDate": "2022-07-19T14:16:18Z",
    "asserter": {
        "reference": "Patient/{patientId}",
        "type": "Patient"
    }
}

Allergies

If a form contains the "Allergies" Zus custom component then the user is given a searchable select list to select from. These are extracted to the AllergyIntolerance resource with the following noteworthy properties:

clinicalStatus.coding with a single object indicating that the condition is active
verificationStatus.coding with a single object indicating that the condition is unverified since it was submitted via a form and not yet confirmed by a clinician
criticality of unable-to-assess
code with a single object containing the SNOMED-CT or RxNorm code for the selected allergy
patient and asserter referencing the patient that the form was submitted for. If the patient was also the user filling out the form then they would be referenced as the recorder as well.

{
    "resourceType": "AllergyIntolerance",
    "id": "{uuid}",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2022-07-19T14:16:19.412+00:00",
        "tag": [
            {
                "system": "https://zusapi.com/accesscontrol/owner",
                "code": "builder/{builderId}"
            }
        ]
    },
    "clinicalStatus": {
        "coding": [
            {
                "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
                "code": "active"
            }
        ]
    },
    "verificationStatus": {
        "coding": [
            {
                "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-verification",
                "code": "unconfirmed"
            }
        ]
    },
    "type": "allergy",
    "criticality": "unable-to-assess",
    "code": {
        "coding": [
            {
                "system": "http://snomed.info/sct",
                "code": "260152009"
            }
        ]
    },
    "patient": {
        "reference": "Patient/{patientId}",
        "type": "Patient"
    },
    "recordedDate": "2022-07-19T14:16:18Z",
    "asserter": {
        "reference": "Patient/{patientId}",
        "type": "Patient"
    }
}

Provenance

As explained above, all FHIR resource extraction starts with reading the QuestionnaireResponse and inferring the appropriate downstream resources to be generated. This relationship is documented via the Provenance resource. If a form submission resulted in the extraction of any structured data beyond the QuestionnaireResponse then a Provenance record is written with the following noteworthy properties:

target array with references to all the FHIR resources that were extracted from a form submission
recorded with the date the extraction occurred
agent with a reference to the patient who the form was submitted for
entity with a role of source and a reference to the QuestionnaireResponse for the form submission

{
    "resourceType": "Provenance",
    "id": "{uuid}",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2022-07-19T20:12:45.474+00:00",
        "tag": [
            {
                "system": "https://zusapi.com/accesscontrol/owner",
                "code": "builder/{builderId}"
            }
        ]
    },
    "target": [
        {
            "reference": "MedicationStatement/{uuid}"
        },
        {
            "reference": "Condition/{uuid}"
        }
    ],
    "recorded": "2022-07-19T20:12:45+00:00",
    "agent": [
        {
            "who": {
                "reference": "Patient/{uuid}",
                "type": "Patient"
            }
        }
    ],
    "entity": [
        {
            "role": "source",
            "what": {
                "reference": "QuestionnaireResponse/{uuid}",
                "type": "QuestionnaireResponse"
            }
        }
    ]
}

Overview

📘Pre-Requisites

QuestionnaireResponse

New Medications

Affirmation/Negation of Pre-populated Medications

Conditions

Allergies

Provenance

📘
Pre-Requisites