diff --git a/input/pagecontent/l3_cql.md b/input/pagecontent/l3_cql.md index 1b1b4cffb..f8fb43c53 100644 --- a/input/pagecontent/l3_cql.md +++ b/input/pagecontent/l3_cql.md @@ -1,17 +1,21 @@ -CQL - [Clinical Query Language](https://cql.hl7.org/) is a way to computably express data queries for the inputs and outputs of decision support - [decision logic](l3_decisiontables.html) and [scheduling logic](l3_scheduling_logic.htlm) - as well as [indicators](l3_indicators.html). +CQL - [Clinical Query Language](https://cql.hl7.org/) is a way to computably express queries and logic for the inputs and outputs of decision support - [decision logic](l3_decisiontables.html) and [scheduling logic](l3_scheduling_logic.htlm) - as well as [indicators](l3_indicators.html). -CQL expressions are data definitions are defined in cql files; Common CQL libraries are available, containing commonly usable expressions, including FHIR resources. +For background and introduction to CQL, refer to the [Getting Started](https://github.com/cqframework/CQL-Formatting-and-Usage-Wiki/wiki/Getting-Started) page of the CQFramework wiki. + +CQL expressions are defined in CQL libraries; Common CQL libraries are available, containing commonly usable expressions for accessing data represented as FHIR resources. Upon authoring, CQL libraries are encoded (base64) and included in FHIR Library resources. -The L3 author must ensure that there are CQL expressions in each Measure or Decision/Scheduling artifact, including their dependencies. Dependencies are common definitions intended to be used across different specification. +The L3 author must ensure that there are CQL expressions in each Measure or Decision/Scheduling artifact, including their dependencies. CQL Library dependencies are common definitions intended to be reused among multiple artifacts, and potentially multiple SMART Guidelines. ### **Inputs:** -* L2 Decision and Scheduling table -* Common CQL files +* L2 Decision tables +* L2 Scheduling tables +* L2 Indicator tables +* Common CQL Libraries ### **Outputs:** @@ -21,12 +25,12 @@ The L3 author must ensure that there are CQL expressions in each Measure or Deci ### **Activities:** -1. The L3 author creates an input CQL file for: -* each input columns in the Decision Table -* each input columns in the Scheduling Table -* each indicator tab - -CQL files are named after the decision/scheduling/measure: +1. The L3 author creates an input CQL Library for: +* each Decision Table +* each Scheduling Table +* each Indicator +CQL Libraries using in SMART Guidelines follow the conventions and conformance requirements established in the [Using CQL With FHIR](https://build.fhir.org/ig/HL7/cql-ig/using-cql.html) implementation guide. +CQL Libraries are named after the decision/scheduling/measure: * e.g., IMMZ.D2.DT.Measles -> IMMZD2DTMeaslesInputs.cql 1.2. Create expressions for all input columns with tags: @@ -73,6 +77,7 @@ In this case, the auhor can for example: 2.4. Include any other dynamic values that are needed for the PlanDefinition in the output CQL. 2.5. Tag any other expressions needed as internal. +// TODO: Provide documentation of the CommunicationRequest approach that provides a level of indirection between the health worker and the decision support guidance 3. Create or reuse ActivityDefinitions depending on what FHIR resources need to be created from the Decision Tables. This will include a CommunicationRequest to alert the Health Worker to the Guidance that will be output. 4. Create PlanDefintions for each Decision Table that references the output CQL libraries. diff --git a/input/pagecontent/l3_libraries.md b/input/pagecontent/l3_libraries.md index 5d1f3df31..3bf7854ae 100644 --- a/input/pagecontent/l3_libraries.md +++ b/input/pagecontent/l3_libraries.md @@ -9,24 +9,102 @@ Libraries are FHIR Artifacts containing the definitions of data querying and pro * Library resources - populated with the necessary metadata and content +#### **Metadata** + +##### **Shareable** + +* Library resources SHALL conform to CRMIShareableLibrary + +| Element | Guidance | +| ---- | ---- | +| id | SHALL be populated with {{Library Name}} +| url | SHALL be populated with {{canonical base}}/Library/{{Library Name}} | +| version | SHALL be populated with {{ig version}} | +| versionAlgorithm | SHALL be populated with {{ig version algorithm}} | +| versionPolicy | SHALL be populated with `strict` | +| name | SHALL be populated with {{Library Name }} | +| title | SHALL be populated with {{Library Title }} | +| status | SHALL be populated with {{ig status}} (`draft` for non-released content, `active` for released content) | +| experimental | SHALL be populated with {{ig experimental}} | +| publisher | SHALL be populated with {{ig publisher}} | +| description | SHALL be populated with {{Library Description}} | +| knowledgeRepresentationLevel | SHALL be populated with {{narrative & (computable | executable)}} | + +##### ** Publishable ** + +* Published `active` status Library resources SHALL conform to CRMIPublishableLibrary + +| Element | Guidance | +| ---- | ---- | +| identifier | ???? | +| date | SHALL be populated with {{ig publish date}} | +| contact | SHALL be populated with {{ig contact}} | +| useContext | SHALL be populated with {{ig useContext}} & ???? Decision Support Logic? Scheduling Logic? Indicator Logic? Data Element Logic? Concepts? Common? Settings? Configuration? | +| jurisdication | SHALL be populated with {{ig jurisdiction}} | +| purpose | SHALL be populated with {{Library Purpose}} | +| copyright | SHALL be populated with {{ig copyright}} | +| copyrightLabel | SHALL be populated with {{ig copyrightLabel}} | +| approvalDate | SHALL be populated with {{ig approvalDate}} | +| lastReviewDate | SHALL be populated with {{ig review date}} | +| effectivePeriod | SHALL be populated with {{ig effectivePeriod}} | +| topic | SHALL be populated with {{ig topic}} and optionally additional topics specific to the library | +| author | SHALL be populated with {{ig author}} | +| editor | SHOULD be populated with {{ig editor}} | +| reviewer | SHOULD be populated with {{ig reviewer}} | +| endorser | SHOULD be populated with {{ig endorser}} | +| relatedArtifact | SHALL be populated with `citation` references to L2 content | + +TODO: Define how references to L2 content occur (not only for libraries but throughout) + +##### **Computable** and **Executable** + +* Computable Libraries SHALL conform to CQLLibrary (base64-encoded text/cql content) +* Executable Libraries SHALL conform to ELMLibrary (base64-encoded application/elm+json content) + +> TODO: Should we have JSON always? + ### **Activities:** -* (Under revision) +* The L3 Author creates Library resources for each CQL Library +* Library Types: -### **Output Criteria / Definition of Done:** +| Library Type | Description | +| ---- | ---- | +| Common | CQL utility and helper declarations | +| Concepts | CQL terminology declarations for concepts in the SMART Guidelines IG | +| Elements | CQL expressions representing SMART Guidelines data elements | +| Decisions | CQL expressions corresponding to the inputs and outputs of SMART Guidelines decision tables | +| Scheduling | CQL expressions supporting scheduling logic | +| Indicators | CQL expressions corresponding to population criteria for indicators | -* Libraries should be conformant to the SMART IG specification - i.e. no QA errors +### **Output Criteria / Definition of Done:** +* Each CQL Library in the IG SHALL have a Library resource +* Each Library SHALL indicate the type of library according to the above (with a useContext slice) TODO: SGLibrary +* Each Library resource SHALL conform to CRMIShareableLibrary +* Each active published Library SHALL conform to CRMIPublishableLibrary +* Each Library resource SHALL conform to CQLLibrary +* Each Library resource SHALL conform to CQLModule ### **Change tracking** -* (Under revision) +In addition to the change tracking provided generally for all resources: + +* Each CQL Expression SHALL provide a reference back to the source of the expression +** Concepts: The reference is implicit in the code +** Elements: A tag referring to the L2 Element by ID +** Decisions: A tag referring to the L2 Decision Table (could be library level?) +** Scheduling: A tag referring to the L2 Scheduling Table (could be library level?) +** Indicators: A tag referring to the L2 Indicator (could be library level?) ### **Tooling:** +> TODO: Need to determine the best way to integrate the library processing. In progress + | Tool | Usage | Doc | | --- | ---| ---| -| (TBC) | | | +| Publisher | As part of the publication process (use path-binary) | | +| CQF Tooling | Run _refresh... | | {:.table-bordered.full-width}