Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates to CQL and Library authoring pages #83

Merged
merged 15 commits into from
Mar 14, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 16 additions & 11 deletions input/pagecontent/l3_cql.md
Original file line number Diff line number Diff line change
@@ -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:**
Expand All @@ -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:
Expand Down Expand Up @@ -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.
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is the motivation for the @internal tag? Why not use the private CQL access modifier? More generally, what is the motivation for making it private in the first place?


// 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.
Expand Down
88 changes: 83 additions & 5 deletions input/pagecontent/l3_libraries.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}


Expand Down
Loading