Document DSL (deprecated)

• Document is schema for Questionnaire with questions and answers and types of values.
• Document is used as source of metainformation by FormLayout
• Document is used as source of metainformation by FormFinalize
• Document resources stored in SDCDocument table.
• Document can define computed fields via rules.

Marking schema as SDC Document entity

Document definition should be marked with aidbox.sdc/doc tag, and also tagged as zen/schema - because it's already schema.

MyDocument
{:zen/tags #{zen/schema aidbox.sdc/doc}}

And after that you can define your custom properties of the document and it's meta information (like source of the document)

Document source defined as fhir Coding like structure, with :system, :code and :url properties

MyDocument
{:zen/tags #{zen/schema aidbox.sdc/doc}
 :source {:code "85353-1" :system "http://loinc.org"}}

To define document fields - you should add :type zen/map property and put your fields under :keys property.

MyDocument
{:zen/tags #{zen/schema aidbox.sdc/doc},
 :type zen/map
 :keys {:loinc-8310-5 {:text "Body temperature"
                       :type zen/map,
                       :confirms #{aidbox.sdc.fhir/quantity},
                       :sdc/boundaries {:imperial {:min 86, :max 105},
                                        :metric {:min 30, :max 42}},
                       :units [{:name "°F"} {:name "°C"}]}}}

Every document field should confirms aidbox.sdc/super-field schema.

For details see Document DSL (deprecated) section.

DB Storage & Common properties

To support document db-saving ability and support common fields for all documents such as:

• :authorReference to user which create document,
• :encounterReference to encounter,
• :unitsystemWhat unit system was used in this document at launch,
• :patientReference to patient
• :statusStatus of the document,
• :typeFull name of document profile.
• :formName/version of form, with which document was captured

You need to add :confirms #{aidbox.sdc/Document} property

MyDocument
{:zen/tags #{zen/schema aidbox.sdc/doc}
 :type zen/map
 :confirms #{aidbox.sdc/Document}}

Rules

Rules used for computed properties. Properties schema and compute formula - defined separately.

To support rules definition you need to add tag aidbox.sdc/rules

MyDocument
{:zen/tags #{aidbox.sdc/doc zen/schema aidbox.sdc/rules}}

and after that you can define caclulated properties and their formulas under :sdc/rules property

MyDocument
{:zen/tags #{aidbox.sdc/dok zen/schema aidbox.sdc/rules},
 :type zen/map
 :sdc/rules {:loinc-39156-5 (when (and (get-in [:loinc-29463-7])
                                       (get-in [:loinc-8302-2]))
                             (* (divide (* (get-in [:loinc-29463-7]) 703)
                                        (* (get-in [:loinc-8302-2])
                                           (get-in [:loinc-8302-2])))
                                1))},
 :keys {:loinc-39156-5 {:type zen/number,
                        :text "BMI"}}}

• name of the rule (:loinc391565) should be matched with name of the field.
• If sdctype inference can't recognize field as calculatedyou can mark it manuallyadd :sdctype aidbox.sdc/calculated to it

Rules logic defined via Embeddel lisp. See details in Lisp reference.

Document Field definition

SDCDocument has several embedded field-types:

• aidbox.sdc/textfields with multiline text
• aidbox.sdc/stringfields with oneline text
• aidbox.sdc/numberfields with number
• aidbox.sdc/quantityfields with measurement units
• aidbox.sdc/choicefields with answers, located in valuesets
• aidbox.sdc/referencefields with reference to arbitrary resources
• aidbox.sdc/calculatedfields, which need to be calculated via rules engine
• aidbox.sdc/attachmentfields, that can be used to attach a file

This field types inferred from Document field schemas. But you can overwrite that by specifying it directly via :sdc-type key

super-field schema

Field-type definition.

Schema contains several aspects of Document (Field) lifecycle

• how it stored in DB
• how it validates
• how it appeares in UI layout
• what the possible options
• what the source of the field

Can contain sub-fields or behaves like an array. Also has links to original sources of questions.

super-field schema has next keys:

quantity field-type

Quantity contains units of measurement

quantity schema has next additional keys:

Example:

MyDocument
{:zen/tags #{aidbox.sdc/doc zen/schema}
 :keys {:temp {:text "Body temperature"
               :type zen/map,
               :confirms #{aidbox.sdc.fhir/quantity},
               :units [{:name "°F"} {:name "°C"}]}}}

choice field-type

Choise field has predefined set of answers.

Choice fields use these properties:

By default choice field uses :enum keyword for options definition.

Example:

MyDocument
{:zen/tags #{zen/schema aidbox.sdc/doc},
 :keys {:bp-measurement {:text "BP measurement site"
                         :confirms #{aidbox.sdc.fhir/coding}    ;; <-- if you use :enum to enumerate possible values - this confirms is optional
                         :enum [{:value {:text "Biceps left",
                                         :code "LA11158-5",
                                         :system "http://loinc.org"}}
                                {:value {:text "Biceps right",
                                         :code "LA11159-3",
                                         :system "http://loinc.org"}}]}}}

For simple cases you can freely use :enum keyword with options - but for complex one (big datasets/more flexibility) you also have 2 alternative sources for retreiving them:

• :aidbox.sdc.options/valueset use valuset stored in aidbox db
• :aidbox.sdc.options/rpcuse custom rpc

If you specify :sdc/options :aidbox.sdc.options/valueset, then you also must specify :valueset property.

Example:

Static valueset

:sdc/options :aidbox.sdc.options/valueset
:valueset "my-food-allergy-valueset"

Dynamic valueset

:sdc/options :aidbox.sdc.options/valueset
:valueset (if (= (get :type) "food")
            "my-food-allergy-valueset"
            "my-substance-allergy-valueset")

If you specify :sdc/options :aidbox.sdc.options/rpc, then you also must specify :rpc property.

RPC method invocations have next structure

Each value of parameters-map should be valid lisp expression.

Example:

:sdc/options :aidbox.sdc.options/rpc
:rpc {:method my-ns/my-rpc
      :params {:p1 (+ 1 2)
               :p2 20}}

reference field-type

Reference field-type contains aidbox reference to resource (id + resourceType + display)

Also field has search semantics based on full resource text search.

reference fields should have these properties:

Example:

MyDocument
{:zen/tags #{aidbox.sdc/doc zen/schema}
 :keys {:patient {:text "Patient"
                  :type zen/map,
                  :confirms #{aidbox.sdc.fhir/reference},
                  :resourceType "Patient"}}}

calculated field-type

Calculated field. Rule with same name should be used to calculate the result.

Calculated fields don't provide additional keys. Instead it depends on :sdc/rules

MyDocument
{:zen/tags #{zen/schema aidbox.sdc/doc aidbox.sdc/rules},
 :keys {:height  {...}
        :weigth  {...}
        :bmi     {:text "BMI",
                  :type zen/number}}
 :sdc/rules {:bmi (divide (get :weigth)
                          (* (get :height)
                             (get :height)))}}

attachment field-type

Attachment field can be used to attach a file to document. File can be stored in DB or in cloud bucket (currently AWS S3 and GCP buckets are supported)

Example:

MyDocument
{:zen/tags #{aidbox.sdc/doc zen/schema}
 :keys {:pulse-image {:confirms #{aidbox.sdc.fhir/attachment}
                      :sdc-type aidbox.sdc/attachment}}}

You can apply some constraints such as file type, max size:

MyDocument
{:zen/tags #{aidbox.sdc/doc zen/schema}
 :keys {:pulse-image {:confirms #{aidbox.sdc.fhir/attachment}
                      :sdc-type aidbox.sdc/attachment
					  :type zen/map
					  :keys {:contentType {:type zen/string
                                           :regex "image/*"}
                             :size {:type zen/integer
                                    :max 100000}}}}}

QuestionnaireResponse convertions

If you need to convert SDCDocument to QuestionnaireResponse you need to specify additional field property

• :linkIdlinkId of original Questionnaire (if not given key of the question will be taken)

MyDocument
{:zen/tags #{zen/schema aidbox.sdc/doc},
 :keys {:bmi {:text "BMI",
              :type zen/number,
              :linkId "/39156-5"}},
 }

SDCDocument extraction

If you would like to extract some values to Observation you should specify additional field property:

• :codecode/system of original Questionnaire question

MyDocument
{:zen/tags #{zen/schema aidbox.sdc/doc},
 :keys {:bmi {:text "BMI",
              :type zen/number,
              :code [{:system "http://loinc.org" :code "39156-5"}]}},
 }

Optional features

Store attachments in cloud storage

Aidbox Forms support storing attachments in the cloud.

Supported cloud storages:

• AWS S3
• GCP Cloud Storage

1. Configure your aidbox/system with sdc-service and it's configuration.

Example:

 box
 {:zen/tags #{aidbox/system}
  :zen/desc "test server"
  :services {:sdc sdc-service}}

2. Create AWS S3 or GCP Cloud Storage 3. Configure sdc-service with created account resource and specify a bucket name

Example:

sdc-service
{:zen/tags   #{aidbox/service}
 :engine     aidbox.sdc/service
 :attachment {:bucket {:name "sdcattachments_bucket"
		       :account {:id "aws-account"
				 :resourceType "AwsAccount"}}}}