worldhealthorganization / smart-ig-starter-kit

This is a draft document still being edited. This content should not yet be expected to be coherent or even compatible with the SMART Guidelines

WHO SMART GUIDELINES - DRAFT SMART Guidelines L3 SOP

---

This is the DRAFT SMART Guidelines L3 SOP

Publication

This ImplementationGuide is published in the following locations:

Continuous Build: https://WorldHealthOrganization.github.io/smart-ig-starter-kit
Continuous Build: https://build.fhir.org/ig/WorldHealthOrganization/smart-ig-starter-kit
Canonical / permanent URL:

Issues

Issues and change requests are managed here:

Issues: https://github.com/WorldHealthOrganization/smart-ig-starter-kit/issues
or the Kanban board: https://github.com/WorldHealthOrganization/smart-ig-starter-kit/projects/1

smart-ig-starter-kit's Issues

Automated validation of authored content

As an author, I want the artifacts that I author to be automatically validated (e.g. in the build workflow) so that I don't need to test manually whether the content is functionally correct - e.g. if the extraction does generate a valid set of FHIR resources, or if the $apply operation does return the adequate MeasureReport with the right values.

DAK Components mapped to L3 artifacts

Define DAK components mapped to L3 artifacts - not just at high level but component by component, field by field.

Do we need guidance on Adapting IGs?

I didn't see anywhere with guidance for member states on how to adapt a SMART IG? Is that something that should be included in the template since the high level concepts would apply to all IGs?

Mini IG for adaptation

Inheritance and adalatation should not be by cloning.
Make a real new IG (utopia? catopia?) that simply shows the entire chain of changes, and how this impacts from concept governance to package deployment.
Start from nothing but tiny changes (e.g. 1-2 elements).
Criteria: Whole process should be very nimble for this.

Studying a Cache System at the FhirEngineRetrieverProvider layer

Surveillance and Outbreak Toolkit IG using FSH

Support sushi authoring for every artifact that uses CQL

Create "current open issues" section

As an L2 author, I want to be aware of tooling issues, dependencies and gaps, so that I can plan my work and define expectations accordingly.

Some issues are preventing optimal tooling. Some examples - not all of them validated yet - to show that some of these dependencies can be in different places and impact authoring and implementation

hapifhir/hapi-fhir#3575
hapifhir/hapi-fhir-jpaserver-starter#601
HL7/fhir-ig-publisher#779

Packages for testing L3 criteria

For testing and debugging L3 outcomes during authorship (i.e. before handing over to L4), we need some packaging mechanism. My proposal is that when the IG is built, certain packages would be available as tarballs, e.g. "questionnaire-xxx" and we can have tools that follow that naming to allow easier debugging. Today it is too cumbersome, which means that a) L3 authors spend lots of energy diving into code and b) it's hard for L2 authors to confirm if there's any gap.

Content	Need
Forms (Questionnaires)	The questionnaires and dependent questionnaires, valuesets and codesystems, the StructureMaps and the structure definitions... and a (few) QuestionnaireResponse(s). And possibly the "good" result of the extraction. SDC etc are not needed, I presume..
Indicators (Measures)	CQL Libraries, dependencies..

I suggest we design this mechanism and

• add this to the SOPs.
• update the tooling (and CRMI if needed?)

pinging @brynrhodes as some of this may be covered already, or a better idea may exist.

ID Generation for patient tracking across campaigns

IPRD has been developing an ID generation toolkit to help track patient records digitally and on paper. More details can be found here

https://opencampaignlink.org/

This issue will be used to track the progress of the toolkit. IPRD has to share current set of requirements and get feedback from the community.

Define SGQuestionnaire profile

As a L3 author nad L4 implementer, I want to know the expectations from questionnaires its content:

• contained valuesets should not be necessary
• Relying on packaging is important not to add unneeded information into the definitional artifacts

Tasks

Beta Give feedback

1. Define SGQuestionnaire profile

L2 SOP Decision support tables

@Akshitapalliwal @litlfred FYI to add to V3 of decision support and L2 L3 SOP

1. Guidance column is used for human action - a communication request in L3 should be created for pop-ups (guidance) in decision tables
2. Action column defines actions the system must take.

• the action must be a "Clinical note" where the action is a human decision, the system must capture a note against it
• if the action is presenting the next screen for data capture (that is also mentioned in the workflow as a next step) then mention the workflow step in the action
• if there are multiple actions for a single cell then they must be written in different lines (using ctrl+enter) and must be separated by AND in capital letters. each sentence must be in quotes.

@costateixeira for L3 SOP that means

1. Guidance column in decision support must create communication requests
2. we will need a SOP item for what artifact in FHIR will be "clinicalnote"

Code Review Surveillance & Outbreak Toolkit

Kindly review : https://github.com/ritikarawlani/smart-outbreak-measles

Add profile and example for L4 bundles

Need to consolidate and further detail the tooling expectations. At this moment there is much ambiguity, e.g. are ValueSets in a Questionnaire needed? Should they be contained? How are they referenced?

• Questionnaires
• Measures?

Document notional performance times for some reference implementations

Confirm/Define package output. Implement or mock the functionality as an urgent dependency

Much debt because of not having a packaging definition and operation. Authors, testers and implementers don’t have a standard outcome with a Questionnaire and all it needs, or a Measure and all it needs. We ended up building the entire IG to get a package and all the other necessary packages.

Define approach or guidance for non-deterministic behaviour, exceptions, or missing information

As an L2 / L3 author, I want to have clear support (and guidance to L3/L4+ implementers) for non-deterministic flows, so that the decision support can be used in real scenarios.

Having questionnaires for every required decision is useful to demonstrate the wishful cases, but real cases have missing information, or much more information than we can standardize, and clinical workflows will not be as prescriptive.
This could be related to the use of BPM+

Create tooling for easy, repeatable, testing of functions like extraction, caclulations.

As an author, I want an easy and quick way for testing changes to artifacts like extractable Questionnaires, and Measures and Plan/ActivityDefinitions, to avoid slow cumbersome testing to contribute to buffered work (i.e. huge chunks of untested code, where small increments would have been much easier to address).

Zero QA errors

Common metadata management

Tasks

Beta Give feedback

1. (Define metadata model?)
2. Create infrastructure (OCL-based)
3. Define interfaces

R4 StructureMaps don't support metadata

Currently it's impossible to add metadata to structuremaps. And when trying to, there's a problem with the publisher parser, and the structuremap is not added to the IG at all when it has some comments.

Remove US dependencies

hl7.fhir.us.cqfmeasures depends on hl7.fhir.us.qicore which depends on hl7.fhir.us.core

Frequent Issues and resolution

Several issues that we find are common, and it would be helpful to compile a list of the most frequent ones and their resolution

Naming Conventions for L3 SOP

Make a real new IG (catopia?)

Make a real new IG (catopia?) that simply shows the entire chain of changes, and how this impacts concept governance. Start from nothing but tiny changes (e.g. 1-2 elements).

Update dependencies to CRMI and others

Make sure we don't replicate existing specifications.
Maybe best after #36

ICD-11 as a CodeSystem

ICD-11 is not supported by the FHIR tooling yet. This should be addressed

Leaner testing while authoring

Changes take long and are difficult to see if everything works. This is a major contributor to buffered work (i.e. huge chunks of untested code, where small increments would have been much easier to address).

• Tooling is needed. Testing, especially functional/integration testing (not just seeing if it compiles, but whether it does the job)
  • Tooling: Ability to create a QResponse and test its extraction
  • Do we have a baseline toolbox? This tool should depend on the packaging too.
    • There’s a PR in hapi jpastarter to upload a npm package, but packages are too heavy just to get a questionnaire and structuremaps..
• See #37 Packaging to feed tooling.

sub menu in navigation bar

On the navigation bar there should be ability to view sub-menu/sub-tabs.

FHIR-equipped No-code Application Development Platform for WHO SMART Guidelines

Build a FHIR equipped no-code development platform for ease of adoption of the WHO SMART Guidelines. In the current state, an organization/ group that wants to try out the SMART Guideline app requires a native android app development skill set. We propose to develop a no-code platform with limited UI assets and customizations to enable anyone who may not have the resources or expertise to embark on traditional software development projects (which are usually expensive. An example app is linked here Template for "Telehealth Coordination" in Google AppSheet, we can borrow some ideas from here and evaluate if something like this is a good candidate for the first version.

Tasks

Beta Give feedback

1. List down Pros and Cons of a no-code platform
2. List down requirements
3. Source of funding for this work
4. Define a good sample use case for a MVP eg: Immunization

Web FHIR SDK

Requirements:

1. SDC : Render Questionnaires
2. Questionnaire Authoring Tool eg:
   https://formdesigner.helsenorgelab.no/
   https://lhncbc.github.io/lforms/
3. Data extraction - Does the community need this?
4. Offline storage , search and sync - Does the community need this?
5. FHIR Operations $appy - Does the community need this?

Need a tab for Glossary under Business Requirements

There is a Concepts tab already under business requirements, but a separate tab for incorporating a glossary is also needed. Look at smart-trust for example of requirement.

CQF tooling- align file naming convention for compatibility with FSH resources

(this is copied over from another repository)
when the tool writes out the json files, it should be able to merge them with the fsh-generated resources, but for this we need a simple change:

• save the resources in the output folder (given by an argument) prepending the resource type and a dash, but not under a folder with the resource type name - i.e. output files as <resourcetype>-<name>.

For example:
When the arguments include -lop ./fsh-generated/resources -mop ./fsh-generated/resources -rp ./fsh-generated/resources
the Measure resource MERTXCURR can be found in the file
./fsh-generated/resources/Measure-MERTXCURR.json
AND should be output to the same file
(currently the tooling saves under
./fsh-generated/resources/measure/Measure-MERTXCURR.json
)

Presuming this is a simple change that requires no further refactoring, I understand it will allow us to finally integrate this with the standard FHIR tooling.

I can setup a branch with a (failing) test if needed, consisting of the template changes

Confirm or define format for "executable/shareable?" Questionnaire (including valuesets, structuremaps)

As an author, tester or implementer I want to have a standard artifact with a Questionnaire and all it needs for testing and using the questionnaire and extraction, without getting the entire NOM package stack and require a terminology server.

Tasks

Beta Give feedback

1. Mock an example
2. Check CRMI and define the format of such package
3. Implement / decide where to implement package function: Knowledge manager? Publisher?

What is the ideal place to maintain links of exisiting tooling in the L4 ecosystem?

1. OHS: Android FHIR SDK
2. OHS: Authorization
3. OHS: Data Analytics
4. OHS: Benchmarking Android SDK
5. OpenSRP: FHIR Web Administrative Managment eg: HCW Role, Location etc
6. matchbox FHIR Server: Load conformance resources and debug with $validate, StructureMap/$transform and Questionnaire/$extract
7. SwissTPH: L3 to L4 pyfhir
8. Authoring Questionnaire :
   a. https://formdesigner.helsenorgelab.no/
   b. https://lhncbc.github.io/lforms/

Define Folder Structure

Table of Contents

Ability to create sub-menu items in Table of Contents.
Numbering changes when sub-menu items are included. Include separate numbering for sub-menu items

ANC Danger Signs IG packaging

Work with ANC danger signs to create smaller packages of the IG for deployment and easy loading onto implementation tools using CQF tooling.

Monitor progress (e.g. in README)

Publish ImplementationGuides in target site

This is a "grouping" issue - about preparing the templates, tooling, scripting and relevant infrastructure for publishing the SMART Guidelines IGs in their final destination

Customizing Title

Currently, the file name appears as the title of the page. Need the ability to customize titles

Upgrade AndroidSDK dependencies to the CQL/Evaluator 3.0

Prevent gh-pages from accumulating history

We've been having some issues with repo size.
The GH action should not keep history on gh-pages, and the existing gh-pages should be squashed to remove commit history from that branch.

Where to define valuesets that are required for CQL?

e.g. IMMZConcepts uses HIV status, ARV Dugs, etc.

Where are these defined? And how can an L3 author know whether they are defined already?

Automate readme

For example to show the QA errors. Lots of issues can be intercepted earlier.

Structure Map as 2 steps instead of 1

Currently, Structure Maps are done from Questionnaires to FHIR resources directly. The proposal is that Structure Maps be done, first, to a Logical Model instance as step 1 and then Logical Model instances to have a map to FHIR Resources.

This normalization step will ensure Logical Models always map to FHIR resources, and further, any questionnaires, IPS or any other structure simply maps itself to the logical model. This will create a more modular, standardized structure of doing things.

Tasks

Beta Give feedback

No tasks being tracked yet.

What is the ideal place to maintain links to learn CQL ?

CQL Foundation

1. https://cql.hl7.org/03-developersguide.html - Read, Read and Re-Read
2. https://cql-runner.dataphoria.org/ - Where to test
3. https://github.com/cqframework/cqf-exercises - Spend some time here
4. https://github.com/cqframework/CQL-Formatting-and-Usage-Wiki/wiki/Getting-Started - Good docs
5. https://github.com/cqframework/clinical_quality_language/blob/master/Src/java/cql-to-elm/OVERVIEW.md - Don't go here before 1-4

Sample Content

1. Sample CQL. - https://github.com/opensrp/fhir-resources/tree/main/g6pd/cql
2. Sample ANC Indicators - https://github.com/opensrp/fhir-resources/tree/main/madx/cql/anc
3. Sample In-App reports - https://github.com/opensrp/fhir-resources/tree/main/ecbis_liberia/library/measure/cql

Create deployable servers

As an author, I want an easy and standard way to deploy a server with the relevant content of the IG, so that I can validate my specifications and see if they work as they should.

Specifications:
11-Oct: This is aproach taken for now:

• standard "testing" content contains links to the relevant files and common instructions (see this)
• docker images with the server (matchbox or cqfruler)
  • these images are NOT processed by the IG, rather they are directly taken from the github repository.
  • The point of getting them directly is not to need to rebuild the IG if for example there's a new version of mathbox).
  • the actual paths to the docker.compose files are is still hardcoded in the markdown, for now.
• The docker compose also contains a simple http server
  • this server gets a simple html app from another github repo (also here, not parsed by the IG.)
• As a result, when the user runs docker compose, the images are downloaded, as well as the static html app.
• 2 apps are available:
  • simple questionnaire filler and structuremap extraction
  • simple measurereport display as a pivot table.

Next: need to decide

• Initializing the server with content
  • is the most complex part now. some use scripts, others extensions... a single way would at least allow us to have a known working approach.
  • option 1 - @litlfred , @ritikarawlani lease comment:
    • L3 author can create a List of packages (at least manually for now).
    • This list has a fixed name, and the app just loads that list. This list seems important because we may not want to upload everything to the server at once, or do we?
    • The list contains packages and each package is a Bundle - for example "Bundle for Questionnaire-IMMZCRegisterClient".
    • The app displays the packages in a dropdown.
    • User selects package and clicks "upload".
    • Another package may exist to delete and rever the server to a known status. Since this is also a Transaction bundle, we don't need to worry about that.

Packaging operation

Packaging Implementation Guide - IG Visualization

Is your feature request related to a problem? Please describe.
There is no GUI tool to visualize changes and adaptations made to IGs. This will be important for country specific deployments.

Kunjan from Argusoft is leading the effort of gathering and documenting requirements.