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.
This RPC don't have any paramerters.
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
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'
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
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
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