Aidbox forms supports Observation-based extraction and Definition-based extraction
Observation-based extraction
Observation-based extraction are widely used extraction method and the simpliest one.
To extract data from item to Observation, you just need to add code to item and enable Observation extraction.
Form setup:
Fill item code (this code will go into Observation code)
Enable Observation-extraction by clicking "Data extraction" -> "Observation"
Minimal Questionnaire that uses that approach:
title: New form
status: draft
url: http://forms.aidbox.io/questionnaire/new-form
resourceType: Questionnaire
item:
- type: quantity
text: Weight
extension:
- url: http://hl7.org/fhir/StructureDefinition/questionnaire-unitOption
valueCoding:
display: F
- url: http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-observationExtract
valueBoolean: true
linkId: weight
code:
- code: 8302-2
system: http://loinc.org
display: Body height
Usage
To get some data from you need to call $extract operation. Also, you can use Debug panel in builder, choose Extraction and you will see result of calling this operation:
POST /fhir/QuestionnaireResponse/$extract
content-type: application/json
resourceType: Parameters
parameter:
- name: questionnaire-response
resource:
resourceType: QuestionnaireResponse
subject:
id: morgan
resourceType: Patient
author:
id: morgan
resourceType: Patient
status: in-progress
item:
- linkId: weight
text: Weight
answer:
- valueQuantity:
value: 123123
unit: F
questionnaire: http://forms.aidbox.io/questionnaire/new-form
In response you will get resource Bundle with needed Observation:
resourceType: Observation
status: final
code:
coding:
- code: 8302-2
system: http://loinc.org
display: Body height
subject:
reference: Patient/morgan
valueQuantity:
value: 123123
unit: F
effectiveDateTime: '2024-08-13T10:56:51.101406969Z'
id: c83afc80-b274-4a75-8034-c54ee3110e67
Definition-based extraction
Definiton-based extraction can be used to extract any type of resources. In this guide we will create form that updates Patient info.
Form setup
Create in builder group called Patient and three items, so your form in item tree should look like this:
Patient [group]
- family name [string]
- given name [string]
- birth date [date]
1. Setting group extraction context
Select group in outline
Expand Data extraction section
Check Extract
Select Definition
Fill Group extraction context with Patient/{{%resource.subject.id}}
When aidbox mets this group during the extraction process, it will fetch Patient resource with id = subject.id of QuestionnaireResponse.
2. Setting item definitions
Once we have item extraction context (in our case it is a Patient resource), we can set where answers from items in this group should go.
For each item in "Patient" group enable data-extraction in builder and choose "Definition" and fill it with these values:
Patient.name.family for family name item
Patient.name.given for given name item
Patient.birthDate for birth date item
In the end your Questionnaire should look like this:
In response you will find two entries in Bundle resource: one updating Patient resource and one for creating Provenance resource.
resourceType: Bundle
type: transaction
entry:
- resource:
address:
- city: Historic City
line:
- 534 Erewhon St
state: DE
name:
- family: John
given:
- Doe
birthDate: '2024-08-17'
resourceType: Patient
id: morgan
identifier:
- value: ''
system: ''
gender: male
maritalStatus:
coding:
- code: M
system: http://terminology.hl7.org/CodeSystem/v3-MaritalStatus
display: Married
request:
method: PUT
url: /Patient/morgan
- resource:
resourceType: Provenance
recorded: '2024-08-13T11:32:02.855923Z'
target:
- reference: Patient/morgan
agent:
- who:
reference: Patient/morgan
entity:
- what:
reference: QuestionnaireResponse/0935069e-2396-41d6-9f27-eafbd812cc98
role: source
request:
method: POST
url: /Provenance
Extraction complicated resource types
In our example ContactPoint has constraints which means:
A system field is required if a value is provided.
We need setup another item which will be extract's need system field.
Form setup
Let's create a form that updates Patient phone resource. Create in builder group called Patient and two items into it , so your form in item tree should look like this:
Patient [group]
- phone [integer]
- system [string]
1. Setting group extraction context
Select group in outline
Expand Data extraction section
Check Extract
Select Definition
Fill Group extraction context with Patient/{{%resource.subject.id}}
When aidbox mets this group during the extraction process, it will fetch Patient resource with id = subject.id of QuestionnaireResponse.
2. Setting item definitions
Once we have item extraction context (in our case it is a Patient resource), we can set where answers from items in this group should go.
For each item in "Patient" group enable data-extraction in builder and choose "Definition" and fill it with these values:
Patient.telecom.value for phone name item
Patient.telecom.system for system name item
3. Setting widget
Select system widget in outline
Select Hidden and Readonly properties
Expand Rules section
Fill Calculated Expression with 'phone'
Now system item will extract 'system' = 'phone' into Patient telecom resource.
In the end your Questionnaire should look like this:
Let's create a form that updates Patient resource. Any item in Questionnaire that you want to extract using this approach must be placed inside a group with
Some resource types have rules for extraction conditions. For example, extracting Patient phone or another contact information needs to be created data type.
