Cumuluz Translate Implementation Guide
0.1.0 - ci-build

Cumuluz Translate Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

QuestionnaireResponse

QuestionnaireResponse

Endpoint

POST /fhir/$extract-questionnaire-response

This operation extracts clinical resources from a completed FHIR QuestionnaireResponse.

It is separate from POST /fhir/stu3-r4/$transform because a form response is not one source profile being converted into one target profile. One completed QuestionnaireResponse can produce a Bundle containing multiple clinical resources.

The operation definition is available at:

GET /fhir/OperationDefinition/extract-questionnaire-response

Supported Questionnaires

The operation is generic at the API level, but support is definition-based. Each supported questionnaire family must register its questionnaire canonicals, normalization maps, extraction map, and target materialization rules.

The currently registered extraction definition supports these PZP ACP Questionnaires:

QuestionnaireResponse version Questionnaire canonical
STU3 https://api.iknl.nl/docs/pzp/stu3/Questionnaire/ACP-zib2017
R4 https://api.iknl.nl/docs/pzp/r4/Questionnaire/ACP-zib2020

The route uses meta.profile or questionnaire to parse the QuestionnaireResponse as STU3 or R4. The registered extraction definition then uses the questionnaire canonical to choose the normalization map.

Request Resource

The request body is a FHIR Parameters resource.

Name Type Meaning
questionnaireResponse QuestionnaireResponse Completed supported STU3 or R4 form response
validate boolean When true, validate the produced R4 Bundle entries

Minimal request shape:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "questionnaireResponse",
      "resource": {
        "resourceType": "QuestionnaireResponse",
        "questionnaire": "https://api.iknl.nl/docs/pzp/r4/Questionnaire/ACP-zib2020",
        "status": "completed"
      }
    },
    {
      "name": "validate",
      "valueBoolean": true
    }
  ]
}

Response Resource

On success, the response body is a FHIR Parameters resource.

Name Type Meaning
result Bundle R4 Bundle containing extracted clinical resources
outcome OperationOutcome Extraction diagnostics and optional validation output

The HTTP status is 200 when the outcome has no error or fatal issues. The HTTP status is 400 when extraction or validation produces an error or fatal issue.

The OperationOutcome can include:

  • validation issues for generated Bundle entries when validate=true
  • diagnostics for QuestionnaireResponse answers that are present but not mapped to a target resource
  • informational diagnostics for normalized answers that are intentionally not materialized because there is no safe target resource

How Extraction Works

The extraction path has four explicit stages:

  1. Normalize the version-specific form into LogicalQuestionnaireForm.
  2. Use LogicalQuestionnaireFormToExtractionBundle.map to create the extraction entries and logical clinical resource bodies that are safe to materialize.
  3. Validate the extraction manifest shape and supported entry kinds.
  4. Transform the materialized logical resources through the configured logical-to-target StructureMaps.

LogicalQuestionnaireForm is intentionally generic: it contains repeated named answers and grouped telecom answers, not ACP-specific fields. The PZP ACP maps own the interpretation from ACP linkIds to those names and from named answers to PZP clinical resources.

The normalization maps are:

  • src/main/resources/mappings/structuremaps/pzp-questionnaire/Pzp2017QuestionnaireResponseToLogicalQuestionnaireForm.map
  • src/main/resources/mappings/structuremaps/pzp-questionnaire/Pzp2020QuestionnaireResponseToLogicalQuestionnaireForm.map

The extraction-decision map is:

  • src/main/resources/mappings/structuremaps/pzp-questionnaire/LogicalQuestionnaireFormToExtractionBundle.map

Local ConceptMaps under src/main/resources/mappings/conceptmaps handle questionnaire-specific code normalization, default codings, UZI specialty normalization, treatment directive choices, contact-point use, boolean answers, and observation methods.

Normalized answer logical models use the shared sourceLinkId, stringValue, booleanValue, and coding shape. StructureMaps read those logical fields directly, use normal where guards for supported or skipped entries, and use ConceptMap-backed translate(...) rules for coded target values.

What This Operation Is Not

This operation is not a free-form QuestionnaireResponse converter.

It only supports registered extraction definitions. At the moment that means the installed PZP ACP form shapes listed above. Other questionnaires should fail clearly rather than being partially interpreted as PZP resources.

It is also not a replacement for the profile-pair transform operation. Use $transform when the input is already a supported PZP 2017 ACP resource profile. Use $extract-questionnaire-response when the input is a completed PZP ACP form response.

Validation

The installed R4 PZP Questionnaire and QuestionnaireResponse examples are loaded as validation context. R4 QuestionnaireResponses can also be validated directly through POST /fhir/r4/$validate.

Validation of generated PZP 2020 resources is requested with the extraction validate parameter. PZP target resources can also be validated later through the generic R4 validation endpoint by passing the target profile explicitly.