SDC with Custom Resources

Structured Data Capturing with Aidbox Custom Resources

Sometimes FHIR granularity is too small to collect patient data from user interfaces. For example, when a physician or a nurse records vital signs in terms of FHIR, they produce a bundle of observations. How to save this data to a FHIR server? How to keep track that this data was collected on the Vitals Form?

One option is to build a transaction bundle with a provenance on the client side and send it to the transaction endpoint. But with this approach it is rather problematic to track data back; update or delete it as a whole.

There is a Structured Data Capture Implementation Guide (SDC IG) which describes how to collect data using Questionnaire and QuestionnaireResponse resources. It is a good idea and a work in progress. One problem we see with it is that the QuestionnaireResponse table is stuffed with all sorts of things and managing this table, doing searches and updates is problematic. Another problem is that Questionnaire/QuestionnaireResponse is too generic and verbose which makes working with them inconvenient.

Aidbox supports Custom Resources, which cover all Questionnaire functionality and flexibility while providing many more features - validation, separate storage, search, references to other FHIR resources, etc. We applied key ideas from the SDC IG to Custom Resources to give you the best of both worlds.

Demonstration Scenario

The first step is to define your custom resource. We recommend using sugar App API. As an example we are defining resource Vitals with temperature, heart_rate, and patient reference:

custom-resource.yaml

POST /App

resourceType: App
id: Vitals
apiVersion: 1
type: app
entities:
  Vitals:
    attrs:
      temperature: {type: number}
      heart_rate: {type: number}
      ts: {type: dateTime}
      patient:
        type: Reference
        refers: [Patient]

Now we can check that Vitals work properly.

Create a new vitals record:

patient

PUT /Patient/pt-1

name: 
- family: Jackson
  given: ['John']

create-vitals

POST /Vitals

resourceType: Vitals
temperature: 36.6
heart_rate: 102
patient: {id: 'pt-1', resourceType: 'Patient'}
ts: '2019-04-09T12:00:00Z'

Get all vitals records for the patient pt-1:

get-vitals

GET /Vitals?.patient.id=pt-1

Debugging Extraction

Now we want to transform Vitals to a set of FHIR Observations. We are using template extraction. You can play and debug extraction using /AlphaSDC/$debug

debug.yaml

POST /AlphaSDC/$debug

source:
 id: src-1
 temp: 36.6
template:
  Observation:
     temp: 
       value: { $path!: [temp] }

response.yaml

source: {id: src-1, temp: 36.6}
template:
  Observation:
    temp:
      value:
        $path!: [temp]
extracted:
  Observation:
    temp:
      value: 36.6
      id: temp-src-1
      meta: {sourceId: src-1}

template it structured as { [resourceType] : { [id-prefix] : <resource-template> }}, for example to generate Observation with prefix tmp you write {Observation: {tmp: <resource-template>}}

<resource-template> is a template/prototype of a resulting FHIR resource, where some attributes contain substitution rules like { $path!: ["attr", "attr"]}. These rules will be replaced with values from Custom resource, indicated by this path.

Advanced substitution rules examples

resource.yaml

resourceType: QuestionnaireResponse
id: qr1
questionnaire: Questionnaire/q1|1
item:
- text: What is your height in feet.inches?
  answer:
  - valueDecimal: 5.2
  linkId: ht
- text: What is your weight in pounds?
  answer:
  - valueDecimal: 122
  linkId: wt

Let's suppose you want to extract the height of a respondent, for this purpose you can use this $path expression ["item, {"linkId": ht"}, "answer", 0, "valueDecimal"]

{"linkId": ht"} - this object is used for filtering, you can declare the objects with as many keys as you need to match item in the specified collection.

Create SDC resource

Now let's define how FHIR Observations will be extracted from Vitals. We have to create AlphaSDC resource for that:

PUT /AlphaSDC/Vitals

template:
  Observation:
    temp:
      subject:
        $path!: [patient]
      category:
      - coding:
        - {system: 'http://terminology.hl7.org/CodeSystem/observation-category', code: vital-signs, display: Vital Signs}
      status: final
      code:
        coding:
        - {system: 'http://loinc.org', code: 8310-5, display: Body temperature}
      effective:
        dateTime:
          $path!: [ts]
      value:
        Quantity:
          value:
            $path!: [temperature]
          unit: degrees C
          system: http://unitsofmeasure.org
          code: Cel
    hr:
      subject:
        $path!: [patient]
      category:
      - coding:
        - {system: 'http://terminology.hl7.org/CodeSystem/observation-category',
          code: vital-signs, display: Vital Signs}
      status: final
      code:
        coding:
        - {system: 'http://loinc.org', code: 8867-4, display: Heart rate}
      effective:
        dateTime:
          $path!: [ts]
      value:
        Quantity:
          value:
            $path!: [heart_rate]
          unit: beats/minute
          system: http://unitsofmeasure.org
          code: /min

.id of AlphaSDC resource should be exactly the same as the name of Custom Resource - i.e., Vitals

.template is a template described in the section above.

Now you can test how data is extracted using POST /AlphaSDC/<id>/$extract endpoint:

request

POST /AlphaSDC/Vitals/$extract

resourceType: Vitals
temperature: 36.6
heart_rate: 102
patient: {id: 'pt-1', resourceType: 'Patient'}
ts: '2019-04-09T12:00:00Z'

You should see the following response:

source: <original resource>
template: <template>
extracted: <result-of-extraction>

Make it work on resource save

To make this extraction work on Vitals save, we have to override its Create Operation

PUT /Operation/vitals-create

request: [post, Vitals]
action: sdc/create

sdc/create action will do extraction and save original custom resource and extracted FHIR resources:

create-vitals

POST /Vitals

resourceType: Vitals
id: v-2
temperature: 36.6
heart_rate: 102
patient: {id: 'pt-1', resourceType: 'Patient'}
ts: '2019-04-09T12:00:00Z'

Now we can see the Observations that have been created:

get-observations

GET /Observation?.subject.id=pt-1
# or
GET /Vitals?.patient.id=pt-1

Please provide your feedback and use cases for SDC using github