# Documentation Templates and Rules (DTR)

## What is DTR?

Documentation Templates and Rules (DTR) enables payers to provide electronic questionnaires that gather the clinical and administrative documentation needed for prior authorization, claims processing, or other coverage requirements.

DTR automates data collection by pre-populating questionnaire answers from the provider's Electronic Health Record (EHR) using Clinical Quality Language (CQL) expressions, reducing provider burden.

1upHealth supports DTR as part of the ePA workflow, providing the payer-side `$questionnaire-package` operation for questionnaire retrieval.

**Official specification**: [HL7 Da Vinci Documentation Templates and Rules Implementation Guide](https://build.fhir.org/ig/HL7/davinci-dtr/)

### Supported versions

1upHealth supports the following versions of the HL7 Da Vinci Documentation Templates and Rules Implementation Guide:

* STU 2.0.0


## How DTR works

DTR connects payer documentation requirements to the provider workflow through the following process:

1. **CRD triggers DTR**: A CRD response card indicates documentation is needed and provides a link to launch DTR.
2. **Questionnaire retrieval**: DTR calls `$questionnaire-package` on the payer server to retrieve the questionnaire, CQL libraries, and value sets.
3. **CQL pre-population**: DTR executes CQL expressions against EHR data to auto-fill answers where possible.
4. **User completes form**: The provider reviews pre-populated answers and fills in any remaining fields.
5. **QuestionnaireResponse stored**: The completed response is saved to the EHR as a QuestionnaireResponse FHIR resource.
6. **Sent to PAS**: The saved QuestionnaireResponse is included in the PAS prior authorization request bundle.


**Specifications**:

- [DTR Workflow](https://build.fhir.org/ig/HL7/davinci-dtr/specification.html)
- [DTR Implementation Approaches](https://build.fhir.org/ig/HL7/davinci-dtr/specification.html)


## Key operations

### `$questionnaire-package`

The `$questionnaire-package` FHIR operation retrieves everything needed to render and pre-populate a questionnaire. The response contains the questionnaire, CQL libraries, and value sets needed for a specific coverage requirement.

**Endpoint**: `POST {payer-base}/Questionnaire/$questionnaire-package`

The DTR client receives this URL from the CRD response card via the SMART launch link or form completion suggestion. 1upHealth's intelligent routing engine handles delivering the correct payer's questionnaire content.

**Input parameters**:

| Parameter | [Cardinality](https://build.fhir.org/conformance-rules.html#cardinality) | Description |
|  --- | --- | --- |
| `coverage` | 1..1 | Coverage resource identify the member and coverage type. |
| `order` | 0..* | One or more Order resources that establish context for documentation. |
| `questionnaire` | 0..* | Canonical URLs for specific questionnaires to retrieve. Can be version-specific. |
| `context` | 0..1 | Context ID from the CRD or CDex response, used to determine relevant questionnaires and support pre-population. |
| `changedsince` | 0..1 | If provided, the response only returns questionnaire bundles that have changed since the `changedsince` timestamp. |


At least one of `order`, `questionnaire`, or `context` must be provided in addition to `coverage`.

**Output**: A Parameters resource containing one or more Bundles. Each Bundle includes a Questionnaire, a draft QuestionnaireResponse, CQL Library resources, and ValueSet resources. This output is consumed by the DTR client to render the form — it is not persisted to the EHR. The *completed* QuestionnaireResponse (after the provider fills in remaining fields) is what gets saved to the EHR.

**Specification**: [$questionnaire-package Operation](https://build.fhir.org/ig/HL7/davinci-dtr/OperationDefinition-questionnaire-package.html)

### `$next-question`

Planned for support
The `$next-question` operation is not currently supported.

The `$next-question` operation is used for adaptive questionnaires to retrieve subsequent questions based on previous answers.

**Endpoint**: `POST {payer-base}/Questionnaire/$next-question`

**Input**: A QuestionnaireResponse FHIR resource containing the current answers.

**Output**: A QuestionnaireResponse FHIR resource with the next questions appended.

**Specification**: [$next-question Operation](https://build.fhir.org/ig/HL7/davinci-dtr/OperationDefinition-DTR-Questionnaire-next-question.html)

## Questionnaire types

DTR supports two types of questionnaires: standard and adaptive.

### Standard questionnaire

All questions are defined upfront in the Questionnaire resource. The full form is rendered at once and CQL expressions pre-populate all applicable fields.

**Use case**: Documentation requirements are well-defined and consistent (e.g. Home Oxygen Therapy certification).

**Profile**: [DTR Standard Questionnaire](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-dtr-std-questionnaire.html)

### Adaptive questionnaire

Questions are delivered dynamically one at a time (or in small groups) via the `$next-question` operation. Each answer may change which questions come next.

**Use case**: Complex decision trees where subsequent questions depend on prior answers (e.g., multi-branch clinical assessments).

**Profile**: [DTR Adaptive Questionnaire](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-dtr-questionnaire-adapt.html)

## FHIR resource profiles

### DTR questionnaire profiles

- [DTR Standard Questionnaire Profile](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-dtr-std-questionnaire.html): Includes CQL expressions for pre-population, enableWhen logic, and validation rules
- [DTR Adaptive Questionnaire Profile](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-dtr-questionnaire-adapt.html): Used with `$next-question` for dynamic question flow


### DTR QuestionnaireResponse

- [DTR QuestionnaireResponse Profile](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-dtr-questionnaireresponse.html): Contains completed answers, pre-population origin tracking, and references to the source Questionnaire


### DTR bundles

- [DTR Questionnaire Package Bundle](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-DTR-QPackageBundle.html): Output contains Questionnaire, CQL Libraries, and ValueSets
- [DTR QuestionnaireResponse Bundle](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-DTR-QRBundle.html): Bundle of QuestionnaireResponse resources for storage or submission


See [all DTR resource profiles](https://build.fhir.org/ig/HL7/davinci-dtr/artifacts.html#structures-resource-profiles)

## Pre-population with CQL

DTR uses [Clinical Quality Language (CQL)](https://cql.hl7.org/) to automatically extract data from the EHR and fill in questionnaire answers.

**How it works:**

1. Each questionnaire item can include a CQL expression via the `cqf-expression` extension.
2. DTR executes CQL against the EHR's FHIR data (Patient, Condition, Observation, etc.).
3. Results are mapped to the corresponding questionnaire answer fields.
4. The `information-origin` extension on each answer tracks whether data was auto-populated or manually entered.


**Data access**: CQL expressions query the EHR's FHIR endpoint (e.g., `https://your-ehr.example.com/fhir/r4`) using the FHIR base URL and access token provided to the DTR app during the SMART on FHIR launch sequence. This is the provider system's own FHIR server — separate from the `$questionnaire-package` operation, which calls the payer side.

**Specification**: [DTR Pre-Population](https://build.fhir.org/ig/HL7/davinci-dtr/specification.html)

## DTR extensions

| Extension | Purpose | Specification |
|  --- | --- | --- |
| `information-origin` | Tracks the source of each answer (auto-populated, manual, override). | [Spec](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-information-origin.html) |
| `coverage-information` | Carries CRD coverage assertion data into the DTR context. | [Spec](https://build.fhir.org/ig/HL7/davinci-crd/StructureDefinition-ext-coverage-information.html) |
| `intendedUse` | Indicates the purpose of the questionnaire (prior-auth, claim, order). | [Spec](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-intendedUse.html) |
| `qr-context` | Links the QuestionnaireResponse to the order or encounter that triggered it. | [Spec](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-qr-context.html) |
| `qr-coverage` | Associates the QuestionnaireResponse with the relevant Coverage resource | [Spec](https://build.fhir.org/ig/HL7/davinci-dtr/StructureDefinition-qr-coverage.html) |


## Launch contexts

DTR can be launched in several ways:

### CRD-triggered

- CRD-triggered is the most common launch context flow.
- CRD returns a card with a SMART app link or form completion suggestion.
- DTR receives the order context and coverage information from the CRD response.
- [Specification](https://build.fhir.org/ig/HL7/davinci-dtr/specification.html)


### PAS-triggered

- When a PAS submission is pended (placed in a pending state awaiting further review) and additional documentation is requested.
- DTR launches with context from the pended ClaimResponse.
- [Specification](https://build.fhir.org/ig/HL7/davinci-dtr/specification.html)


### Stand-alone

- Provider launches DTR directly without a prior CRD or PAS interaction.
- Must manually select the payer, coverage, and order context.
- [Specification](https://build.fhir.org/ig/HL7/davinci-dtr/specification.html)