feat(#9875): document how to use select_*_from_file

[jkuester]

Description

Just adding some brief documentation for how to use the newly supported select_one_from_file and select_many_from_file question types in a form.

I have tried to keep the documentation concise while linking to additional information. I assume the reader is already familiar with configuring forms and uploading resources and just needs the key info on how to connect the two.

cht-core issue: medic/cht-core#9875
cht-core PR: medic/cht-core#10971

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[jkuester]

@mrjones-plip can I get a quick docs review! 🙏 I am confident in the technical accuracy, but would appreciate your thoughts on clarity and level of detail.

[mrjones-plip]

I'm gonna run through setting it up to see how hard it is. tl;dr - I think this is close, but we could just a smidge more to get a POC. Gimme a sec and I'll send back a formal review!

[mrjones-plip]

yay! this reads well and has good examples

minor tweaks for clarity and and then a few more example values to guide folks

---

Separately (and kinda out of scope for this PR) I failed to get the feature to work though - lemme know if you're concerned!

1. check out latest feat(9875)/external-dataset-forms branch from vikrantwiz02's repo
2. build images and run them in docker (got no time for npm run dev-api 😅 )
3. edit death form to have select_one_from_file foo.xml
4. add ./resources/foo.xml with contents of XML from this commit
5. push it all with cht and convert-app-forms upload-app-forms upload-resources -- death_report
6. go to death report and see Error loading form. Please try again or check with an administrator. in browser and console says Error loading form Error: Failed during the form "death_report" rendering : External dataset "foo" not found in resources. Only XML files are supported.

🤷

[jkuester]

add ./resources/foo.xml with contents of XML from this commit

Did you remember to also update the resources.json file in your config to include a reference to foo.xml?

Error loading form Error: Failed during the form "death_report" rendering : External dataset "foo" not found in resources. Only XML files are supported.

Are you sure you set select_one_from_file foo.xml in your form config? I would have expected to see External dataset "foo.xml" as the error message. For best results, you want to use foo.xml both as the property key in the resources.json and as the instance name in your form field type.

Thank you for taking the time to try out the code! It is good to have another set of eyes on stuff here. 👍

[mrjones-plip]

Yes! I tried both this in resources.json:

"foo.xml": "foo.xml"

and also

"foo": "foo.xml"

Neither worked. I also made sure to

Are you sure you set select_one_from_file foo.xml in your form config?

Yups - I literally copied it from my form. Speaking of which - here's the whole zip (TMI, but it's small): default.mrjones.select.from.file.zip. Also here's the full cht command in case I'm missing something simple:

cht --url=https://medic:password@192-168-68-26.local-ip.medicmobile.org:10472 upload-resources convert-app-forms upload-app-forms compile-app-settings upload-app-settings -- death_report

and docker images were named after the branch: medicmobile/cht-*:feat-9875--external-dataset-forms

Happy to pair quick next week if it'll help!

[mrjones-plip]

I just did a git pull origin before our call in 20 min and don't think any of the changes affect this PR, but listing them here in case you think I should rebuild the images!

git pull origin output on vikrantwiz02-core's branch

➜  vikrantwiz02-core git:(feat(9875)/external-dataset-forms) ggpull
remote: Enumerating objects: 147, done.
remote: Counting objects: 100% (111/111), done.
remote: Compressing objects: 100% (44/44), done.
remote: Total 57 (delta 46), reused 21 (delta 12), pack-reused 0 (from 0)
Unpacking objects: 100% (57/57), 6.29 KiB | 804.00 KiB/s, done.
From github.com:vikrantwiz02/cht-core
 * branch                feat(9875)/external-dataset-forms -> FETCH_HEAD
   bdc320284..6fdf14c93  feat(9875)/external-dataset-forms -> origin/feat(9875)/external-dataset-forms
Updating bdc320284..6fdf14c93
Fast-forward
 admin/src/js/services/message-queue.js                            |  6 ++++--
 admin/tests/unit/services/message-queue.spec.js                   | 62 +++++++++++++++++++++++++++++++-------------------------------
 api/src/services/export/message-mapper.js                         | 15 +++++++++------
 api/tests/mocha/services/export/message-mapper.spec.js            |  4 ++--
 ddocs/medic-db/medic-client/views/registered_patients/map.js      | 22 ----------------------
 ddocs/medic-db/medic-client/views/reports_by_subject/map.js       |  2 +-
 shared-libs/transitions/src/lib/utils.js                          | 18 +-----------------
 shared-libs/transitions/test/unit/lib/utils.js                    |  4 ++--
 shared-libs/transitions/test/unit/utils.js                        |  8 ++++----
 webapp/src/ts/services/format-data-record.service.ts              | 14 +++++++-------
 webapp/tests/karma/ts/services/format-data-record.service.spec.ts |  8 ++++----
 11 files changed, 65 insertions(+), 98 deletions(-)
 delete mode 100644 ddocs/medic-db/medic-client/views/registered_patients/map.js

[jkuester]

That just looks like the changes from master which were merged in. Should not really have any affect.

[mrjones-plip]

Adding an update for posterity - after just waiting over the weekend, I came back this morning and my form just worked without me changing anything from when it was broken last week. @jkuester and I theorize the web app wasn't getting updated and my aggressive "shift + reload" wasn't actually reloading the app.

This PR is doubly good to go now!