Understanding web form version locking in Survey123
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 Power Automate and Make.com 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.
- First the quickest way, but the one I would not generally recommend. 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. Generally speaking, I would stay away from this option to let Survey123 automatically update the web form at runtime.
- One approach to help you test things out, but not quite a practical approach for production surveys. 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 https://community.esri.com/groups/survey123/blog/2019/02/06/survey123-tricks-of-the-trade-web-form-u...
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. This is the way I like to do 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. Before I republish a survey, I always test the survey with the latest version using the URL parameter as described above. Just to make sure it all works as expected.
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 version-locked. 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. Version locking also reduces the initial loading time of the form, because no dynamic upgrade is necessary.
Survey123 Web App JavaScript API and version locking
The Survey123 web app API is built to help JavaScript developers embed, style and interact with Survey123 web forms within web applications. You can learn more about this API through this introductory blog. The API reference is also a good source of info.
In developer samples and throughout the blogs and documentation you will often see that the API is imported using this URL: http://survey123.arcgis.com/api/jsapi This is the home of the API and always returns the latest available version of it (non-version locked).
If you rather lock the version of the API used in your web application to a specific version, all you need to do is to add the version number you want at the end of the URL. For example: http://survey123.arcgis.com/api/jsapi/3.13 will give you access to the 3.13 version specifically.
Just like there are benefits to version-lock your web forms, you may also want to consider version locking for your custom code.