result:
resourceType: Questionnaire
title: PHQ2/PHQ9 Depresssion
name: box.sdc.sdc-example/PHQ2PHQ9Form
status: draft
lastReviewDate: '2022-10-10'
contact:
- name: cont1
telecom:
- system: tel
value: 300-00-00
effectivePeriod:
start: '2022-10-10T10:10:10Z'
end: '2022-10-10T10:10:10Z'
description: Base schema for questionnaire(document) definition. Also a resource in DB - SDCDocument
approvalDate: '2022-10-10'
item:
- linkId: misc-yes-no-button
text: 'PHQ-9 Questionnaire: For positive depression screen or follow up'
type: boolean
- linkId: 44258-2
text: Feeling bad about yourself-or that you are a failure or have let yourself or your family down
type: choice
code:
- code: 44258-2
system: http://loinc.org
answerOption:
- value:
Coding:
code: LA6568-5
system: http://loinc.org
display: Not at all
- value:
Coding:
code: LA6569-3
system: http://loinc.org
display: Several days
- value:
Coding:
code: LA6570-1
system: http://loinc.org
display: More than half the days
- value:
Coding:
code: LA6571-9
system: http://loinc.org
display: Nearly every day
- linkId: loinc-LL382-3
text: PHQ-9 Interp-score
type: decimal
code:
- code: LL382-3
system: http://loinc.org
Error:
error:
message: Can't save form to resource: you need specify :fhir/id property on the form
convert-forms
Convert all SDCForms with :fhir/id property to FHIR questionnaire and store them in DB.
params:
Param
Description
Type
required?
describe-rules*
If true - will add field calculation rule description to Q
boolean
no
Returns list of pairs [form-name, convertions-result] where convertion result is one of:
Ok
{messge: "error message"}
Request:
POST /rpc
method: aidbox.sdc/convert-forms
params:
describe-rules: true
Result:
result:
- - box.sdc.sdc-example/PHQ2PHQ9Form
- ok
- - box.sdc.sdc-example/PHQ2PHQ9Form
- message: '...Something wrong with conversion...'
generate-form-template
Generate ZEN namespace with empty Form definition and all relevant layers. You can use this as starting point when you need create custom form from scratch.
Note: rpc doesn't make any changes in filesystem - it just returns template. You then should save it to file manually
params:
Param
Description
Type
required?
ns
Namespace of form
String
no
title
Form Title
String
no
POST /rpc?
method: aidbox.sdc/generate-form-template
params:
ns: 'my.company.forms.my-vitals'
title: 'My first form'
Properties is a typical map where each key is a property name and value is any JSON value Dynamic Properties - properties that are stored in DB, in SDCFormMetadata resource
Given properties will be merged with existed - you can replace old values by this operation.
error:
message: SDCFormMetadata with id = '<resource-id>' is not found
message: There are no such properties [<prop-names>] in FormMetadata with id = '<resource-id>'
get-forms
Get forms definitions
Response can be narrowed with document Symbol name substring
params:
Param
Description
Type
required?
q
substring of Form symbolic name
String
no
include.properties
include-filter for properties match
map
no
exclude.properties
exclude-filter for properties match
map
no
include/exclude filter
include/exclude properties should be in that shape as you except them in Form definition.
if property value is a set - then filter specifies elements subset with AND logic
if property value is a coll - then filter specifies collection matching with strict order and elements counts
if property value is a map - then filter specifies subset of map structure with searched leaves values
if property value is a keyword/string/symbol - then filter specifies equal match by stringified property value.
result:
form: 'box.sdc.sdc-example/VitalsForm' ;; Form name
title: "MyForm" ;; Form title
version: 1 ;; Internal form version.
document: {} ;; SDCDocument resource
document-def: {} ;; Document zen definition (can be used for UI validations)
layout: {} ;; Enriched layout with document metadata and rules. Used for rendering
layout-def: {} ;; Layout zen definition. (can be used for retrieving additional info from layout engine)
rules: {} ;; merged (and optionally transformed) :sdc/rules from document and layout definitions
rules-order: {} ;; Rules keys in topological sort.
finalize-profile: {} ;; Zen Schema for Finalize Constraints
Error:
error:
message: "Wrong population logic for resource defined"
errors: [{message: "..."}] ;; schema validation errors (zen-style errors)
warnings: ;; failed population logic expressions
- message: "..."
launch-ctx {...} ;; context data of the launch process
localion:
expr: <lisp/expr> ;; failed lisp/expr
read-document
Get form for saved document.
Param
Description
Type
required?
id
Document id
String
yes
rules-in-lisp
Return rules as Lisp or AST
boolean
no
POST /rpc?
method: aidbox.sdc/read-document
params:
id: doc-1
Result:
Success
result:
form: 'box.sdc.sdc-example/VitalsForm' ;; Form name
title: "MyForm" ;; Form title
version: 1 ;; Internal form version.
document: {} ;; SDCDocument resource
document-def: {} ;; Document zen definition (can be used for UI validations)
layout: {} ;; Enriched layout with document metadata and rules. Used for rendering
layout-def: {} ;; Layout zen definition. (can be used for retrieving additional info from layout engine)
rules: {} ;; merged (and optionally transformed) :sdc/rules from document and layout definitions
rules-order: {} ;; Rules keys in topological sort.
finalize-profile: {} ;; Zen Schema for Finalize Constraints
Error:
error:
:message "Can't find document"
save
Save document draft without Finalize Profile validations. Can be used with documents in draft, in-progress, in-amendment statuses
Param
Description
Type
required?
document
document resource
SDCDocument
yes
If document in draft status - set in-progress status to it.
result
document: {...} ;; signed document
exported: ;; exported resources (optional)
to-create: [...]
to-update: [...]
to-delete: [...]
Error
error:
message: Document didn't pass sign validations
type: :sdc.error/validation
errors:
- message: More detailsed validation message
...
message: Some of the exported documents are invalid
type: :sdc.error/export
errors:
to-create:
- resource: {...} ;; generated resource by export
export/idx: 0 ;; export position in export list
errors: {...} ;; zen-style validation errors
to-delete:
- resource: {...} ;; generated resource by export
export/idx: 0 ;; export position in export list
errors: {...} ;; zen-style validation errors
to-update:
- resource: {...} ;; generated resource by export
export/idx: 0 ;; export position in export list
errors: {...} ;; zen-style validation errors
aidbox.sdc/convert-document
Converts SDCDocument to QuestionnaireResponse
If you need to have original Questionnaire linkId-s - you should specify :linkId property of the SDCDocument fields. By default field keys are used as linkId.
Also you may choose the output format:
aidbox - to store inside Aidbox DB
fhir - to exchange with other FHIR systems
Optionaly you can save converted QuestionnaireResponse to its resource table via save-to-resource flag
NOTE: If you use save-to-resource = true you should specify format = 'aidbox' only
Params:
Param
Description
Type
required?
id
id of SDCDocument in DB
String
no
document
SDCDocument resource body
Resource
no
format
Output format
"fhir" / "aidbox"
yes
save-to-resource
If true - converts and saves QR to resource
boolean
no
opts
Map
no
opts.include-scores*
If true - include scores from answers to QR
boolean
no
opts.describe-rules*
If true - will add field calculation rule description to QR
boolean
no
to use include-scores and describe-rules options you need to import aidbox.sdc.extra namespace in configuration project
Request:
Example with document stored in DB
POST /rpc
method: aidbox.sdc/convert-document
params:
id: doc-1
format: fhir
Set in-amendment status for Document. Used for document corrections. Should be signed after correction
Can be used only for documents in completed, amended statuses.
Param
Description
Type
required?
id
document id
string
yes
dry-run
Run without saving document and extractions
boolean
no
Additionally will create History SDCAddendum resource with timestamp and user.
Request:
POST /rpc?
method: aidbox.sdc/amend,
params:
id: doc-1,
Response:
Success
result: {...} ;; updated document (the same if it is already in in-amendment status)
Error
error:
message: Resource is not found
message: Can't be amended not in final status (completed/amended): <cur-status>
...
add-note
Add Addendum Note to the given Document. This is the preferred way to add Notes to Documents.
Params:
Param
Description
Type
required?
id
Document id
zen/string
yes
user
Reference to user which adds note
zenbox/Reference
yes
text
Addendum note text
zen/string
yes
Request:
POST /rpc?
method: aidbox.sdc/add-note
params:
id: doc-1
user:
id: user-1
resourceType: User
text: "Temperature measurements are not correct. Should be 100"
Result:
Success
result:
date: '2022-11-11T11:11:10.111Z'
text: Temperature measurements are not correct. Should be 100
type: aidbox.sdc.addendum/Note
user:
id: user-1
resourceType: User
target:
id: doc-1
resourceType: SDCDocument
id: f3989be1-9e6d-4e9e-a9bf-7b52956ea432
resourceType: SDCAddendum
Server responds with HTTP 422 Unprocessable Entity if wrong document id is provided.
POST /rpc?
method: aidbox.sdc/add-note
params:
id: some-unknown-document-id
user:
id: user-1
resourceType: User
text: "Temperature measurements are not correct. Should be 100"
Result:
Error
error:
message: Resource not found
- get form with saved document
- save document
- finalize document, run extracts
- converts SDCDocument to FHIR QuestionnaireResponse
- creates policy token for form
- creates shared form link
- put document to in-amendment state. Used for corrections
- add note as addendum to the given document
To save Questionnaire to resource you should specify :fhir/id property in the
To specify additional fields that are represented in Questionnaire but not in the Form DSL - you can use predefined form properties for that
Creates to get access to SDCDocument/SDCWorkflow
Creates to get access to SDCDocument/SDCWorkflow
Theme that will be applied to form.
See
Use this API (aidbox.sdc/add-note) instead of the low-level
