Da Vinci - Documentation Templates and Rules
2.1.0 - STU 2.1
Da Vinci - Documentation Templates and Rules
2.1.0 - STU 2.1
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.1.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
| Page standards status: Trial-use |
This page is organized into several sections reflecting the various steps involved in implementing DTR. These steps are organized in roughly the order they would typically occur, though some variation in order is possible.
The core of this process is summarized in this diagram:
 NOTE: |
The use of a portal for collection of clinical data to support prior authorization SHALL NOT be considered conformant to the requirements of this Implementation Guide. |
Throughout this guide, the term 'EHR' refers to the set of systems acting on behalf of a provider, whether managed directly by the provider organization or by a third-party agency. Similarly, 'payer' refers to the set of systems acting on behalf of the payer, whether managed directly by the payer or by a third-party agency. For additional discussion about how this implementation guide functions when EHR and/or payer systems are not monolithic but instead are made up of components, refer to the ePA Coordinators page.
Information passed to DTR will typically contain clinical terminologies, might not contain billing terminologies, and will generally not include billing modifier codes or similar information typically included in prior authorization requests. Services will also need to consider that the mapping they perform between clinical terminologies and billing codes could be different than the bill coding process performed by the client system when claims are eventually submitted. This could mean that assertions about coverage or prior authorization requirements will need to be expressed conditionally (e.g., "Provided this service is billed as X, Y or Z, then prior authorization is not needed").
In situations where the DTR App is aware of the likely billing codes at the time of ordering, it might send these codes as additional CodeableConcept.coding repetitions to assist in server processing. If CPT is used, note the ability to convey CPT modifier codes via post-coordination as described in the Using CPT page on terminology.hl7.org.
It is more efficient if mappings can be shared across payers and providers. This implementation guide encourages industry participants to cooperate on the development of shared mappings and/or to work with terminology developers (e.g., AMA for CPT codes) to develop shared mappings as part of their code maintenance process.
EHRs have the option of delivering DTR functionality internally or leveraging a DTR SMART on FHIR Application (SMART App) that handles the primary data capture and population functions of the DTR process. Such SMART applications may be developed by the EHR vendors, by payers, or by third parties.
DTR apps are expected to be technically able to run against any EHR and work with any payer. This means that EHRs are free to choose which app they prefer and MAY switch apps as they see fit. However, for a DTR app to be used it needs to be trusted appropriately to manage access to personal health information by the EHRs and payers. EHRs that leverage DTR SMART apps will choose which DTR apps they will trust and support. In some cases, an EHR MAY opt to support multiple DTR SMART apps. If so, the EHR will be responsible for determining which app is used in which circumstances.
SMART on FHIR defines the basic expectations for an EHR to register a SMART app. Most EHRs and organizations impose additional registration expectations. DTR imposes an additional expectation as part of the app registration process, which is discussed in more detail in the Determination of Payers Supported by a DTR App section of this specification.
Similarly, all DTR apps SHALL be registered with the payer systems with which they communicate. If an EHR opts to interact with the payer directly without using an app, then the EHR itself will need to register.
Initial setup of connectivity between client and payer will have a manual component to establish security credentials and a trust relationship (unless both parties are part of a shared trust network). Dynamic endpoint discovery allows for the potential to use different endpoints for the $questionnaire-package operation over time without changing security credential or legal agreement expectations.
Payers MAY have multiple back-end functions that handle different types of decision support and/or different types of services. However, for the purpose of DTR conformance, payers SHALL have a single endpoint (managed by themselves or a delegate) that can handle responding to all DTR service calls.
This registration process SHALL ensure that the DTR app or Full EHR (i.e., Native App):
$questionnaire-package operation has a shared secret allowing secure access to the payer endpoint via SMART on FHIR Backend Services.Implementers of this IG SHOULD support the endpoint discovery mechanism defined in the HRex specification to allow discovery of the endpoints used in this IG - specifically the $questionnaire-package operation endpoint used to retrieve the Questionnaires and associated libraries, value sets, etc. to be completed.
(Also see Authenticating DTR client to payer API)
Even after an application has been successfully registered, payers and EHRs SHOULD monitor the application behavior and MAY suspend an application's access if it is suspected of malicious behavior.
| NOTE: |
Some payers MAY create Questionnaires that rely on code systems that require licensing for use where there isn’t already a cross-U.S. license in place (e.g., UB, CPT). In such cases, the payer, provider, and if necessary, the SMART on FHIR app vendor will need to have the relevant licenses to display, store, and retransmit the information captured. The expectations around licensing requirements SHALL be established as part of the configuration process between the parties. |
Payers have documentation requirements and rules that must be satisfied as part of their typical operations when reimbursing for care for certain services requiring authorization or documentation. The Questionnaire resource is used to represent the information needs that providers must satisfy to meet payer documentation requirements and/or rules. The Questionnaire resource allows specifying:
The base Questionnaire resource defines some of these capabilities. However, to allow specifying all the expectations needed to meet payer requirements for data collection forms, additional extensions are necessary. DTR leverages the extended Questionnaire capabilities defined in the Structured Data Capture (SDC) implementation guide to define the complete set of functionality necessary to support data capture for payer purposes.
More information regarding Questionnaires, workflow, and behaviors implementers will need to understand can be found in the SDC Guide:
This IG defines two different profiles on Questionnaire that can be used to define data gathering requirements: the DTR Standard Questionnaire profile and the DTR Adaptive Questionnaire profile.
In the first approach, all possible questions that can be asked, as well as the logic around when questions are enabled and what answers are permitted are expressed in computable form and shared as a complete set when the Questionnaire Package is retrieved. Typically, the same Questionnaires are used across a wide variety of order types and members, though in theory the payer could generate a custom Questionnaire that is specific to a particular order and/or member.
In the second approach, the complete set of questions is not exposed. Instead, the $next-question operation is called repeatedly to slowly build up the list of questions, influenced by answers to prior questions. The set of questions asked will typically vary from patient to patient and order to order.
A summary of the trade-offs between the two approaches can be seen in the table below:
| Standard Questionnaire | Adaptive Questionnaire |
|---|---|
| All questions and logic shared when the questionnaire package is first downloaded. i.e., all potential questions, logic and rules are visible to the EHR or DTR app. | Questions are exposed one at a time (or occasionally a couple at a time) and only relevant questions are exposed. Rules and logic are hidden and only questions relevant to the current member/order are visible to the EHR or DTR app |
Only $questionnaire-package operation is needed |
Payer must support both $questionnaire-package and $next-question operations |
| Logic for which questions are asked and which answers are available is encoded in the Questionnaire, possibly using CQL, and is executed by the DTR app/EHR. | Logic for which questions are asked and which answers are available is written in software maintained by the payer in the language of their choice. The DTR app/EHR simply exposes whatever questions and answer choices are returned by the operation |
| Payers will need to write CQL and/or leverage advanced Questionnaire logic elements for both rules as well as data pre-population | Payers will need to write CQL for data pre-population only (though they will need to express rules in some programming/configuration language of their choice) |
| Rules that require accessing other payer systems or logic not expressible in CQL cannot be expressed. | Code defining rules for what questions to display, the text of the question, the answers available, etc. can depend on calls to other payer interfaces and can leverage logic of any needed level of complexity, including using third-party rules engines. |
Any population from payer data must occur at the time the $questionnaire-package operation is called and cannot be dependent on data populated from the EHR or entered by the user. |
Answers to later questions can be pre-populated from payer data based on previously answered questions (whether answered by pre-population from the EHR or by users) |
| Questionnaires and associated logic can be shared in a standardized way across payers as part of industry standardization efforts to drive consistency in data collection | Individual questions could theoretically be shared, but any special logic around which questions are asked or answers are available would not be easily shareable |
Logic cannot leverage payer data except as present in pre-populated answers in the initial QuestionnaireResponse provided in the $questionnaire-package operation |
$next-question logic is free to leverage data held by the payer about the member, plan, or other information
|
| Outcomes of the Questionnaire process are only reflected in answers in the QuestionnaireResponse | The QuestionnaireResponse returned by $next-question can contain extensions as well as answers – such as the coverage-information extension (see below)
|
| The payer has no access to what answers have been provided in the QuestionnaireResponse until/unless the QuestionnaireResponse is later transmitted to the payer (e.g., as part of a prior authorization request or a claim). The payer cannot inject any identifiers around commitments with respect to coverage or the satisfaction of authorization requirements. | The payer receives the data each time a question is asked and, [while limited in how they can use that data], they can associate it with identifiers that allow them to adhere to commitments with respect to coverage or the satisfaction of authorization requirements. |
Payers MAY support either approach or opt to provide some Questionnaires using one approach and others using the second based on the requirements of the form. DTR apps and Full EHRs SHALL support both types of Questionnaires.
Questionnaires, whether standard or adaptive, SHOULD also use logic that ensures that only 'relevant' questions and answer choices are displayed, based on what answers have already been provided/populated using elements such as enableWhen or enableWhenExpression. When using elements with a data type of 'Expression' within Questionnaires to control flow or rendering, all logic SHALL be written in CQL. However, there are many other properties and extensions that control the rendering and behavior of Questionnaires.The DTR Standard and Adaptive Questionnaires have identified the elements and extensions from the SDC Base, Advanced Rendering, Advanced Behavior and Expression-based Population profiles that must be supported in DTR. The descriptions Elements flagged as mustSupport SHALL be supported by DTR Apps and Full EHRs.
These systems SHOULD also support all non mustSupport data extensions included in the differential of the DTR Questionnaire profiles as per SDC documentation for those elements and extensions and SHALL gracefully handle the presence of these elements if not supported (i.e., non-support for an element SHALL NOT interfere with a user's ability to complete a QuestionnaireResponse). However, payers SHALL NOT rely on support for any of these elements in the design of their Questionnaire (i.e., a DTR client that ignores such elements cannot impact the successful collection of information acceptability of the information gathered).
The questionnaire designer SHOULD consider the possibility that access to some data may be restricted or prohibited and that access restrictions could happen silently (e.g., indistinguishable absent data).
When a payer uses an Adaptive Form, they SHALL return a questionnaire instance compliant with the DTR AdaptiveQuestionnaire-Search profile. This will include a questionnaireAdaptive extension that indicates that the Questionnaire is adaptive and is also used to determine the endpoint on which the $next-question operation should be called to start completing the QuestionnaireResponse. The extension's url value is the base for the next question operation (i.e., [url]/Questionnaire/$next-question).
| NOTE: |
If present, any questionnaireAdaptive url SHALL be a sub-url under the base for the payer and able to be accessed within the same SMART Backend Services connection as was established to make the $questionnaire-package call.
|
The QuestionnaireResponse included in the Questionnaire Package Bundle accompanying an adaptive Questionnaire SHALL follow the convention of referencing a contained Questionnaire derivedFrom the canonical for the Questionnaire being completed. Typically, the QuestionnaireResponse and contained Questionnaire will contain no answers (or corresponding questions), though the payer MAY opt to include a few pre-populated answers for user review prior to soliciting additional questions using the $next-question operation.
The $next-question operation provides no opportunity to pass context to the server posing the questions. It will have no information about who the member is, the nature of the order, or anything else. Any information needed will need to be passed in as the answer to a question. Payers MAY define pre-populatable questions to extract such information, using CQL to access the Questionnaire's launchContext extension or performing any necessary data retrieval. The populated (and potentially user-reviewed or adjusted) answers can then be leveraged in subsequent calls to $next-question to determine what to ask next.
Adaptive questionnaires pose a slight challenge when it comes to preparing the Questionnaire package. Unlike standard questionnaires, adaptive forms do not identify all their questions up-front. As such, it is not clear exactly which ValueSets will be needed for coded elements, nor which Libraries might be needed to contain CQL to support pre-population. There are three strategies payers can use – and payers MAY opt to combine strategies within a single Questionnaire:
The payer MAY opt to include CQL Libraries and ValueSets in the package that are not actually referenced by any questions, on the prospect that they might be (or are likely to be) referenced by one of the questions at some point. Libraries might also be included that define common helper functions that will be leveraged by question-specific CQL provided later. The downside of this approach is that an adaptive form might draw from a library of hundreds of different questions but only actually use a handful. This could result in needing to share an extremely large questionnaire package. It may also expose more of the proprietary logic than the payer might wish to make known. On the other hand, any CQL or code lists provided in the package is content that will not need to appear contained in the QuestionnaireResponse, which can lighten subsequent calls to $next-question.
The payer MAY add CQL Libraries and ValueSets as 'contained' resources inside the QuestionnaireResponse that are relevant to the questions that are part of the Questionnaire for each $next-question call, slowly building up the set of resources that happen to be relevant to the questions actually asked. The benefit of this approach is that only codes and CQL relevant to the questions asked needs to be shared. The downside is that this content is then present on every call to $next-question.
Finally, the payer MAY opt to specify the CQL and codes without using Libraries or ValueSets at all – the CQL can be sent in-line within the various Expression elements, and the codes can be listed directly as answerOption Codings. This has similar advantages and disadvantages to the second option, though it has less overhead. On the other hand, CQL and codes can't be shared across different items.
In some cases, an adaptive form may need to retrieve resources from the EHR in order to determine what subsequent questions to ask or to make a prior authorization decision. The only way for information to be relayed to the payer is with answers inside a QuestionnaireResponse. However, QuestionnaireResponse answers can't actually be full resources, only references. Payers needing full resources to be returned should use the containedReference extension to indicate that the selected resource(s) for an answer of type reference should be included as contained resources within the QuestionnaireResponse. This provides a mechanism for full resources to be included as part of the QuestionnaireResponse.
Implementers that support Adaptive Questionnaires SHOULD always include a coverage-information extension when the QuestionnaireResponse is deemed complete. (Future versions of this guide may tighten this expectation to a SHALL).
The package returned by the $questionnaire-package operation MAY include Library and/or ValueSet instances that are not referenced by any of the returned questionnaires if at least one of those questionnaires is adaptive. In this circumstance these additional resources are being made available, and SHALL be retained in the session, on the likelihood that a question in one of those adaptive questionnaires returned by the $next-question operation will need (and reference) these resources.
| NOTE: |
This mechanism is not necessary for non-adaptive forms as all resources pointed to by the QuestionnaireResponse will be returned as part of the Questionnaire Package Bundle |
The Privacy, Security, and Safety page includes additional guidance on the use of Adaptive questionnaires.
In some cases, upon receiving enough answers from an adaptive form, a payer will be able to make assertions about coverage, prior authorization, and/or any 'additional documentation needed' similar to what is provided by the CRD process. This information needs to be made available to the DTR client in a computable fashion. To do so, the adaptive form service will place the coverage-information extension on the root of the QuestionnaireResponse, alongside the qr-context extension.
If Adaptive Forms are being used, and a DTR service determines that prior authorization is both necessary and the requirements have been satisfied, then the final question in the form SHALL be a question that asks the user if they would like the prior authorization identifier to be issued, and indicate the appropriate response options. If the answer indicates a desire to have the identifier issued, then the completed questionnaireResponse from the payer will contain the issued Prior Authorization identifier in the satisfied-pa-id element of the coverage-information extension.
DTR payers SHALL ONLY use DTR adaptive forms to return a coverage-information extension when:
coverage-information extension is already present on the relevant order; and| NOTE: |
It will be unusual for a coverage-information extension created by an adaptive form to come back saying 'additional documentation required', however there are theoretical use-cases for this to be useful and this specification does not prohibit such behavior. If this occurs, it could result in a subsequent launch of DTR, or could result in the DTR client prompting the user as to whether they want to move on to filling out the new form(s).
|
If an adaptive questionnaire response includes an unsolicited determination that authorization requirements have been 'satisfied', the EHR SHALL allow the clinician to flag the provided determination number as "not valid". For example, If they feel the determination was based on incorrect information. If a payer receives a new invocation of an adaptive form for the same order, they SHALL treat the result of the new completion as replacing any previous completion from a prior coverage determination process.
If a final DTR QuestionnaireResponse includes a Coverage Information extension, the DTR Client SHALL associate the Coverage Information returned with the relevant Appointment, Encounter and/or Request resources and SHALL make the information provided in the extension available to their users for viewing. This might be managed with icons, flyovers, or other mechanisms as is appropriate to the workflow of the users of that DTR Client.
One of the core purposes of this specification is to automate the retrieval of documentation required by the payer in a manner that reduces provider burden.
Pre-populating answers reduces burden in two ways:
Pre-population requires that logic be embedded in the Questionnaire that identifies where in the EHR the information can be found. This in turn requires that the information needed be reliably locatable.
Questionnaires SHALL include logic that supports population from the EHR where possible. Such logic SHOULD rely exclusively on data elements and search parameters defined either in US Core or HRex (including simple calculations there-on - e.g., age from birthdate). Translation between standard codes SHOULD be supported where possible. Ideally, the design of questions in payer forms SHOULD consider what data is likely to be available for pre-population purposes, with an objective of minimizing provider data entry effort.
Due to differences in workflows or information systems, clinical information MAY be represented in different FHIR resources or with different codes or code systems. Therefore, payer CQL MAY have to examine different resources or use value sets to find patient information. It is preferable to have more extensive CQL or value sets than require a user to input values that the rules were unable to find.
DTR uses the SDC Expression-based Population mechanism as the mechanism for populating, and specifically the use of CQL as the expression language. CQL SHALL be used when pre-populating elements using data gathered from the EHR. DTR clients SHALL handle expressions in Questionnaires denoted as either CQL or FHIRPath (which is a proper subset of CQL). DTR servers SHOULD identify inline expressions that are valid FHIRPath as FHIRPath rather than CQL. This will mean using the launchContext, variable and the initialExpression, contextExpression or calculatedExpression extensions together with logic in Libraries referenced by the cqf-library extension to help populate the QuestionnaireResponse.
Further guidance on writing the necessary CQL can be found at 'Use of CQL' later in this guide.
In some cases, if there isn't specific data that can be retrieved computably from the EHR, it MAY be sufficient for a payer to merely have an attestation by the provider that certain documentation exists, that a certain patient condition exists, or that certain actions have been completed. This can be represented in a Questionnaire as a simple boolean or choice question where the text describes what the user is attesting to. Payers SHOULD design questionnaires to support attestation rather than discrete data where this is sufficient for the business requirements.
Some payers MAY require that attestations or other answers be 'signed' (the electronic equivalent of 'initialing' the answer). This would be identified by means of the questionnaire-signatureRequired extension on the Questionnaire item.
| NOTE: |
This IG does not define any expectations around certificate management or other considerations involved in the creation or validation of signatures, only the means by which signatures are requested and provided. |
Questionnaires MAY also support attaching reports or other supporting documentation (e.g., images, pathology reports, etc.) where providing question answers is not sufficient. The 'attachment' question type can be used to support this. Attachments might be found by searching for DiagnosticReport or Media instances, or by the provider directly uploading something to the Questionnaire rendering tool.
While a user might need to suspend interaction with the DTR process, there could possibly be a limit on the amount of time that a set of documentation templates and rules is valid. For example, it is unreasonable to resume the DTR process for an order that was started several years ago because it would produce a QuestionnaireResponse that would still be valid if submitted now. On the other hand, if a form was filled out five days ago and submitted today, it will be frustrating for providers if the form is rejected as "out of date".
Payers SHOULD use the Questionnaire.effectivePeriod element to describe the period over which the documentation templates and rules are valid. The DTR App or EHR can then check against that period when resuming a previously stored QuestionnaireResponse.
The Questionnaire resource provides several mechanisms for conveying coded answer choices. The table below is guidance that SHOULD be used when constructing questions with coded answers:
| CQL and Questionnaire terminology usage | Comment |
|---|---|
| No value set, embed the code choices using answerOption. | This is OK if there is no need to reuse the codes across multiple questions and the list of codes is ‘fixed’ and relatively small (< 40). |
| Pass a value set in the questionnaire package with the expansion already in place. | The same set of codes is used for multiple answers and the set of codes is relatively small (< 40). This saves the need for a terminology service call.’ |
| Pass a value set in the questionnaire package, but the client recipient will need to run the expansion or ask a terminology server to do the expansion. | The value set expansion is on the larger size (> ~40 codes), such that using the $expand with a filter operation will be more efficient from a user interface perspective. These value sets SHOULD be expanded by the client and therefore SHOULD NOT be included in the questionnaire package. DTR clients running as SMART on FHIR apps will typically need to hold the complete content of the questionnaire package in memory. Payers SHOULD design their questionnaires, value sets, and libraries with the knowledge that content which is too large may cause DTR clients to fail. |
As part of the SDC Questionnaires that define the information payers require to be captured, CQL is used to support automatic population of answers from existing EHR data and, occasionally, to enforce complex logic around what questions should be displayed. For example, whether answers are required, what answers should be enabled, etc. This CQL MAY query for patient observations, conditions, or other discrete information within the EHR to use as part of the population process or logic. The SDC specification provides guidance about how CQL expressions can be used for different purposes, as well as how information gathered by CQL in one portion of the Questionnaire can be made available in other portions of the Questionnaire.
CQL can either be embedded inline as part of an expression or referenced in a Library resource. All Libraries needed by a questionnaire SHALL be referenced by the cqf-library extension and included as part of the $questionnaire-package operation.
| NOTE: |
This guide sets expectation that Questionnaires returned from the $questionnaire-package operation will include CQL to support population and/or flow control and rendering of the Questionnaire within the DTR app or EHR. It is possible that payers may opt to use CQL internally to support population of QuestionnaireResponses returned in the $questionnaire-package or as part of the $next-question operations. However, there is no expectation this will occur and this specification provides no guidance on how such CQL would be written.
|
Like many other programming languages, CQL allows for statements to be nested within conditional logic. This creates instances where some statements may not be executed due to a prior condition not being met.
Data retrieval in a QuestionnaireResponse is dependent on the enableWhen element.
CQL logic SHOULD be partitioned to be specific to groups/questions/etc. when doing so will allow it to be more efficient - though consideration should also be given to whether performing significant data gathering at the outset (even if the data is unneeded) will produce a more positive experience than intermittent data retrieval 'on demand', when such retrieval MAY introduce user-interface delays. This pattern of logic structure is referred to by several names, including eager quitting, early return or, short circuiting. The goal is to avoid the execution of statements if they will not be relevant given other information available to the logic. This is done to streamline workflow and allow the user to focus on relevant input fields.
As an example, a payer MAY have a set of rules or specific information that must be gathered on a patient only if they have diabetes. This information MAY be gathered through a series of CQL statements. When constructing this CQL for DTR, these statements SHOULD be nested in conditionals to first check if the patient has diabetes before checking for information dependent on that condition.
Implementers could use Adaptive Forms to minimize the need for any CQL that provides conditional information retrieval.
While CQL can either be embedded inline in Expression elements or packaged in Libraries, This guide strongly recommends that implementers SHOULD place CQL logic in libraries as it is much easier to edit and debug such logic when it is all in one place, rather than when it's scattered through many different expression elements throughout the Questionnaire. In this approach and results of the queries, filtering, and other operations are to variables in the Libraries using define statements. These variables can then be referenced in the valueExpression, contextExpression or calculatedExpression elements asserted for the various Questionnaire item elements. If a given variable evaluates to null the answer will be left empty, for the end user to complete.
DTR imposes the following additional rules on CQL use by payers to maximize interoperability:
cqf-library elements), then any valueExpression referring to defined variables SHALL specify the library name as well as the statement name as follows: "LibraryName".statementName.content.data element.
It is possible that the apps used to provide DTR functionality will not support all payers the EHR might have "DTR requests" for. It is important for the EHR to know what payers their app supports so that they only allow their users to launch the DTR app in the context of payers the app will be able to support. (Launching an app only to be told "this payer isn't supported" is an unpleasant user experience.)
The developer of SMART on FHIR DTR apps SHALL define an endpoint maintaining a list of payers currently supported by that app. This listing of Payers is based on the Supported Payers logical model also published in this IG. EHRs using external DTR apps SHALL support accessing the endpoint. The EHR will be configured with knowledge of which endpoint to access for a given app as part of the process of configuring support for that app within the EHR. Different endpoints SHALL be defined for different versions of the application in situations where support for payers varies by application version.
It is important to note that the Payer Identifier used in this file SHALL be the same as the ones that are returned by the endpoint discovery mechanism defined in HRex.
Example 'Supported Payers' file:
{
"supportedPayers": [
{
"name": "Health Ohmy",
"identifier" : {
"system" : "http://healthohmy.com/NamingSystem/payer-identifiers",
"value" : "987654321"
}
},
{
"name": "Instancio Health",
"identifier" : {
"system" : "http://Instancio.org/NamingSystem/payer-identifiers",
"value" : "123456789"
}
}
],
...
}
Accessing the endpoint will be by a simple GET with an Accept header of application/json and SHALL be performed over TLS. The returned JSON object will contain a "payers" property referring to an array of objects. Each object will have an id and name property, both with string values. It is possible that additional properties MAY be supported in the future.
EHRs will typically retrieve the list of supported payers for the app once per day and will use this information to determine whether to expose the ability to launch DTR for orders associated with coverages for that payer.
| NOTE: |
The purpose of the DTR client registration process is to establish trust - NOT to establish custom questionnaire behavioral expectations. |
The standardization of payer ids is still considered an open issue. Guidance on standardization of payer identity is expected to be provided in the DTR Implementer Support page on the HL7 Confluence site.
| NOTE: |
This section only applies if an EHR is using a SMART app. |
When the DTR process is being launched, the Electronic Health Record (EHR) system and DTR process SHALL follow the procedures established by the SMART App Launch Framework - specifically the SMART App Launch Framework's EHR launch sequence.
Like any SMART app, DTR is passed a context when launched. The openId, user, and patient launch contexts SHALL be requested and provided. In addition, the launch context SHOULD include fhirContext references as follows:
coverage-information extension of the Request or Encounter passed below) andIf these are not passed in as part of context, then the app MAY either raise an error or guide the user to select the needed records.
In addition to launch contexts, the SMART app will need to request scopes for the type of information it needs to access and manipulate. Payer-provided Questionnaires MAY require access to a wide range of resources.
At a minimum, the app and the HIT server SHALL support access to the following resources via the 21st Century Cures Act compliant APIs:
Resources referenced from the above via Must Support elements, including transitive references, SHALL also be supported.
However, typically CQL in Questionnaires will also need access to Observation, Condition, Procedure, DocumentReference and potentially others. Therefore, in most cases, apps will simply request patient/*.rs and patient/questionnaireresponse.cu. However, apps MAY opt to be more restrictive in their access requests if they are confident that they can do so while meeting payer CQL needs and EHRs indicate this is desirable.
Regardless of the scopes asked for and granted by the user, the EHR SHALL limit access to only that data they deem appropriate for use in automatically populating payer forms, in particular restricting sensitive data. (Refer to the Privacy and Security section for more details)
To collect data for a payer, the EHR or SMART app responsible for data collection must first establish a connection to the payer. Payers SHALL require DTR apps and EHRs connecting to their endpoint to authenticate using SMART on FHIR Backend Services. This mechanism provides a flow that authorizes a system to connect to a FHIR server where no user needs to be involved in the authorization process. It allows systems like EHRs to easily interact with pre-authorized defined scopes of access. The scopes necessary are:
system/questionnaire.rssystem/valueset.rssystem/library.rsThese are sufficient to invoke the DTR Questionnaire operations $next-question and ValueSet/$expand, as well as the retrieval of libraries and value sets.
Again, this is only relevant for SMART on FHIR clients, though a similar process will happen for Full EHRs. There are several steps in processing the launch context to begin the data collection process. The following recommended workflow describes the steps and mechanisms that would be necessary to determine the QuestionnaireResponse(s) to render. Some EHRs or SMART apps may vary their behavior slightly, but the end result of determining the relevant QuestionnaireResponse(s) should be the same.
qr-context search parameter (e.g., [EHR-base]/QuestionnaireResponse?patient=123&context=ServiceRequest/789).qr-context extension identifying any associated requests or encounters, and if so, perform searches to retrieve them with _includes for requester, performer, etc.coverage-information extension, either from CRD or from DTR.
Once the EHR or app has authenticated itself, it can invoke the $questionnaire-package operation using the information gathered in the preceding Retrieving Launch Context Information step. The operation will be invoked with a 'POST' using the base endpoint associated with the coverages provided based on payer configuration. If multiple Coverages are provided that are associated with payers having different endpoints, then the operation will be invoked once per payer endpoint (e.g., POST [base]/$questionnaire-package).
The operation will be invoked passing a DTR Questionnaire Package Input Parameters instance containing the following information:
coverage element.questionnaire element.order resources, plus the associated performer and requester Practitioner and Organizations, as well as any referenced Devices or Medications as 'referenced' resources.coverage-information extension was available, the coverage-assertion-id as context.context.meta.lastUpdated as changedsince.The result will be a response with one or more Questionnaire package Bundles. The remainder of the DTR process will involve the completion, storage, and use of the QuestionnaireResponses found in those Bundles.
The operation will return a Questionnaire Package Bundle for each Questionnaire that needs to be completed. The Bundle will include the Questionnaire to be filled out, any ValueSets or CQL Libraries needed to support completion of the Questionnaire, and optionally a partially pre-populated QuestionnaireResponse to use as a starting point when filling out the form. If a QuestionnaireResponse is returned, the QuestionnaireResponse.questionnaire SHALL point to the same canonical URL as the Questionnaire provided in the package Bundle. If no Questionnaires need to be completed, the Parameters instance will not contain any Questionnaire Package Bundles.
If any of the retrieved Questionnaires have an effectivePeriod that ends prior to the current date, then the DTR client SHALL change the status of any retrieved work-in-progress QuestionnaireResponses for the expired Questionnaires to 'stopped' and notify the user that the previously recorded content has expired. The $questionnaire-package operation would then need to be re-invoked just passing the orders and not specifying canonical questionnaire URLs to retrieve the updated Questionnaire(s) appropriate for the order, using the same context.
If an expired Questionnaire is retrieved when it wasn't explicitly requested by referring to a canonical version, but instead by passing in the relevant order(s) and/or context id, the DTR client SHOULD report an error to the payer.
| NOTE: |
Previously completed QuestionnaireResponses SHALL NOT be supported due to concerns about currency of clinical information. |
Prior to exposing the draft QuestionnaireResponse to the user for completion and/or review, the DTR client SHALL execute all CQL necessary to resolve the initialExpression, candidateExpression and calculatedExpression extensions found in the Questionnaire for any enabled elements.
All items that are pre-populated (whether by the payer in the initial QuestionnaireResponse provided in the questionnaire package, or from data retrieved from the EHR) SHALL have their origin.source set to 'auto' (within the required information-origin extension).
The flow of execution of the CQL will be determined by the associated Questionnaire. The client will proceed through the Questionnaire, and for any question that is associated with the result of a CQL expression, that specific CQL statement will be executed. The DTR client SHALL use result caching so that results that are already available will be reused without requesting them again.
| NOTE: |
The answers to questions populated by an initialExpression or calculatedExpression might themselves be dependencies to determine whether a Questionnaire item is enabled or not, which MAY in turn influence whether additional pre-population is required. DTR clients SHALL iterate as necessary until a steady state is reached. If dependencies are such that a steady state cannot be reached (e.g., an item that is enabled causes a value to be set which causes a different item to be enabled, that then disables the first item…), then the Questionnaire SHALL be treated as erroneous and attempts at automatic population SHALL end, with the user being informed of that.
|
The DTR client SHALL retrieve the FHIR resources specified in the dataRequirement section of a Library. SMART apps will do this using the access token provided on launch. The client can then pass these resources to the Clinical Quality Language (CQL) engine. For example, the snippet below is from a Library that contains a dataRequirement section. In this code snippet the resource data needed from the EHR is Condition.
"dataRequirement": [
{
"type": "Condition",
"codeFilter": [
{
"path": "code",
"valueSet": "http://cts.nlm.nih.gov/fhir/ValueSet/2.16.840.1.113762.1.4.1219.25"
}
]
},
Depending on user permissions, the client might not have access to all the data. Queries SHOULD be constructed to minimize the retrieval of information that is not necessary to answer the relevant questions (For example, queries for medications that only require active medications should have appropriate filters to retrieve active medications and not inactive medications). It's possible not every CQL statement will be executed (for example some questions may only be enabled given certain answers to prior questions). To reduce data transfers and increase overall speed, data MAY be fetched as needed. However, the app's execution engine MAY be implemented using a different strategy (for example by doing bulk fetches before starting execution).
An adaptive form handles population slightly differently from a 'standard' form because questions only become available one (or a few) at a time. Some CQL Libraries MAY themselves only become available once certain questions are displayed. The population process must therefore happen after each call to $next-question, populating any newly available questions. DTR clients SHALL support such an incremental population of adaptive QuestionnaireResponses. For performance, the DTR application SHOULD save the results of execution of CQL prior to the $next-question call.
If DTR is launched using a previously saved QuestionnaireResponse, the DTR client SHOULD re-execute CQL to populate all empty elements, as well as those with an origin.source of 'auto'. Any answers with an origin.source of 'override' or 'manual' SHALL NOT be changed, though if pre-population would have asserted a value for an answer with an origin.source of 'manual', the origin.source SHALL be changed to 'override'.
An adaptive form handles population slightly differently from a 'Standard' form because questions only become available one (or a few) at a time. Some CQL Libraries MAY themselves only become available once certain questions are displayed. The population process must therefore happen after each call to $next-question, populating any newly available questions. DTR clients SHALL support such an incremental population of adaptive QuestionnaireResponses. For performance, the DTR application SHOULD save the results of execution of CQL prior to the $next-question call.
The FHIR Library containing/referencing a CQL logic file can reference other needed CQL files (e.g., helper libraries) using the relatedArtifact field and a RelatedArtifact with a type of depends-on. The engine SHALL make available to the execution context all such referenced CQL Libraries.
If the CQL is malformed (is not syntactically correct) in any way, the app's execution engine SHALL NOT attempt any execution of the malformed CQL. If the CQL engine reports an error when executing any of the CQL the app should similarly stop all CQL execution. In either case, the client SHALL report the error to the payer using the Log Questionnaire Errors operation and SHOULD Log the error internally and/or in the DTR client if possible.
If the CQL in the Questionnaire is only used for form population purposes, the app SHALL:
If the CQL also includes questionnaire logic, such as whether certain elements are enabled, or other validation rules, the app SHALL notify the user that there is an issue with the questionnaire and prohibit further completion of the form.
| NOTE: |
A query for data that returns no results SHALL NOT be considered a failure. |
While the goal of DTR is to automatically gather all the necessary information to satisfy documentation requirements without interrupting the user, this is not possible in all cases. It is likely that at least some answers will not be able to be gleaned from the EHR, due to missing data, data that is not computable, or data that is not represented in a standardized way. Also, even where answers are determined automatically, users may wish to review them for accuracy and completeness. Therefore, the system acting as a form filler is responsible for displaying all 'enabled' questions, groups, and display items to the end user for completion and/or review. In some cases, the population process MAY populate all answers to the Questionnaire. The DTR client SHALL provide the ability, but NOT a requirement, for providers to review pre-populated answers prior to saving the resulting response for subsequent use within the EHR.
DTR leverages a subset of extensions and capabilities defined by the SDC implementation guide to support control over rendering, flow logic, and population and calculation of answers. The DTR SDC Questionnaire profile and DTR Adaptive Questionnaire profile identify the set of core elements and extensions that must be supported by 'full' EHRs and DTR solutions in terms of rendering and processing Questionnaires and their associated responses - and the elements that payers can count on being supported in the Questionnaires they expose.
Two different profiles are used to support two different approaches to managing questionnaire logic and two different levels of engagement between the form filling interface and the payer:
Implementers should review the advanced rendering, advanced behavior, population and adaptive forms portions of the SDC implementation guide, focusing on the elements and extensions included in the DTR profiles. Implementers should also be familiar with the documentation about the Questionnaire and QuestionnaireResponse resources from the core FHIR specification. Conformance with DTR requires conformance with the relevant portions of the SDC implementation guide.
All DTR applications SHALL support rendering according to the mustSupport elements in the DTR Questionnaire profile as well as executing all CQL found within Questionnaire extensions. CQL and FHIR Questionnaires SHALL be required even when DTR is implemented within a DTR Native App as opposed to a DTR SMART App.
When a user fills in a value or changes an answer in a QuestionnaireResponse, the DTR client SHALL populate the information-origin extension, setting the author property to the current user, and setting source to 'override' if the source was already 'override' or 'auto', or 'manual' otherwise. DTR clients SHALL either provide a PractitionerRole in the SMART App launch of DTR or support transmitting the role by means of the activeRole extension within the Practitioner resource.
Each Questionnaire has a set of rules that determine whether a QuestionnaireResponse is allowed to be considered 'complete'. For example, cardinality expectations on answers, restrictions on allowed values, etc. These rules are defined both by core elements as well as by extensions.
The DTR client SHALL validate the QuestionnaireResponse on an ongoing basis as the user is reviewing and entering data. The client SHALL visually flag any elements that require adjustment to meet validation rules.
For Standard Questionnaires, when the QuestionnaireResponse is valid, the DTR client SHALL indicate that to the user and allow them to mark the QuestionnaireResponse as complete, though the user MAY opt to continue making changes or save the QuestionnaireResponse in draft form. The DTR app SHALL NOT mark a Standard QuestionnaireResponse as 'complete' automatically.
With an adaptive Questionnaire, there is an iteration of invoking $next-question, populating if possible, and allowing user review/adjustment of answers. The DTR client SHALL NOT allow the user to indicate they are ready for the next question/set of questions until the answers to the current QuestionnaireResponse pass validation rules. If $next-question is invoked with a QuestionnaireResponse the payer determines is invalid based on the rules in the contained Questionnaire, it SHOULD return an HTTP 400 error with an OperationOutcome indicating the circumstances where the QuestionnaireResponse is invalid.
Unlike Standard Questionnaires, with adaptive QuestionnaireResponses the determination that a QuestionnaireResponse is complete is made by the payer. The final call to $next-question will result in an echo back of the QuestionnaireResponse with no further questions provided in the contained Questionnaire, and with the QuestionnaireResponse set to 'complete'. However, the QuestionnaireResponse MAY have a coverage-information extension added reflecting the payer's coverage assessment based on the information gathered in the QuestionnaireResponse.
If a questionnaire or question is marked as questionnaire-signatureRequired, then the DTR client will need to add a questionnaireresponse-signature extension to the appropriate location in the QuestionnaireResponse. The signature would attest to the QuestionnaireResponse as a whole, or to the specific item the signature appears on – excluding any questionnaireresponse-signature extensions themselves.
In some cases, the answer to a question modified by a user MAY be the input to an expression driving other logic within the questionnaire. DTR clients SHALL monitor for changes to dependent questionnaire answers and re-execute logic, adjusting calculatedValues, enabling elements, adjusting validation rules, etc. based on changes made by the user.
If an EHR system performs DTR functionality internally, it MAY save session information however it likes. The guidance below does NOT apply in this scenario.
At any point prior to completion the DTR client SHALL be able to save the 'in-progress' QuestionnaireResponse, either to ensure that work-in-progress is not lost, or to allow the user to close the session and then relaunch it later. When the QuestionnaireResponse has been marked as 'complete', the DTR client SHALL save the QuestionnaireResponse to the EHR using a create (POST) if the record had not previously been stored, or an update (PUT) if the record had already been saved at least once. The DTR process creates a QuestionnaireResponse resource through the course of normal operation. This resource SHOULD be saved to the patient record in the EHR system of the healthcare provider if supported. It MAY also be transmitted to the payer IT system.
The information gathered via DTR can be used for a variety of purposes:
Once DTR has written a QuestionnaireResponse to the DTR Client and updated the QuestionnaireResponse.status element to complete, the DTR Client needs to understand what action(s) it should take with the collected information. This is accomplished via three extensions:
qr-context extension provides a reference to the Request resource(s) and/or Encounter that the QuestionnaireResponse relates to.intendedUse extension indicates how the EHR is to use the information with respect to the associated orders/recordscoverage-information extension captures any coverage determination made by the payer with respect to the Request or encounter resources mentioned in the context extension.Upon storing a completed QuestionnaireResponse with a coverage-information extension, the EHR SHALL propagate the coverage-information extension to all non-Coverage resources included on the qr-context extension on the QuestionnaireResponse. If a coverage-information already exists on the target resource with the same coverage-information.coverage, it SHALL be overridden.
In those cases where a QuestionnaireResponse is to be used to convey information either to the payer or to downstream service providers, the DTR Client SHALL place the QuestionnaireResponse in a 'collection' Bundle complying with the questionnaireResponseBundle profile. This Bundle will include the QuestionnaireResponse entry as its initial entry and will then also include any resources that are referenced by the QuestionnaireResponse as answerReference that are not already contained within the QuestionnaireResponse. This ensures that all necessary information is delivered without a need for subsequent queries.
| NOTE: |
Only those resources directly referenced in the QuestionnaireResponse are included. If further references from a referenced resource are desired, the designer of the Questionnaire must ensure that these are also included as answers (possibly as hidden answers automatically populated by CQL within the Questionnaire). |
While multiple purposes are possible, the expectation is that all information in the QuestionnaireResponse will be used for that purpose (e.g., If a QuestionnaireResponse had a purpose of 'prior authorization' and 'order transmission', then the full QuestionnaireResponse bundle would be sent as a prior authorization attachment and as an attachment when the order is sent to the performer).
If there is a desire to send different content to different recipients, then distinct QuestionnaireResponses SHALL be used. It is up to the DTR Client to determine the process by which attachments to prior auth requests, claims or orders are assembled - this could be done automatically, or with human review.
IG © 2022+ HL7 International / Clinical Decision Support. Package hl7.fhir.us.davinci-dtr#2.1.0 based on FHIR 4.0.1. Generated 2024-12-21
Links: Table of Contents |
QA Report
| Version History |
|
Propose a change