What is Version Reference and how should it be used?

Version Reference is used to keep track of fields across different versions

So what is this used for and what does it mean for Users, Administrators, Report Builders and Management?

In the Form or Issue/defect/record "Wizard", when editing a field there is Version reference under Metadata.

What happens when you create a new version?

Every time you create a new version, new fields are generated based on the old version and they are completely separate from the old ones. The only thing that ties the new fields to the old ones is called "Version Reference".

So what is Version Reference?

A version reference is a unique identifier that is generated every time you create a field in the wizard. Even though it is shown in the dialog as the name of a field in the previous version, it is actually an ID that consists of random letters and numbers.

When a new version is created, all properties of the fields are copied over, including things like title and version reference. Please note that you can always edit the title, resize the field and even change the field type. 

The way the system knows that a field in the new version is actually equivalent to the one in the old version is this version reference. When two fields share the same version reference across different versions, the system understands that they are meant to be the same, even though they are completely separate fields.

What does Version Reference do?

Let's say in the first version you have a text field for the name of a person who fills in the template. You have been using this template for a while before you decided to make a new version of the template and change this field to a user field for people to pick from a dropdown list. Here we have completely separate fields in 2 different versions, and they do not share the same field type. Despite this, we want to let the system know that these fields are meant to be the same.

When you edit the version reference, you can pick a corresponding field from an older version of the template to indicate which field this is equivalent to. These two fields will then share the same version reference and the system will treat them as the same thing, albeit in two different versions.

Later on, when you export a CSV file of the data you have in your templates, or when you carry out analysis in PowerBI, the system knows that those 2 fields are equivalent and is able to put the data in the same column. This makes analysis possible between fields in different versions while preserving data in older versions. This is the backbone of versioning and how the system keeps track of everything.

When should you edit Version Reference?

Generally, you don't need to edit it manually because it is copied over every time you create a new version. So you can edit the title and change the field type without having to edit the version reference because it is already there.

The only time you need to do so is if you "Delete" a field and create a new one to replace it. As the system does not track the fields based on the title, creating a new field and giving it a title that is the same as the one in the old version is not sufficient to let the system know that they are same. 

In that case, check the version reference and see if it says "None". If so, edit it by picking the corresponding field in the old version to fill in the correct version reference so everything can be tracked properly.

Version reference can be edited at any time, even after a template has been published. So if you have missing version references in your fields, you can always go back to your older versions and fix them. Version reference always goes in one direction. Only new fields can reference old fields, not the other way around. If you have extra fields in your new version, you can leave the version reference as "None" to let the system know that these are new fields and do not correspond to anything in the past.

e.g. Form template

Issue template