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 Extraction

QuestionnaireResponse Extraction

Endpoint

POST /fhir/$extract-questionnaire-response

Use this operation when the input is a completed supported form. It is separate from $transform because one form can produce multiple target clinical resources.

Current Support

The operation is generic at the API level, but extraction is definition-based.

Currently registered questionnaires:

Form 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

Other QuestionnaireResponses are rejected instead of being partially interpreted as PZP resources.

Request Parameters

The request body is a FHIR Parameters resource.

Name Required Type Meaning
questionnaireResponse yes QuestionnaireResponse completed supported STU3 or R4 form
validate no boolean validate produced R4 Bundle entries

Minimal request:

{
  "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 Parameters

Name Type Meaning
result Bundle extracted R4 clinical resources
outcome OperationOutcome extraction diagnostics and optional validation diagnostics

HTTP 200 means extraction completed without error or fatal issues. HTTP 400 means extraction or validation produced an error or fatal issue, or the request could not be processed.

Extraction Pipeline

Step What happens
Normalize form version-specific StructureMap converts form answers into LogicalQuestionnaireForm
Select entries extraction map decides which logical clinical resources can be materialized
Materialize resources logical resources are sent through existing logical-to-PZP target maps
Validate generated R4 resources are validated when validate=true

Key maps:

Purpose Map
STU3 form normalization src/main/resources/mappings/structuremaps/pzp-questionnaire/Pzp2017QuestionnaireResponseToLogicalQuestionnaireForm.map
R4 form normalization src/main/resources/mappings/structuremaps/pzp-questionnaire/Pzp2020QuestionnaireResponseToLogicalQuestionnaireForm.map
extraction decisions src/main/resources/mappings/structuremaps/pzp-questionnaire/LogicalQuestionnaireFormToExtractionBundle.map

Concept Translation In Extraction

Questionnaire extraction uses local ConceptMaps for answer normalization and target coding.

Examples:

  • answer-to-boolean conversion
  • treatment directive choice mapping
  • medical policy goal mapping
  • observation method mapping
  • contact-point use mapping
  • UZI specialty normalization
  • default codings for generated resources

See Concept Translation.

Boundary

Use $transform when the input is already a supported PZP 2017 ACP resource profile.

Use $extract-questionnaire-response when the input is a completed supported ACP QuestionnaireResponse.