Announcing a new release 6.0.0 of cht-conf

Announcements Releases
1

We are excited to announce the 6.0.0 release of cht-conf!

Some big enhancements have been made to the form processing logic including some breaking changes that may require updates to existing form xlsx files.

Shout out to @Omswastik for contributing the pyxform changes that made all this possible! :tada:

New bundled version of pyxform

Local pyxform installation is no longer required

Previously, the pyxform utility (required for converting form xlsx files to the xml xform format for upload) needed to be manually installed in the user’s environment. Now pyxform (version v4.0.0-medic) is bundled with cht-conf and installed automatically when cht-conf is installed. The user simply needs Python 3.12+ available in their environment.

Existing cht-conf users can safely uninstall any local pyxform installation. cht-conf will only use the bundled instance of pyxform.

New pyxform version may require change to forms

The new version of pyxform brings with it a number of importiant changes that may require updating existing form xlsx files for compatibility. The known changes include:

Modified Functionality

  • Attribute ordering in the generated XML file will now be deterministic.
    • Re-converting an unmodified form should not result in any changes to the form’s xml file.
    • When converting a modified form, the only lines that will be changed in the form xml are ones that are directly related to the changes in the xlsx.
  • Question fields are now required to have a label or hint. (Previously, pyxform would just print a warning if a question did not have a label or hint.)
    • If you try to convert a form with a question field with an empty label (and no hint) it will fail with an error like: The survey element named 'world' has no label or hint.
    • For fields that should not be displayed to the user, consider using the caluculate type when you have a calculation expression or a default value. If the field value is not coming from the calculation or default columns, the hidden type can be used without a label/hint. This is particularly useful for input data fields or fields populated by the contact selector.
  • Empty groups/repeats (without any child fields) now result in an error.
  • Duplicate choice names now result in an error by default. However, support can be re-enabled via the allow_choice_duplicates setting.
  • pyxform will now warn when there are missing translation columns for any of the languages in the form.

Added functionality

  • trigger columns are now supported, allowing for calculations to be automatically re-evaluated when an unrelated value changes!
  • You can now reference ${paths} in labels on the choices sheet.
  • Support for randomizing choice order in select questions via the randomize=true parameter has been added.

feat(#613)!: uplift pyxform to v4.0.0-medic (#709) (d78296d)

Consistent naming of form identifier required

When there is a missmatch between the form_id in the xlsx, the file name for the xml, and the internalId from the properties file, cht-conf will now raise an error when you run the convert-*-forms action.

Now it is not required to specify the form identifier at all (in the xlsx, xml, or properties files). cht-conf will automatically set the form identifier based on the name of the xlsx file and the form type.

For cases where existing forms are now triggering an error:

  • contact forms - remove any custom identifiers specified in the xlsx or properties file for contact forms.
  • app forms - if a custom value (that does not match the xlsx file name) is currently specified as the form_id in the xlsx or the internalId in the properties file, the file name of the form’s xlsx/xml file should be updated to match the custom identifier value.
    • The renamed form will be seen as a “new” form on the CHT instance (even though it will produce reports with the same form value). So, be sure to remove the old version of the form from the instance before renaming and re-uploading the updated form.
    • Do not update the custom identifier value to match the form’s file name. That will result in new reports being written with a different form value and can produce data consistancy issues.
  • training forms - as with the app forms, if there is a missmatch in the identifier of a training form the file name of the training form xlsx/xml file should be updated to match the custom identifier.
    • Be sure to remove the old version of the form from the instance before renaming and re-uploading the updated form.
    • Do not update the custom identifier value to match the form’s file name. That will result in the form being treated as a totally new training and users would be prompted to redo the training even if they had previously completed it.

feat(#537)!: error when form internalId does not match file name (#776) (f921f1e)

5 Likes
2

When I tried to convert a form with cht-conf@6.0.0, I got this error on Windows 11:

ERROR There was a problem executing xls2xform. Make sure you have Python 3.10+ installed.
'C:\Users\binok\AppData\Roaming\nvm\v20.19.6\node_modules\cht-conf\bin\xls2xform-medic' is not recognized as an internal or external command,
operable program or batch file.

I have Python 3.12.7 and tried it with both PowerShell and Command Prompt.

When I looked into the directory mentioned in the error, it had a file named xls2xform-medic, but it didn’t seem to be executable on Windows.

I had xls2xform-medic.exe from a previous pyxform installation that I copied to the above directory. Now my cht convert-app-forms command is working, but I guess I’ll miss out on the new pyxform features that way.

Is there a way we could support it on Windows?

Update: AI suggested me to create xls2xform-medic.cmd instead of the copied exe, and put this as the content of the cmd file:

@echo off
python "%~dp0xls2xform-medic" %*

It converted the XLS successfully, while showing the new warnings from the latest pyxform.

Should we package this xls2xform-medic.cmd with cht-conf, or is there a better way to make it work for Windows users?

1 Like
3

@binod thanks for the details here! :person_facepalming: I did not think to test this on Windows… :grimacing:

After doing more reading and tinkering, I agree with your assessment/solution here. I have logged an issue and raised a PR. If I can get a :+1: from you on the PR, we can get this fixed and released!

2 Likes
4

FYI, we found a regression that affects forms where the form_id/internalId of the form does not match the file name of the form xlsx/xml. This has been fixed in the latest patch release. I recommend that everyone upgrade to that version. :+1: