Da Vinci - Documentation Templates and Rules
2.2.0 - STU 2.2

Da Vinci - Documentation Templates and Rules, published by HL7 International / Clinical Decision Support. This guide is not an authorized publication; it is the continuous build for version 2.2.0 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/davinci-dtr/ and changes regularly. See the Directory of published versions

## Change History

Page standards status: Informative | Highlight text changes?

### Release 2.2.0

Non-Substantive changes:

- FHIR-55885 - Making clear that the responsibility rests with the DTR server to produce distinct questionnaires (link)
- FHIR-55884 - Requirements around primary keys and update behavior for coverage-information extensions are out of sync between server and client sections (link)
- FHIR-55883 - Clarify §spec-125 regarding not supporting previously completed QuestionnaireResponses (link)
- FHIR-55866 - Expand narrative to clarify where the CQL Identifier mime type gets used (link)
- FHIR-55693 - Clarify scope of hyperlinks to contained Binary resources (link)
- FHIR-55692 - Clarification of location of 'contained' Binary XHTML/PDF/image resources (link)

### Release 2.2.0-snapshot

Breaking changes:

- FHIR-52804 - Change SHOULD to SHALL for returning HTTP 400 error with an OperationOutcome indicating the circumstances where the QuestionnaireResponse is invalid (link)
- FHIR-52801 - Change SHOULD to SHALL regarding the use of logic ensuring only questions and answer choices which are required for the intended clinical or administrative purposes (link)
- FHIR-52791 - Include expectations that DTR Services SHOULD have DTR questionnaires available for all covered items that require additional data collection (link)
- FHIR-52320 - Use a List profile instead of a logical model for supported payers (link)
- FHIR-51736 - Constrain DTR to only take a single coverage as input (link)
- FHIR-51631 - Give users an idea of how much time completion will take by adding `estimatedCompletionTime` extension to base Questionnaire (link)
- FHIR-50789 - Provide clarity around simple logic in Adaptive forms and adaptive processing expectations and requirements (link)

Substantive changes:

- FHIR-55401 - Documenting that hyperlinks in XHTML or supportLink may point to 'contained' binary resources, and include note on security implications (link)
- FHIR-53496 - Adding a 'request-specific' flag on Questionnaire to clarify circumstances allowed to re-use a form (link)
- FHIR-53050 - DTR version discovery as referenced in HRex
- FHIR-53041 - Making DTRMetricData providerId and groupId optional, but with a constraint that they are required if the source is the EHR (link)
- FHIR-52803 - Removed statement about translation between standard codes "where possible" as it is too ambiguous
- FHIR-52455 - Added clarification narrative regarding what is considered a 'portal' and expectations for it (link)
- FHIR-50465 - Added a new page called Conformance Details (link)
- FHIR-50033 - Added clarification narrative regarding If both orders and a context id are present (link)
- FHIR-48879 - Added clarification narrative regarding issues with source data in retrieving questionnaire packages (link)

Non-Substantive changes:

- FHIR-53484 - Multiple narrative and conformance updates to improve testability guidance (link)
- FHIR-53225 - Attribute all conformance requirements to distinct actors (link)
- FHIR-52982 - Clarified expectations around communicated public keys via SMART on FHIR Backend Services (link)
- FHIR-52796 - Improve clarity for exposing question text and answers in API, as well as use of third party logic in data gathering (link)
- FHIR-52802 - Clarified expectations around questionnaire design for absence of data (link)
- FHIR-52794 - Provide narrative to note that adaptive forms may help to protect intellectual-property (IP) and licensing exposure (link)
- FHIR-52792 - Include reference that the guide has requirements under HT1-4 (link)
- FHIR-52701 - Clarify that CQL SHALL be compatible with CQL version 1.5 (link)
- FHIR-52700 - Added references to CQL content (link)
- FHIR-51869 - Added section named "Launch Workflow" enumerating DTR's launch circumstance (link)
- FHIR-51629 - Set expectations for splitting clinical/patient and non-clinical forms (link)
- FHIR-51577 - Included guidance that server organizations MAY allow clients to pre-examine/pre-process questionnaires (link)
- FHIR-50790 - Clarified guidance on ability for DTR client to expose questionnaire items and how they are exposed (link)
- FHIR-51100 - Added a 'dragon' warning about legal rights to terminology in "Questionnaire Design" (link)
- FHIR-50499 - Added narrative guidance to explain rules for updating coverage-information with DTR (link)
- FHIR-49898 - Updated the context parameter to say "CRD, CDex, or PAS-provided context" (link)
- FHIR-49885 - Corrected the Questionnaire Package operation to explicitly list all parameters (link)

### Release 2.2.0-ballot

Breaking changes:

- FHIR-51020 - Provided guidance that `cql-identifier` should be used as mime type for CQL identifier.
- FHIR-50797 - Updated Questionnaire Package operation to always return a Parameters resource upon successful execution.
- FHIR-49726 - Made `Questionnaire.text` optional and also made `item.text` mandatory.
- FHIR-49663 - Removed coverage from context extension (qr-context) and split out into a corresponding coverage extension (qr-coverage)
- FHIR-49339 - Sliced QuestionnaireResponseBundle entry to enforce a single QuestionnaireResponse (1..1) and provided clearer guidance in specification.

Substantive changes:

- FHIR-50240 - Included narrative to specification to clarify expectations for sending more than one of orders/contextId/Questionnaire and cross-checking.
- FHIR-50020 - Rewrote section on Storing QuestionnaireResponses because it contained contradictory guidance and was misleading.
- FHIR-50013 - Updated the SHOULD to a SHALL in the `$log-questionnaire-errors` operation definition to align with narrative guidance.
- FHIR-49862 - Created Adaptive QuestionnaireResponse profile to enforce adaptive requirements on DTR QuestionnaireResponse used in $next-question operation.
- FHIR-49845 - Added MustSupport flag to both the `context` and `intendedUse` elements of the QuestionnaireResponse.
- FHIR-49836 - Redesigned 'Questionnaire Design' section to remove subjective qualifications.
- FHIR-49811 - Created 'audience' extension to differentiate administrative vs. clinical forms.
- FHIR-49810 - Added a complex constraint that says you must either have context id or Coverage.
- FHIR-49744 - Included narrative guidance within section '9.6.3 CQL Constraints' indicating that DTR SHOULD support additional FHIRPath variables/functions.
- FHIR-49743 - Added new invariants to Questionnaires that require certain extensions based on question type.
- FHIR-49729 - Constrained `supportLink` cardinality from 0..* to 0..1.
- FHIR-49724 - Created abstract 'Base Questionnaire' (`dtr-base-questionnaire`) to contain common elements for both Standard and Adaptive questionnaires.
- FHIR-49699 - QuestionnaireResponse item cardinality loosened from 1..* to 0..* to accommodate initial `$next-question` call.
- FHIR-448824 - Created internal DTR valueset `$expand` operation to focus parameter expectations specific to DTR.

Non-Substantive changes:

- FHIR-50587 - Added 'QuestionnaireResponse Contained Resources' section describing expectations for contained resources within QuestionnaireResponses.
- FHIR-50282 - Split apart previously 'temp' codesystem codes into appropriate, internal code systems (used in 'code' datatype elements)
- FHIR-49929 - Included guidance in the Questionnaire Package operation regarding the expectations for handling 'optional' forms.
- FHIR-49879 - Provided clarifying narrative in Questionnaire Package operation regarding location of context.
- FHIR-49815 - Updated narrative in 'EHR to App Connectivity' to provide clarity around DTR support for payers.
- FHIR-49814 - Added `alternateExpression` extension (as mustSupport) to each 'expression' extension in the Questionnaire profiles.
- FHIR-49730 - Constrained out `itemOptionalDisplay` in base questionnaire.
- FHIR-49648 - Clarified that both the target resource and QuestionnaireResponse can contain multiple coverage-information extensions
- FHIR-49639 - Adaptive Form Search profile modified to constrain out (0..0) the item due to questions not being relevant and were marked as MustSupport.
- FHIR-49343 - Narrative guidance for QuestionnaireResponse Bundle change of 'will' to SHALL addressed by ticket FHIR-49399.

### Release 2.1.0

- FHIR-48744: Align endpoint discovery language w/ CRD
- FHIR-48728: Inconsitency between contexts in CRD and DTR
- FHIR-48703: Coverage context search parameter inconsistencies
- FHIR-48694: Clarify ValueSet and $expand Guidance
- FHIR-48686: Profile $next-question (or create a new operation) so there's an actual use for the DTR adaptive questionnaire profile
- FHIR-48524: Constraining Queries example clarification
- FHIR-48523: Is the "Retrieving Launch Context Information" informational?
- FHIR-48521: Determining support for payer questionnaires
- FHIR-48520: Clarify use of PH Alternate Expression Extension
- FHIR-48519: Clarify whether FHIRPath is allowed in pre-population expressions
- FHIR-48518: Are there required DTR client responses to an added coverage-information extension?
- FHIR-48517: Library and ValueSet Caching requirements for DTR Apps and Full EHRs
- FHIR-48516: Clarify QuestionnaireResponse contained Questionnaire Requirements for adaptive questionnaires
- FHIR-48515: Explain Reasoning behind the difference in Questionnaire Adaptive extension cardinality
- FHIR-48513: No examples of Questionnaire Package Bundles with a QuestionnaireResponse
- FHIR-48511: Change SHOULD to SHALL
- FHIR-48510: suggest adding "including appeals"
- FHIR-48508: change conformance language for the retrieving launch context
- FHIR-48506: SHOULD have CQL logic
- FHIR-48504: Questionnaire-package Bundle Example not updated to only have one questionnaire
- FHIR-48501: Change SHOULD to SHALL
- FHIR-48499: add or staff to better capture people who populate
- FHIR-48495: CMS enforcement discretion comes out of nowhere
- FHIR-48494: Include CMS requirements
- FHIR-48490: $questionnaire-response output parameter name inconsistency
- FHIR-48488: Ambiguous SHALL on resource support requirement
- FHIR-48487: Replace EHR with Provider HIT
- FHIR-48314: providers need a way to indicate if they want pre-emptive prior auth as part of adaptive forms
- FHIR-47995: Must Support guidance section should be moved from Specification page to a 'Conformance Expectations' page
- FHIR-47706: Add support for US Core 7
- FHIR-47250: Clarify adaptive architecture
- FHIR-46754: $questionnaire-package narrative and DTRQuestionnairePackageBundle do not align.
- FHIR-46750: Clarify that CQL expectations are for app/EHR, not payer
- FHIR-46646: Conformance requirement on subjective determination
- FHIR-46554: Include questionnaire details in the example

### Release 2.1.0-preview

The following issues are addressed in preparation for this STU Update:

- Multiple changes have been incorporated to provide support for both US Core 3.1.1 and 6.1
- FHIR-44930: extra period breaks out a requirement in section 7.10.2 of the formal spec
- FHIR-45010: Why does OperationOutcome repeat
- FHIR-46288: Identifying the minimum resource read access ought to be SHALL instead of 'will'
- FHIR-45945: Clarify links to base FHIR resources in Background section
- FHIR-45075: DTR should not point to CDS Hook security guide
- FHIR-44929: Ambiguity within the formal specification on use of SMART on FHIR Backend Services
- FHIR-42809: allowing linking to a portal rather than building out a questionnaire is not in line with regulation, legislation, or even the spirit of IG
- FHIR-45020: $questionnaire-package Operation Definition incorrectly states to return warning in outer Bundle
- FHIR-46627: Include Burden Reduction common narrative for Enforcement Discretion
- FHIR-46569: Use EHR rather than EMR throughout
- FHIR-46525: Discrepancy in DTR Package output definition
- FHIR-44789: Can DTR be satisfied by a pre-existing QR?
- FHIR-45967: questionnaire-package bundle needs to allow for QuestionnaireResponses
- FHIR-46441: Add endpoint discovery expectations
- FHIR-46285: Need to formalize expectation around use of 'questionnaire-adaptive' extension
- FHIR-46002: Provide guidance on how to transmit FHIR resources to Adaptive Questionnaires

### Release 2.0.1

The following issues are addressed in this technical correction:

- FHIR-43030: Information Origin Extension challenged to be supported by SMART

### Release 2.0.0

The following issues are addressed resulting from this ballot:

- FHIR-24714: This is a security risk as described in the last ballot. - DTR #60
- FHIR-33328: Need clarification of what the DTR Task page is actually for
- FHIR-36117: DTR Document Reference R4 Resource Profile Inappropriately Marks Elements As Must Support
- FHIR-36220: CQL execution errors in an automated process should not require an end user to be notified
- FHIR-36225: statement doesn't quite make sense
- FHIR-36227: fix link (& therefore normative requirement) to DTR Questionnaire, instead of base CQF questionnaire
- FHIR-36228: Need clearer expectations around reusing and refreshing the QuestionnaireResponse
- FHIR-36355: Refactor the overview
- FHIR-36371: Clarify 'required' documentation
- FHIR-36378: Clarify CQL version expectations
- FHIR-36481: STU note should go away
- FHIR-36484: Remove SMART on FHIR applications and servers section
- FHIR-36489: Requesting user identity stuff belongs in section on launch
- FHIR-36522: add to sentence
- FHIR-36523: change SHOULD to SHALL
- FHIR-36525: Change MAY to SHALL
- FHIR-36528: it is essential that payers create extensive CQL for payer rule automation
- FHIR-36529: Change MAY to SHOULD
- FHIR-36530: refine verbiage
- FHIR-36532: Operation needs a detailed description
- FHIR-36139: More clarity around how UM Payer multi party arrangements are handled
- FHIR-36148: no template property is defined in appContext, and questionnaire is OPTIONAL
- FHIR-36150: is a CRD server the same as a payer API?
- FHIR-36433: Should be guidance about the use of versioning
- FHIR-36439: Why do we mandate the use of library?
- FHIR-36445: Caching guidance needs to be clarified
- FHIR-36538: DTR Questionnaire should be removed
- FHIR-36542: Context extension needs more definition
- FHIR-36548: add guidance to value set
- FHIR-36549: relaunch for other users
- FHIR-36550: Add SHALL save DTR response in EMR to beginning of section
- FHIR-36551: change SHOULDs to SHALLs in task creation
- FHIR-36553: change from "needs to" to SHALL
- FHIR-36555: limit scope
- FHIR-36624: attestation concern
- FHIR-34121: Provide a mechanism for Template to specify what to do when DTR ends
- FHIR-33224: Add support for SDC Adaptive forms
- FHIR-36276: Security review of SDC Adaptive Forms in DTR
- FHIR-36492: Handling updates to Questionnaire.effectivePeriod
- FHIR-36478: SDC questionnaire responses will always have a Questionnaire url somewhere
- FHIR-36527: refine language
- FHIR-36483: Need to clarify pruning expectations
- FHIR-36390: Launch instructions need correction/clarification
- FHIR-36491: Drop section on "usage sessions"
- FHIR-36385: No guidance on CRD
- FHIR-40438: Section on DTR use of US Core has link which points to general US Core page instead of 3.1.1
- FHIR-24581: Identify the subject extension. - DTR #15
- FHIR-36151: Again, DTR <-> Payer should use SMART backend services
- FHIR-36365: Downloads should be a separate page
- FHIR-36394: CQL logic guidance is misleading
- FHIR-36367: Talk about DTR before you talk about CRD
- FHIR-40549: Guidance regarding the Endpoint for adaptive form next question
- FHIR-36470: Fix guidance on saving state
- FHIR-36434: Revamp endpoint description a bit
- FHIR-36369: Payer
- FHIR-36376: Fix wording on SDC
- FHIR-36374: Should be no conformance rules around CDS Hooks or CRD
- FHIR-36377: Clarify language on CQL
- FHIR-36435: Remove CRD paragraph
- FHIR-36362: "CQL and FHIR Questionnaires SHALL be required" is unclear
- FHIR-39504: Add guidance on endpoint discovery/configuration
- FHIR-36539: DTR QuestionnaireResponse should be based on SDC
- FHIR-36395: Context needs to talk about hierarchy of expression too.
- FHIR-36380: Why is change history wrapped in an STU note?
- FHIR-36386: DTR to payer security doesn't belong in CRD links section
- FHIR-38837: Specific issues related to sensitive or patient restricted information
- FHIR-36138: Clarify what information is in scope for FHIR CQL support
- FHIR-36430: Clarify expectations on missing context
- FHIR-36300: Who is responsible for provision of the token
- FHIR-36482: Patient must always be in context
- FHIR-21006: DTR should point to SDC, not CQIF Questionnaire
- FHIR-36479: Provide proper details on authentication
- FHIR-36392: Guidance on CQL isn't quite right
- FHIR-36379: Spec *MUST* use mustSupport in its profiles
- FHIR-36384: "Profiles" page doesn't really make sense as a page
- FHIR-36382: Formal specification page should be revamped
- FHIR-36447: Guidance on handling Questionnaire is insufficient
- FHIR-36364: Home page should appear on the menu
- FHIR-36465: DTR is repeating guidance better covered in SDC
- FHIR-36360: Conformance statements don't belong on the home page
- FHIR-36368: Conformance language doesn't belong on use-case page
- FHIR-36410: Title and content don't jive
- FHIR-36356: Adjust note to implementers
- FHIR-37949: Remove all notion of storing work-in-progress on payer
- FHIR-40421: Guidance on this page needs to be rewritten
- FHIR-36450: Goal is overstated and user input always required
- FHIR-36476: Refactor relaunch documentation
- FHIR-36349: Split menu into background and spec
- FHIR-36149: appContext should be a black box to EHR, use SMART launch param's instead
- FHIR-36440: Remove the 'relaunch' section
- FHIR-36517: Clarification on Tasks
- FHIR-36531: Change SHOULD to SHALL and delete the MAY sentence that follows
- FHIR-36146: Clarify that DTR app should authenticate to payer with SMART Backend Services
- FHIR-36441: Remove FHIR version discussion
- FHIR-36298: CRD linking to website versus a DTR solution
- FHIR-36429: No appContext on stand-alone launch
- FHIR-36547: data SHOULD NOT be stored on the payer server
- FHIR-36540: Improve description of SDC Questionnaire profile
- FHIR-36383: Are you using SDC or CQF?
- FHIR-36361: Provenance expectations need more clarity
- FHIR-36507: Correct and re-organize this section
- FHIR-36533: Issues with lack of guidance on storage
- FHIR-36129: Initial DTR Launches should not be restricted to CDS Hooks Cards within the CRD workflow.
- FHIR-36988: Not clear where to get Requester Organization when creating PAS request
- FHIR-36366: Actors are unclear and in wrong place
- FHIR-36438: Questionnaire guidance is incorrect
- FHIR-36537: DocumentReference profile isn't sufficient
- FHIR-36253: DTR Spec needs a way to pass a questionnaire / response across organizations
- FHIR-34151: Need an ability for DTR to store prior authorization
- FHIR-39443: Add expectations about terminology mapping
- FHIR-36119: DTR SDC Questionnaire For Adaptive Form Profile Inappropriately Marks Elements As Must Support
- FHIR-36373: Clarify US Core expectations
- FHIR-36299: Mapping CQLs to PA criteria
- FHIR-36466: Provider Attestation guidance needs fixing
- FHIR-34103: Clarify minimum Questionnaire capabilities
- FHIR-33226: Formalize how DTR passes information to PAS, PAO or other exchange IG
- FHIR-36219: The CDS Hooks Card Link object should not require a DTR launch URL
- FHIR-36004: Change to use the CRD unsolicited prior auth profile
- FHIR-36467: Need a section on privacy/security
- FHIR-36346: Add 'support' menu item
- FHIR-36118: DTR SDC Questionnaire Profile Inappropriately Marks Elements As Must Support
- FHIR-36370: Clarify expectations on QR approval
- FHIR-36372: Do we need a CRD & DTR section here?
- FHIR-36393: Page names are overly long
- FHIR-36432: Are DTR Questionnaire valuesets pre-expanded?
- FHIR-36524: remove references to manual alternatives/solutions that do not leverage the specs
- FHIR-34291: Deferring and relaunching DTR App
- FHIR-37270: Access Token must not be included in appContext
- FHIR-36443: How does an app notify the payer system
- FHIR-36520: Change operation invocation
- FHIR-36391: Need more launch details
- FHIR-39492: Allow DTR to be used from CDex
- FHIR-36543: Need a search parameter for new context extension
- FHIR-36534: Correct operation adaptive expectations
- FHIR-40605: Update Questionnaire package operation per discussions
- FHIR-36431: Inconsistency in how value sets & libraries are returned
- FHIR-36625: please clarify data access by payer
- FHIR-34128: Allow passing 'order' context when launching DTR
- FHIR-36436: Do better job of explaining HRex decision points
- FHIR-36468: What's the point of distinguishing CQL vs. human-authored?
- FHIR-36535: We need examples for operation inputs and outputs
- FHIR-36437: Revamp payer authorization language
- FHIR-36455: Utilization of CQL
- FHIR-36375: Loosen rules on SMART
- FHIR-36359: Need CapabilityStatements
- FHIR-36331: Revamp expectations around launch parameters
- FHIR-36192: Include CRD questionnaire workflow, not just prior auth questionnaire
- FHIR-36412: Need more guidance on CDS Hooks launch
- FHIR-36544: Examples are incomplete and have extras
- FHIR-36409: EHR and DTR initiation
- FHIR-36411: Organize interactions along likely HIT modules
- FHIR-41557: Guidance on Referenced resources missing
- FHIR-41576: Prohibit alternate use of 'next-question' data
- FHIR-41168: "How DTR Passes Information" page is no longer accurate
- FHIR-40421: Guidance on this page needs to be rewritten
- FHIR-41854: DTR needs to be re-organized quite a bit