Aidbox SDC API

Custom SDC operations supported by Aidbox Forms.

• $generate-link

• $save

• $submit

Generate a link to a QuestionnaireResponse - $generate-link

This operation generates a link to a web page to be used to continue answering a specified QuestionnaireResponse.

URLs

POST [base]/QuestionnaireResponse/[id]/$generate-link

Parameters

NOTE: All parameters wrapped with Parameters object

resourceType: Parameters
parameter:
- name:  [var-name]
  value: [var-value]

Parameter	Cardinality	Type
allow-amend	0..1	Boolean
allow-repopulate	0..1	Boolean
redirect-on-submit	0..1	String
redirect-on-save	0..1	String
expiration	0..1	Integer
theme	0..1	String
read-only	0..1	Boolean
app-name	0..1	String
source		Reference<Device, Organization, Patient, Practitioner, PractitionerRole, RelatedPerson>
partOf		Reference<Observation, Procedure>
author		Reference<Device, Practitioner, PractitionerRole, Patient, RelatedPerson, Organization>
basedOn		Reference<CarePlan, ServiceRequest>

allow-amend

Whether the generated link will allow amending and re-submitting the form.

name: allow-amend
value:
  Boolean: true

allow-repopulate

Whether the generated link will allow re-populating the form.

NOTE: Repopulate will be working only with forms that contain populate behavior

name: allow-repopulate
value:
  Boolean: true

redirect-on-submit

A URL where the user will be redirected to after successfully submitting the form.

name: redirect-on-submit
value:
  String: https://example.com/submit-hook?questionnaire=123

redirect-on-save

A URL where the user will be redirected to after hitting Save button.

By default Save button is not visible - form autosaved after every keystroke. But sometimes it's usefull to close form in a partially-filled state

name: redirect-on-save
value:
  String: https://example.com/submit-hook?questionnaire=123

expiration

Link expiration period (days)

name: expiration
value:
  Integer: 30

By default thir parameter = 7 days

theme

Form theme.

name: theme
value:
  String: hs-theme

read-only

Show form in a read-only mode

name: read-only
value:
  Boolean: true

app-name

Application name that will be used in Audit logging when returned link was used.

Audit logging should be enabled.

- name: app-name
  value
    String: my-app

Usage Example

Request

POST [base]/QuestionnaireResponse/[id]/$generate-link
content-type: text/yaml

resourceType: Parameters
parameter:
  - name: allow-amend
    value:
      Boolean: true
  - name: redirect-on-submit
    value:
      String: https://example.com/submit-hook?questionnaire=123

Success Response

HTTP status: 200

link: http://forms.aidbox.io/ui/sdc#/questionnaire-response/12c1178c-70a9-4e02-a53d-65b13373926e?token=eyJhbGciOiJIUzI

Failure Response

HTTP status: 422

resourceType: OperationOutcome
text:
  status: generated
  div: Parameters are invalid
issue:
- severity: error
  code: invalid
  expression:
  - parameter.0.resource
  diagnostics: unknown key :resource

Aidbox uses HS256 to sign JWT token by default. To use RS256 you need to set

BOX_AUTH_KEYS_PRIVATE and BOX_AUTH_KEYS_PUBLIC environment variables.

See settings

Save a QuestionnaireResponse - $save

This operation validates the structure of a QuestionnaireResponse and saves it. It performs basic structural validation, but does not validate against the associated Questionnaire definition.

The operation validates only FHIR structure of QuestionnaireResponse and have associated Questionnaire. Operation doesn't validate for example — required fields like $submit operation

URLs

POST [base]/fhir/QuestionnaireResponse/$save

Parameters

NOTE: All parameters wrapped with Parameters object

resourceType: Parameters
parameter:
- name: response
  resource: 
    # QuestionnaireResponse resource here

The operation takes a single input parameter named "response" containing a QuestionnaireResponse resource wrapped in a Parameters resource.

Output Parameters

The operation returns:

• response: The saved QuestionnaireResponse resource

• issues: Any validation issues encountered (if applicable)

Usage Example

Request

POST [base]/fhir/QuestionnaireResponse/$save
content-type: application/json
accept: application/json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "response",
      "resource": {
        "resourceType": "QuestionnaireResponse",
        "questionnaire": "Questionnaire/patient-registration",
        "status": "in-progress",
        "item": [
          {
            "linkId": "name",
            "text": "Patient Name",
            "item": [
              {
                "linkId": "name.given",
                "text": "Given Name",
                "answer": [
                  {
                    "valueString": "John"
                  }
                ]
              },
              {
                "linkId": "name.family",
                "text": "Family Name",
                "answer": [
                  {
                    "valueString": "Smith"
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  ]
}

Success Response

HTTP status: 200

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "response",
      "resource": {
        "resourceType": "QuestionnaireResponse",
        "id": "12c1178c-70a9-4e02-a53d-65b13373926e",
        "questionnaire": "Questionnaire/patient-registration",
        "status": "in-progress",
        "item": [
          {
            "linkId": "name",
            "text": "Patient Name",
            "item": [
              {
                "linkId": "name.given",
                "text": "Given Name",
                "answer": [
                  {
                    "valueString": "John"
                  }
                ]
              },
              {
                "linkId": "name.family",
                "text": "Family Name",
                "answer": [
                  {
                    "valueString": "Smith"
                  }
                ]
              }
            ]
          }
        ]
      }
    }
  ]
}

Validation Failure Response

HTTP status: 422

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "response",
      "resource": {
        "resourceType": "QuestionnaireResponse",
        "id": "12c1178c-70a9-4e02-a53d-65b13373926e",
        "questionnaire": "Questionnaire/patient-registration",
        "status": "in-progress",
        "item": [
          {
            "linkId": "name",
            "text": "Patient Name",
            "item": [
              {
                "linkId": "name.given",
                "text": "Given Name",
                "answer": [
                  {
                    "valueString": "John"
                  }
                ]
              },
              {
                "linkId": "name.family",
                "text": "Family Name",
                "answer": [
                  {
                    "valueDecimal": "1,324"
                  }
                ]
              }
            ]
          }
        ]
      }
    },
    "issue": [
     {
      "severity": "fatal",
      "code": "invalid",
      "expression": [
       "QuestionnaireResponse.item[0].item[1].answer[0].valueDecimal"
      ],
      "details": {
       "coding": [
        {
         "system": "http://aidbox.app/CodeSystem/operation-outcome-type",
         "code": "invalid-type"
        },
        {
         "system": "http://aidbox.app/CodeSystem/schema-id",
         "code": "QuestionnaireResponse"
        }
       ]
      },
      "diagnostics": "Invalid type for the field. Expected 'string', but got 'decimal'"
     }
    }
  ]
}

Submit a QuestionnaireResponse - $submit

This operation validates and submits a QuestionnaireResponse, marking it as "completed" or "amended". It performs comprehensive validation against the associated Questionnaire definition. If validation fails, it returns only the "issues" parameter without the "response" parameter and does not save the QuestionnaireResponse.

URLs

POST [base]/fhir/QuestionnaireResponse/$submit

Parameters

NOTE: All parameters wrapped with Parameters object

resourceType: Parameters
parameter:
- name: response
  resource: 
    # QuestionnaireResponse resource here

The operation takes a single input parameter named "response" containing a QuestionnaireResponse resource wrapped in a Parameters resource.

Output Parameters

The operation returns:

• response: The submitted QuestionnaireResponse resource with status updated to "completed"

• issues: Any validation issues encountered (if applicable)

Usage Example

Request

POST [base]/fhir/QuestionnaireResponse/$submit
content-type: application/fhir+json

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "response",
      "resource": {
        "resourceType": "QuestionnaireResponse",
        "questionnaire": "Questionnaire/patient-registration",
        "status": "in-progress",
        "item": [
          {
            "linkId": "name",
            "text": "Patient Name",
            "item": [
              {
                "linkId": "name.given",
                "text": "Given Name",
                "answer": [
                  {
                    "valueString": "John"
                  }
                ]
              },
              {
                "linkId": "name.family",
                "text": "Family Name",
                "answer": [
                  {
                    "valueString": "Smith"
                  }
                ]
              }
            ]
          },
          {
            "linkId": "birthDate",
            "text": "Date of Birth",
            "answer": [
              {
                "valueDate": "1970-01-01"
              }
            ]
          },
          {
            "linkId": "gender",
            "text": "Gender",
            "answer": [
              {
                "valueCoding": {
                  "system": "http://hl7.org/fhir/administrative-gender",
                  "code": "male",
                  "display": "Male"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

Success Response

HTTP status: 200

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "response",
      "resource": {
        "resourceType": "QuestionnaireResponse",
        "id": "12c1178c-70a9-4e02-a53d-65b13373926e",
        "questionnaire": "Questionnaire/patient-registration",
        "status": "completed",
        "item": [
          {
            "linkId": "name",
            "text": "Patient Name",
            "item": [
              {
                "linkId": "name.given",
                "text": "Given Name",
                "answer": [
                  {
                    "valueString": "John"
                  }
                ]
              },
              {
                "linkId": "name.family",
                "text": "Family Name",
                "answer": [
                  {
                    "valueString": "Smith"
                  }
                ]
              }
            ]
          },
          {
            "linkId": "birthDate",
            "text": "Date of Birth",
            "answer": [
              {
                "valueDate": "1970-01-01"
              }
            ]
          },
          {
            "linkId": "gender",
            "text": "Gender",
            "answer": [
              {
                "valueCoding": {
                  "system": "http://hl7.org/fhir/administrative-gender",
                  "code": "male",
                  "display": "Male"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

Validation Failure Response

HTTP status: 422

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "issues",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          {
            "severity": "error",
            "code": "required",
            "expression": ["QuestionnaireResponse.item[3]"],
            "diagnostics": "Missing required field: Contact Information"
          }
        ]
      }
    }
  ]
}