ichivite-esristaff

Understanding web form version locking in Survey123

Blog Post created by ichivite-esristaff Employee on Jan 24, 2020

With every new release of Survey123, we include fixes, enhancements and new features into Survey123.  For the most part, having access to the latest and greatest fixes and features is straight-forward:

 

  • Survey123 field app: Install the latest Survey123 field app from the app stores.
  • Survey123 website: Reload the Survey123 website in your browser.
  • Survey123 report service: Nothing to do... every time you request a new report, the latest report engine is used.
  • Survey123 Microsoft Automate and Integromat modules: All changes get applied right away in run-time and design modes.

 

But what about your web forms? Well it depends so that is why I thought it would be worth going in detail over this.

 

Survey123 web form version locking

 

Survey123 web forms are version locked by default. That is, a web form (unless specified otherwise) will always use the version of the Survey123 web app that was current when you last published the survey.  This basically means that any new fixes and enhancements we apply to new versions of Survey123 do not take effect over your already published web forms.

 

We apply version locking by default because we want to make sure your surveys always behave exactly as when you published them, regardless of changes in newer versions of Survey123.  It is true that new versions incorporate fixes and enhancements, but they can also bring unexpected changes that may break your existing surveys. 

 

Three ways to upgrade your web forms

 

If you would like to upgrade the version of Survey123 used to render your web forms, you have different options.

 

  • You can disable version locking in your survey through the Settings tab of your survey. In the screenshot below, you can see that I have a survey that was published with version 3.5. If version locking is enabled, then the 3.5 version of the Survey123 web app will always be used to render the form. By activating the option to 'always use the latest version', the web form will always run on the latest and greatest version.

 

 

A handy preview link right by the 'always use the latest version' option is available so you can validate that all looks good before you make a change.  I strongly suggest you always preview your survey to make sure everything behaves as expected.

 

Choosing to always run your web forms against the the latest version of the Survey123 web app available is tempting, but consider the following:  First, by disabling version locking you are forcing a dynamic upgrade of your published survey to the latest version when the survey is loaded in your browser. We do our best to minimize the impact of upgrading your web forms on the fly, but this could slow down the loading time of your form.  Second, with every new update there is always a chance that something could break. If you disable version locking you lose control over which version of the Survey123 web app will be used to render your form.

 

  • You can force your web form to use the latest version available of the Survey123 web app by adding the version=latest query parameter to the URL. For example:

https://survey123.arcgis.com/share/<your_survey_id_here>?version=latest

Note that version=latest has been added as a query parameter to the URL.  You can combine version=latest with other query parameters as described in Survey123 Tricks of the Trade: Web form URL parameters 

 

I like to use this technique to thoroughly test out my surveys before I upgrade them to the latest version, but I do not like to share URLs with the version=latest parameter in them because people may accidentally or intentionally remove it.

 

  • Finally, you can upgrade your survey web form by republishing it.  With this approach, your web form is upgraded to the current version of the publishing tool (Survey123 Connect or Survey123 web designer) you use. By keeping version locking activated, your web form is always cached and ready to go (no on the fly upgrades). You would need to republish it again if in the future you consider that you need to upgrade the web form version.

 

All in all, I personally prefer to decide when to upgrade a web form. If a web form is working all good, I leave it alone: Don't change anything that works!  In the event that I want to leverage a particular fix, enhancement or new feature in a more recent version, I first validate my web forms with the latest release (using version=latest), and then I republish the survey to upgrade the web form.  Knowing that my web form is version locked and running on the exact version I want gives me extra peace of mind.

Outcomes