Help wanted testing the new version of `pyxform`

Development
1

The long awaited pyxform upgrade is nearly here! We are in the final stages of testing/validating the branch of cht-conf containing the new pyxform. If you are an app developer with a set of CHT forms, I would love it if you could test converting your forms with this beta version of cht-conf and report back here about how it went! :folded_hands:

How to test the beta version

Install the beta version of cht-conf:

npm i -g github:medic/cht-conf#uplift-pyxform

This new version of cht-conf comes with the upgraded version of pyxform already bundled. If you have pyxform separately installed in your local environment (e.g. for use with an older version of cht-conf), that version of pyxform will no longer be used.

Only the convert-*-forms and upload-*-forms actions should be affected by this uplift. Once you have installed the branch version of cht-conf, use the typical actions to convert your forms and upload them to a test CHT instance (I do not recommend testing this in production. :sweat_smile:) You should see a pretty significant different in the generated form xmls. This is expected as the form configuration has been updated to follow the latest spec.

If you see errors when converting the forms, check the logs and the change documentation below to see if your form needs updated.

Once your forms are successfully converted, upload them to a test instance and then confirm your workflows still behave as expected. Though the form xml has significant changes, the user experience in the form should not change.

Pyxform Changes

Note that this is not an exhaustive list, but includes everything I have found so far that might impact folks building/maintaining CHT forms.

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.
    • It seems that updates to these values do not cascade to the choice labels, but you can still load initial values from fields (e.g. from the calculation to default). These initial values will be displayed in the label for select_* questions that use that choices instance.
  • Support for randomizing choice order in select questions via the randomize=true parameter has been added.

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.
    • This should make it dramatically easier to review changes to forms.
  • Normal 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 not 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.
    • If a group/repeat does not have a label, the conversion will complete successfully, but will print a warning. This matches previous behavior for this case, but is not actually the desired experience. There is an open issue to remove the warning in the future.
      • If the group has the field-list appearance, no warning is printed.
  • Empty groups/repeats (without any child fields) now cause a pyxform error.
    • This error will be printed: Check the form for an empty group or repeat.
    • Previously, the empty group was just added to the form xml.
  • Duplicate choice names are now rejected by default - but can be re-enabled via the allow_choice_duplicates setting.
    • This means that by default you cannot have multiple entries in the same choices list with the same name.
  • The new pyxform will now warn when you are missing translation columns for any of the languages in the form.
    • So, if you have both label:en and label:fr, but only have hint:en and not hint:fr the form will convert successfully, but a warning will be printed.
3 Likes
CHT Dev Demo Hour - Thursday, Dec 4, 2025