Page Comparison

...

You can see detailed instructions on how to set up the Excel file here. 

Note: This tool (XLSForm) is provided by a third party, and it is not within the responsibility of the Dimagi/CommCare support team to maintain or support.

Overview

Build your form in Excel (following the instructions on http://opendatakit.org/use/xlsform/) and then upload it to XLSForm (http://opendatakit.org/xiframe/). You can then download the XForm and upload it into our form builder on HQ.

As you build your form you can test it online using the validation tool: https://opendatakit.org/use/validate/

...

Example: In CommCare's Form Builder, a display condition might look like: /data/pizza_fan = 'no' while in Formhub it would look like: ${pizza_fan} = 'no' - these will be updated when the xml file is generated

• To avoid issues with itext and how CommCare deals with languages make sure to specify the language in the header. For example, if your app is only in English then make sure to put "label::en" instead of just "label" - if you do CommCare will add two languages (default and English).

• To keep using "data" as the ID of each form (the CommCare standard), please be sure to name your excel file "data". CommCare may not recognize the "settings" tab of the Excel file described XLSForm.

• Labels (called "notes" in the other tools) are often treated as text questions when the form is uploaded to CommCare. There are 2 easy ways to address this issue. #1 You can change the question type from Text to Label in the CommCare form builder. This is a known issue and will eventually be fixed.  #2 If you use the question type "acknowledge" then CommCare will interpret that as a label with the checkbox confirmation turned on.

• You can test your forms online using https://opendatakit.org/use/validate/

Using non-Latin languages and alphabets in the XLSform-XML process

If you choose to use XLSform's ability to handle multiple languages, by reading the XLSforms documentation and adding additional columns to contain the additional language content, please note the following:

• The XLSform documentation tells you to create additional columns and give those new columns headers like label::English.  However, if your purpose is to eventually paste that XML into CommCare, then you need to be careful about what the title of the language you use in those column headers. For commcare use, you should not use the full language name like "English," but instead must use the "short language codes," such as en and tha,that are shown in the little "Languages" pull-down menu in CommCare's left nav bar. Therefore your additional column headers will look like label::en  or required_message::tha.

• If your additional language content uses alphabets other than the latin character set, you will have to be careful about the way that you handle the process of copying your finally converted XML file into CommCare. Normally, many users would simply double-click the XML file that they had downloaded from the converter, select-all and copy, and then paste that XML into the CommCare forms editor. However, on Windows, it is likely that the default application that loads when you double-click the XML document will not display the non-latin character set correctly, and will therefore paste as gibberish into your CommCare form. If this happens, then, when you download the XML document from the converter, open it in a text-editing application that is more able to handle non-latin alphabets (one example is the Notepad++ app for Windows.) This app will correctly handle the non-latin characters in the XML, and then you can successfully cut-and-paste from that app into the CommCare form editor.

Known Limitations

There are some things that don't work well when uploading a Formhub form to CommCare; these are active efforts to make these more compatible

• You may get an error message when uploading your form that CommCare xmlns will be added. You can ignore this message. If, once inside the Form Builder, you see a persistent error message about the Form Name make any minor change in the form, save, and refresh the page.

• When first opening your form to edit you may see a message that says "id is not defined." Just click "ok" and then make any minor change in the form, save, and refresh the page.

• If you have multiple languages in your Excel form but not in your CommCare app, any additional languages that are not already in your app will be deleted.  Before uploading anything go to the application -> languages and make sure all languages are added. On the languages page you will see that each language has a 2 or 3 letter code (English = en; Hindi = hin). In your Excel file you must use those codes in the headers. So for English you would use "label::en" as the header for the label column on both tabs of the Excel file. These are case sensitive.  Alternatively you can upload the xform with one language, add the additional language, and then use Bulk Translation to add additional languages.

• Both tools described here uses the name of you Excel file as the root of all of the xpaths in your form. So if you call your file "survey" then your data will look like /survey/question4 instead of /data/question4. You cannot change this after uploading into CommCare. We recommend that you name your excel file "data" if you want to be consistent.  

• The "add other option" for multiple choice questions will generate the "other" question with the correct question ID but will not generate the correct skip logic.

• You may also notice some extra "hidden values" at the bottom of your form after using the Excel tools. You should delete these.  These hidden values are formhub, uuid, meta and instanceID.  

• Advanced features link hint text, multimedia, read-only, and complex logic may not be well supported.

Shortcut for creating the XLSForm format from CommCare's Export Form Contents

...