Populate a Questionnaire

Populate a FHIR QuestionnaireResponse using a saved Questionnaire, its patient context, and optional values supplied by the caller. Questionnaire variables and calculated expressions can fetch or derive values while the response is assembled.

Method	Path
POST	/fhir/R4/Questionnaire/:id/$populate

Replace :id with the id of a Questionnaire already available in the project. The Questionnaire can define FHIR Structured Data Capture variables, a patient launchContext, and calculated-expression extensions. For example, a variable can query the latest height Observation for the active patient; a calculated expression can use height and weight answers to populate a BMI item.

Request

The request body is a FHIR Parameters resource. Use context to pass named application data and response to provide an in-progress response with answers that should be retained or used in calculations.

curl --request POST \
  --url "https://api.sandbox.ovok.com/fhir/R4/Questionnaire/${QUESTIONNAIRE_ID}/\$populate" \
  --header "Authorization: Bearer ${OVOK_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data @populate-parameters.json

Example populate-parameters.json:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "context",
      "part": [
        {
          "name": "name",
          "valueString": "myCustomVariableName"
        },
        {
          "name": "content",
          "resource": {
            "myCustomDataKey": "myCustomDataValue"
          }
        }
      ]
    },
    {
      "name": "response",
      "resource": {
        "resourceType": "QuestionnaireResponse",
        "status": "in-progress",
        "item": [
          {
            "linkId": "bmi-calculation",
            "item": [
              {
                "linkId": "patient-height",
                "answer": [{ "valueDecimal": 175 }]
              },
              {
                "linkId": "patient-weight",
                "answer": [{ "valueDecimal": 100 }]
              }
            ]
          }
        ]
      }
    }
  ]
}

• The outer Parameters resource carries inputs to the operation.
• A context parameter has part entries: name identifies the variable, and content carries its value. Questionnaire expressions can access it through %context.<name>.
• The response parameter contains an initial QuestionnaireResponse. Its item and answer elements provide existing answers; Questionnaire expressions can reference them while calculating new answers.
• linkId values connect response items to the corresponding items in the saved Questionnaire.

Successful response

The Alpha reference shows a generated QuestionnaireResponse example and also documents a Parameters response schema that wraps the response under parameter[name=response].resource. The schema example is shown here; inspect the returned resourceType and wrapper when integrating with a particular deployment.

Response path	Example	Meaning
resourceType	Parameters	FHIR wrapper for the operation output.
parameter[name=response].resource.resourceType	QuestionnaireResponse	Generated response resource inside the named output parameter.
...resource.status	in-progress	Status of the populated response.
...resource.questionnaire	Questionnaire/<questionnaire-id>|0.1.0	Source Questionnaire canonical URL and optional version.
...resource.subject.reference	Patient/<patient-id>	Patient the answers belong to.
...resource.item[].linkId	bmi-calculation, patient-height, patient-weight, bmi-result	Nested items corresponding to the Questionnaire's structure.
...answer[].valueDecimal	175, 100, 32.7	Supplied or populated answers; calculated answers can be filled from Questionnaire expressions.
...resource.meta.profile[]	http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaireresponse	QuestionnaireResponse profile used by the implementation, when present.

The QuestionnaireResponse is returned to the caller. Save it with a FHIR create or update request if it should persist in the project.

Responses and errors

HTTP status	Meaning
200	Request succeeded; the result contains the populated response.
400	The request could not be operated on by the server. Check the Parameters body.
401	The resource owner or authorization server denied the request. Check the access token and its permissions.
404	The Questionnaire or a referenced resource could not be found. Check the path id and references.
422	The server could not validate the request or Questionnaire. Check its FHIR structure and expressions.
500	The server encountered an unexpected condition. Retry later or provide the request ID to support.

On error, the operation can return a FHIR OperationOutcome instead of a populated response. Its issue entries describe the failure; exact diagnostics depend on the request and server state.

Source: Alpha API reference: Populate questionnaire.