Addendum API

• create-addendum

• add-note

• add-to-history

• create-amendment

• add-comment

• get-addendums

create-addendum (WIP)

Creates custom addendum resource for given source (SDCDocument/SDCWorkflow)

Extensible via ZEN

Params:

Param	Description	Type	required?
addendum	Addendum resource	SDCAddendum (without 'date')	yes

Should be used only for custom created(by user) SDCAddendum resources

Request:

POST /rpc?

method: aidbox.sdc.addendum/create-addendum
params:
  addendum:
    type: aidbox.sdc.addendum/Note
    target: 
      id: doc-1
      resourceType: SDCDocument
    user:
      id: user-1
      resourceType: User
    appointment: "2022-10-10T10:10:10.000Z"
    text: "Temperature measuarements are not correct. Should be 100"

Response:

result:
  type: aidbox.sdc.addendum/Note
  id: note-1
  date: "2022-12-12T10:10:10.000Z"
  target: 
    id: doc-1
    resourceType: SDCDocument
  user:
    id: user-1
    resourceType: User
  appointment: "2022-10-10T10:10:10.000Z"
  text: "Temperature measuarements are not correct. Should be 100"

add-note

Creates addendum Note for SDCDocument/SDCWorkflow

Params:

Param	Description	Type	required?
target	reference to target resource	zenbox/Reference	yes
user	reference to user which adds note	zenbox/Reference	yes
text	reference to target resource	zen/string	yes

Should be used for creating Note addendum for SDCDocument/SDCWorkflow

Request:

POST /rpc?

method: aidbox.sdc.addendum/add-note
params:
  target: 
    id: doc-1
    resourceType: SDCDocument
  user:
    id: user-1
    resourceType: User
  text: "Temperature measuarements are not correct. Should be 100"

Response:

result:
  type: aidbox.sdc.addendum/Note
  id: note-1
  date: "2022-12-12T10:10:10.000Z"
  target: 
    id: doc-1
    resourceType: SDCDocument
  user:
    id: user-1
    resourceType: User
  appointment: "2022-10-10T10:10:10.000Z"
  text: "Temperature measuarements are not correct. Should be 100"

add-to-history

Add history addendum for resource for given status. When resource in status 'completed/amended' - snapshot can be saved (if resource is differs)

Params:

Param	Description	Type	required?
resource	resource body	SDCDocument/SDCWorkflow	yes
user	reference to user which adds note	zenbox/Reference	yes

Should be used for storing status changes for SDCDocument/SDCWorkflow.

When status is completed/amended - try find latest complete/amended History resource with snapshot and checks is resource different - if so - ads snapshot field to new History addendum

Request:

POST /rpc?

method: aidbox.sdc.addendum/add-to-history
params:
  resource: 
     id: doc-1,
     patient: {id: pt-1, resourceType: Patient},
     encounter: {id: enc-1, resourceType: Encounter},
     type: box.sdc.sdc-example/VitalsDocument,
     resourceType: SDCDocument,
     status: "completed"
     loinc-59408-5: {value: 97},
     author: {id: doc-1, resourceType: User},
     loinc-8310-5: {value: 36.6, unit: C},
     loinc-8867-4: {value: 72}
  user:
    id: user-1
    resourceType: User

Response:

result:
  type: aidbox.sdc.addendum/History
  id: note-1
  date: "2022-12-12T10:10:10.000Z"
  target: 
    id: doc-1
    resourceType: SDCDocument
  user:
    id: user-1
    resourceType: User
  changed: true
  snapshot: 
     id: doc-1,
     patient: {id: pt-1, resourceType: Patient},
     encounter: {id: enc-1, resourceType: Encounter},
     type: box.sdc.sdc-example/VitalsDocument,
     resourceType: SDCDocument,
     status: "completed"
     loinc-59408-5: {value: 97},
     author: {id: doc-1, resourceType: User},
     loinc-8310-5: {value: 36.6, unit: C},
     loinc-8867-4: {value: 72}

create-amendment

Finds History addendums for given target and try generate Amendment report - which contains difference between 2 latest snapshots of that resource.

Params:

Param	Description	Type	required?
target	reference to resource with History addendums	SDCDocument/SDCWorkflow	yes
user	reference to user which adds note	zenbox/Reference	yes

Should be used for compute diff for two latest History snapshots of SDCDocument/SDCWorkflow and created Addendum resource for it.

If there are less than 2 History addendums with completed/ammended status and with snapshot - Amendment should not be created.

Difference is array of diff objects

Diff object is a map of keys

key	type
type	change operation type	"remove"/"replace"/"add"
path	path of change	vector of strings
old	old value (if exists)	zen/string? (optional)
new	new value (if exitts)	zen/string (optional)

Request:

POST /rpc?

method: aidbox.sdc.addendum/create-amendment
params:
  target: 
     id: doc-1,
     resourceType: SDCDocument,
  user:
    id: user-1
    resourceType: User

Response:

result:
  type: aidbox.sdc.addendum/Amendment
  id: a-1
  date: "2022-12-12T10:10:10.000Z"
  user:
    id: user-1
    resourceType: User
  target: 
    id: doc-1
    resourceType: SDCDocument
  old-revision:
    id: "a-1"
    resourceType: "SDCAddendum",
  new-revision: 
    id "a-2"
    resourceType: "SDCAddendum",
  diff: 
    - type: remove
      path: ["loinc-8867-4" "value"]
      old 72
    - type: add
      path: ["loinc-59408-5" "value"]
      new: 41
    - type: replace
      path: ["loinc-8310-5" "value"]
      old: 90
      new: 97

add-comment

Add comment for docuement/workflow with optional path to commented value in resource

Params:

Param	Description	Type	required?
target	reference to target resource	zenbox/Reference	yes
user	reference to user which adds note	zenbox/Reference	yes
path	path to commented value in resource	vector of strings	no
text	reference to target resource	zen/string	yes

Should be used for creating Comment addendum for SDCDocument/SDCWorkflow

Request:

POST /rpc?

method: aidbox.sdc.addendum/add-comment
params:
  target: 
    id: doc-1
    resourceType: SDCDocument
  user:
    id: user-1
    resourceType: User
  path: ["loinc-59408-5" "value"]
  text: "Temperature measuarements are not correct. Should be 100"

Response:

result:
  type: aidbox.sdc.addendum/Comment
  id: note-1
  date: "2022-12-12T10:10:10.000Z"
  target: 
    id: doc-1
    resourceType: SDCDocument
  user:
    id: user-1
    resourceType: User
  path: ["loinc-59408-5" "value"]
  text: "Temperature measuarements are not correct. Should be 100"

It's looks like Comment similar to Note - but semantically they are different. Comment should not releated to status of SDCDocument/SDCWorkflow and used for informal conversations, which doesn't have any legal force. Note should be used for SDCDocument/SDCWorkflow in completed/amended statuses.

get-addendums

Returns collection of addendums for the given target resource.

Params:

Param	Description	Type	required?
target	reference to target resource	zenbox/Reference	yes

Request:

POST /rpc?

method: aidbox.sdc.addendum/get-addendums
params:
  target:
    id: doc-1
    resourceType: SDCDocument

Response:

result:
  - date: '2022-10-01T12:00:00.000Z'
    meta: ...
    type: aidbox.sdc.addendum/History
    resourceType: SDCAddendum
    snapshot: ...
    status: completed
    id: 039455f7-ed08-4462-90a6-14b5b679d728
    changed: true
    target:
      id: doc-1
      resourceType: SDCDocument
    user: ...

Server responds with HTTP 422 Unprocessable Entity if wrong target is provided.

Request:

POST /rpc?

method: aidbox.sdc.addendum/get-addendums
params:
    target:
        id: some-unknown-doc-id
        resourceType: SDCDocument

Result:

Error

error:
  message: Resource not found