Supporting modular configuration in cht-conf

Development
1

The way cht-conf manages configuration files for contact-summary/targets/tasks makes it challenging to leverage reusable configuration modules (e.g. GitHub - medic/cht-stock-monitoring-workflow · GitHub).

Essentially, integrating any pre-defined external configuration requires custom edits to the local contact-summary.templated.js, targets.js and/or tasks.js files. These edits are difficult to reliably automate (e.g. in a post-install dependency script).

See this cht-conf issue for more details.

In feat(#566): implement auto-inclusion of task and target and contact s… by inromualdo · Pull Request #784 · medic/cht-conf · GitHub @Romuald_Dansou has worked up a solution to this problem by refactoring the structure of contact-summary/tasks/targets config to be simliar what we currently have for the app_settings.

Currently, if you init a new config project, it will load config from these files (not counting deprecated ones):

  • app_settings/
    • base_settings.json
    • forms.json
    • schedules.json
  • contact-summary.templated.js
  • targets.js
  • tasks.js

After Ro’s changes, the non-deprecated places to load config from will be:

  • app_settings/ (unchanged)
    • base_settings.json
    • forms.json
    • schedules.json
  • contact-summary/
    • base.js
  • targets/
    • base.js
  • tasks/
    • base.js

In each of the contact-summary/, targets/, and tasks/ directories you can add multiple files that are merged together to form your complete configuration during compile-app-settings. This allows you to have a custom base.js file with your bespoke config and then also to have one or more other files that perhaps were loaded/generated externally that all get pulled into your app settings. You can also just spread your bespoke config across multiple files for better organization, etc.

To limit the complexity of the code changes here, we are also dropping support for nools-style configuration in cht-conf. That config has been deprecated for years since and cht-core dropped support in 4.2.0. (Edit: technically, the normal “declarative” configuration has been supported in cht-conf since ~2018 in the 1.x. The deprecated “nools” configuration continued to be supported in both cht-conf and cht-core. It was the 5.0.0 release of cht-core that finally dropped support for “nools” config in cht-core.)

Posting this out here to get feedback, suggestions, comments, objections, etc from a larger group of people before we drop this in a new major version of cht-conf. :folded_hands: Please let us know what you think! Tag anyone else who might be interested. :+1:

@diana @binod @kenn @paulalogno

2

I love the idea of pushing CHT Conf forward in this way! Feels to me like a worth while breaking change to have this extensibility and re-usability added especially with it coming from Medic Afya’s real world use.

For someone not paying attention who upgrades to latest CHT Conf, unknowingly taking on this breaking change, what is the experience like when they next go to push their config to the CHT? Mainly what will it tell them and how many steps is it to fix it? The latter looks like maybe just creating a few directories and moving/rename some js files?

I think breaking changes that make it easy and prescriptive to recover from are a lot more palatable than when the fix is hours of work. This can be especially true when you’re under deadline and just need to push a fix live to your production CHT instance.

Thanks!

3

Great question, thanks @mrjones! To clarify, the only true breaking change here is dropping support for the old nools-style config. So anyone with the contact-summary.js and or rules.nools.js files should get an error (with explanation) when running compile-app-settings with the new version of cht-conf. This nools-style was deprecated years ago (when the “declarative” config was made available) though it technically was still supported in cht-core all the way up to 5.0.0. So the folks this would immediately affect are people trying to run the latest version of cht-conf to compile/upload old “nools” configuration for a 4.x CHT instance. Anyone wanting to still compile/upload the “nools” config will have to pin to a 6.x version of cht-conf (and will be unable to upgrade to 5.0.0). (Worth noting that we were pretty confident when we dropped support for nools in 5.0.0 that basically no one was still actively using it…)

Otherwise, the existing declarative config files (contact-summary.templated.js, targets.js, and tasks.js) are totally still supported, though keeping them at the root level is deprecated. For folks that do not want to see warnings when running compile-app-settings, the “fix” should be as simple as copying the files:

  • contact-summary.templated.js > contact-summary/base.js
  • targets.js > targets/base.js
  • tasks.js > tasks/base.js
4

Gotcha - thanks for the run down of the differences - makes sense!