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

Use POST /fhir/$extract-questionnaire-response when the source is a completed supported ACP form. This operation is separate from $transform: one form can produce multiple R4 clinical resources.

Supported forms

The API shape is generic, but extraction is definition-based. Other questionnaires are rejected rather than partially interpreted.

Request and call

Build the Parameters envelope around a complete supported QuestionnaireResponse. This command reads that resource from completed-acp-questionnaire-response.json:

jq -n --slurpfile response completed-acp-questionnaire-response.json \
  '{
    resourceType: "Parameters",
    parameter: [
      {name: "questionnaireResponse", resource: $response[0]},
      {name: "validate", valueBoolean: true}
    ]
  }' | curl -sS \
    -H 'Accept: application/fhir+json' \
    -H 'Content-Type: application/fhir+json' \
    --data-binary @- \
    'http://localhost:8080/fhir/$extract-questionnaire-response'

The source resource must be completed and contain the required extraction context and answers defined by the selected Questionnaire. A resource containing only the canonical and status is not a successful extraction example.

Success response

HTTP 200 returns R4 Parameters:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "result",
      "resource": {
        "resourceType": "Bundle",
        "type": "collection",
        "entry": []
      }
    },
    {
      "name": "outcome",
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          { "severity": "information", "code": "informational", "diagnostics": "Extraction completed" }
        ]
      }
    }
  ]
}

The returned Bundle contains extracted R4 clinical resources according to the actual answers and an R4 Binary with id QuestionnaireResponse-source. The Binary retains the source QuestionnaireResponse JSON content, including nested and repeated answers, restrictions, notes, and unknown items. Its contentType is application/fhir+json; fhirVersion=3.0 for STU3 or application/fhir+json; fhirVersion=4.0 for R4: the embedded source remains in its original FHIR version. The HTTP operation preserves the JSON content, not request whitespace, property ordering, or other lexical formatting. Internal callers that supply source JSON directly retain that string unchanged; otherwise the parsed source resource is serialized in its original version. The Binary is source evidence, not an independently extracted clinical assertion.

When validate=true, the outcome carries R4 validation diagnostics, including validation of the Binary envelope. Embedded source data is not thereby validated as R4. Clients must inspect issue severities and the non-materialized answer diagnostics before processing Bundle entries.

Treatment-choice, restriction, verification-method/detail, and treatment-note answers do not produce a TreatmentDirective. A completion date, named professional, or discussion answer does not by itself establish the verification and author relationship required for that clinical assertion. Their linkIds remain in the extraction diagnostics as non-materialized, and their original values remain available in the Binary. Extraction therefore provides a partial clinical interpretation with retained source evidence; recognition of every linkId does not establish complete clinical translation.

The maps preserve these questionnaire distinctions explicitly:

• Only an affirmative informed-relatives Boolean answer creates ACP-InformRelativesRequest. A negative answer is retained in the source and reported as non-materialized; it never becomes an affirmative request.
• Changed-agreements yes/no/unknown answers are included in the single AdvanceDirective comment, alongside the earlier-agreements note when present. When no earlier-agreements directive is produced, or the changed-agreements answer is ambiguous, its linkId is reported as non-materialized and its original value remains in the source.
• Repeated legal-representative roles produce separate relationship concepts. Legacy STU3 role codes are aligned to their R4 counterparts. An "other" role or relationship retains the explanatory text nested under its own answer occurrence. Legacy flat text is used only when exactly one matching "other" answer and one description make the association unambiguous; otherwise it is not assigned to a concept, and its linkId is reported as non-materialized.
• Coded attendance roles and relationships without a safe link to a known person are reported as non-materialized and retained in the source. Their presence does not establish which named contact attended.

Failure response

An unsupported questionnaire, malformed request, extraction error, or validation error/fatal returns HTTP 400 with only an R4 OperationOutcome:

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-supported",
      "diagnostics": "Unsupported QuestionnaireResponse questionnaire canonical '<canonical>'"
    }
  ]
}

Extraction model

version-specific QuestionnaireResponse
-> LogicalQuestionnaireForm normalization
-> explicit extraction decisions
-> existing logical-to-PZP target maps
-> retain original version-labelled source JSON as Binary
-> optional R4 validation
-> Bundle + OperationOutcome

ConceptMaps normalize supported answers, treatment choices, observation methods, policy goals, contact-point use and specialty codes. See Mapping Model. Use $transform instead when the input is already a registered PZP clinical resource profile.