Da Vinci DTR

Aidbox Forms supports $questionnaire-package operation from the Da Vinci Documentation Templates and Rules (DTR) Implementation Guide .

Overview

The $questionnaire-package operation retrieves a Questionnaire along with all of its dependencies (ValueSets) and a pre-populated draft QuestionnaireResponse, packaged together in a single Bundle. This is useful for Documentation Templates and Rules (DTR) applications that need to collect information for prior authorization or other payer requirements.

Specification: OperationDefinition-questionnaire-package

Current Limitations

The current implementation supports a subset of the full Da Vinci DTR specification:

• Single Questionnaire flow only - The canonical parameter is used to request a specific Questionnaire
• No CQL Library support - CQL libraries referenced by the Questionnaire are not included in the bundle
• No context parameter - The CRD context ID parameter is not yet supported
• No changedsince parameter - Incremental updates based on timestamp are not supported

Endpoints

The operation is available at the following endpoints:

Input Parameters

The operation accepts a FHIR Parameters resource with the following parameters:

Launch Context

The coverage and order parameters are passed to the populate operation as launch context variables, making them available in FHIRPath expressions:

• %coverage - The Coverage resource
• %order - The order resource (ServiceRequest, MedicationRequest, etc.)

Output Parameters

The operation returns a FHIR Parameters resource with:

Package Bundle Structure

The packagebundle is a FHIR Bundle of type collection with entries in the following order:

1. 1.
   Questionnaire - The requested Questionnaire resource (first entry)
2. 2.
   ValueSets - Pre-expanded ValueSets referenced by answerValueSet (middle entries)
3. 3.
   QuestionnaireResponse - A draft (status: in-progress) QuestionnaireResponse (last entry)

ValueSet Handling

• ValueSets are expanded using the $expand operation
• Only ValueSets with 40 or fewer concepts are included in the bundle
• ValueSets with more than 40 concepts are excluded, and an informational message is added to the outcome
• If a ValueSet cannot be expanded, a warning is added to the outcome

Examples

Basic Request

Retrieve a questionnaire package by canonical URL:

POST /fhir/Questionnaire/$questionnaire-package
content-type: text/yaml
accept: text/yaml

resourceType: Parameters
parameter:
- name: canonical
  valueCanonical: http://example.org/Questionnaire/prior-auth-form|1.0

Request with Coverage

Include coverage to set the QuestionnaireResponse subject:

POST /fhir/Questionnaire/$questionnaire-package
content-type: text/yaml
accept: text/yaml

resourceType: Parameters
parameter:
- name: canonical
  valueCanonical: http://example.org/Questionnaire/prior-auth-form|1.0
- name: coverage
  resource:
    resourceType: Coverage
    id: coverage-123
    status: active
    beneficiary:
      reference: Patient/patient-456
    payor:
    - reference: Organization/payer-789

Request with Coverage and Order

Include both coverage and order for full context in population expressions:

POST /fhir/Questionnaire/$questionnaire-package
content-type: text/yaml
accept: text/yaml

resourceType: Parameters
parameter:
- name: canonical
  valueCanonical: http://example.org/Questionnaire/prior-auth-form|1.0
- name: coverage
  resource:
    resourceType: Coverage
    id: coverage-123
    status: active
    beneficiary:
      reference: Patient/patient-456
- name: order
  resource:
    resourceType: ServiceRequest
    id: order-789
    status: active
    intent: order
    code:
      coding:
      - system: http://example.org/procedures
        code: '12345'
        display: Medical Procedure
    subject:
      reference: Patient/patient-456

Successful Response

resourceType: Parameters
parameter:
- name: packagebundle
  resource:
    resourceType: Bundle
    type: collection
    entry:
    - resource:
        resourceType: Questionnaire
        id: prior-auth-form
        url: http://example.org/Questionnaire/prior-auth-form
        version: '1.0'
        status: active
        item:
        - linkId: diagnosis
          type: choice
          text: Primary Diagnosis
          answerValueSet: http://example.org/ValueSet/diagnosis-codes
    - resource:
        resourceType: ValueSet
        url: http://example.org/ValueSet/diagnosis-codes
        expansion:
          contains:
          - system: http://hl7.org/fhir/sid/icd-10
            code: J06.9
            display: Acute upper respiratory infection
    - resource:
        resourceType: QuestionnaireResponse
        questionnaire: http://example.org/Questionnaire/prior-auth-form|1.0
        status: in-progress
        subject:
          reference: Patient/patient-456
        item:
        - linkId: diagnosis
          text: Primary Diagnosis

Response with Warnings

When some ValueSets cannot be included:

resourceType: Parameters
parameter:
- name: packagebundle
  resource:
    resourceType: Bundle
    type: collection
    entry:
    - resource:
        resourceType: Questionnaire
        id: prior-auth-form
    - resource:
        resourceType: QuestionnaireResponse
        questionnaire: http://example.org/Questionnaire/prior-auth-form|1.0
        status: in-progress
- name: outcome
  resource:
    resourceType: OperationOutcome
    issue:
    - severity: information
      code: too-costly
      diagnostics: 'ValueSet too large to embed (>40 concepts): http://example.org/ValueSet/large-codes'
    - severity: warning
      code: not-found
      diagnostics: 'ValueSet expansion failed: http://example.org/ValueSet/unknown-codes'

Error Response - Missing Parameter

resourceType: OperationOutcome
issue:
- severity: error
  code: required
  diagnostics: 'Missing required parameter: canonical'

Error Response - Questionnaire Not Found

resourceType: OperationOutcome
issue:
- severity: error
  code: not-found
  diagnostics: 'Questionnaire not found: http://example.org/Questionnaire/unknown'

Using Population Expressions

Questionnaires can include population expressions that reference the launch context. For example:

resourceType: Questionnaire
url: http://example.org/Questionnaire/with-population
item:
- linkId: coverage-id
  type: string
  text: Coverage ID
  extension:
  - url: http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression
    valueExpression:
      language: text/fhirpath
      expression: '%coverage.id'
- linkId: order-status
  type: string
  text: Order Status
  extension:
  - url: http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression
    valueExpression:
      language: text/fhirpath
      expression: '%order.status'
- linkId: patient-name
  type: string
  text: Patient Name
  extension:
  - url: http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-initialExpression
    valueExpression:
      language: text/fhirpath
      expression: '%subject.name.first().given.first()'

When this questionnaire is requested with coverage and order parameters, the QuestionnaireResponse will have pre-populated answers:

resourceType: QuestionnaireResponse
status: in-progress
subject:
  reference: Patient/patient-456
item:
- linkId: coverage-id
  answer:
  - valueString: coverage-123
- linkId: order-status
  answer:
  - valueString: active
- linkId: patient-name
  answer:
  - valueString: John

Related Resources

• Da Vinci DTR Implementation Guide
• SDC $populate Operation
• FHIR Questionnaire Resource