Form Versioning

Form Versioning can extend the capabilities of any project cycle by giving users the ability to evolve current forms while preserving the integrity of previous iterations. Form Versioning allows for detailed deployment tracking, allowing teams to see who has updated a form, when a change was made, and any notes accosted with the update. Additionally, Form Versioning can be used to revert to previous incarnations while safeguarding all submission data.

Form Versioning is limited to Enterprise level projects. Users without an Enterprise level project can still experience versioning via any Trial level project.

Enable Form Versioning

To get started, create or enter an existing project. For the purpose of this walk-through, an HTML element will be anchored to the top of each form to keep track of the current iteration.

To enable Form Versioning, expand the Advanced Settings tab by clicking on it.

In the Form Revisions section, expand the select dropdown menu and select either Enable option.

Form Revisions can be configured in two different ways:

  • Enabled – Use current form version when viewing submission
    • Will display all form submission data in the most recent form revision.
  • Enabled – Use original form version when viewing submission
    • Will display form submission data in the form revision that it was captured in.

This functionality extends to wherever users choose to view their submission data. This includes viewing their data from within the <form.io> platform or externally like inside the users application.

Afterwards, click either Create Form if creating the a new form or Publish when interacting with an existing form. Once saved, Form Versioning is now enabled and the Revisions tab is now available for user interaction.

Once inside the revisions interface, users can see the full scope of their current development cycle. Important information such as who made the revision, when the revision was made, the revision number, and any notes made are all available. Additionally, several actions are now available.

  • Use
    • Will enter the traditional form Use tab in that form revision.
  • Data
    • Will display form submission data that was captured in that form revision.
  • Restore
    • Will make a clone of the current revision, iterating the Vid to the most recent revision.

These items will be covered in depth further down.

Creating Form Revisions

With Form Versioning enabled, users can begin iterating through different form revisions. Note that this revision has a new field added. Additionally, this guide has iterated the tracking HTML field manually to illustrate a change in form version, this is not an automatic process.

At the bottom of each form, users can enter a revision note that will appear alongside other important information in the Revisions tab once published.

Once complete, pressing the Publish Form action will create a new revision and will be visible on the revisions page.

Note that the system has automatically iterated the Vid number now that multiple revisions exist.

Using Form Revisions

By default, the Use tab will display the most recent form revision (the one with the highest Vid).

However, users can interact with the Use action from within the Revisions tab to use specific form revisions.

When using Vid #1, the original form is displayed, notice how (C) Version Field is no longer present.

When using Vid #2, notice (C) Version Field is present again as well as the change to the tracking field.

Viewing Revision Data

A 3rd revision has been added where (B) Version Field has been removed. Additionally, the following submissions have been made to each for form version:

  • Version 1: 2 submissions made
    • (A) { Apple1, Apple2 }
    • (B) { Banana1, Banana2 }
  • Version 2: 3 submissions made
    • (A) { Apricot1, Apricot2, Apricot3 }
    • (B) { Blueberry1, Blueberry2, Blueberry3 }
    • (C) { Cherry1, Cherry2, Cherry3 }
  • Version 3: 2 submissions made
    • (A) { Avocado1, Avocado2 }
    • (C) { Carrot1, Carrot2 }

A simple inspection of the Data action for Vid #1 will reveal the two submissions listed in the table above.

Notice that only submissions made using Vid #1 are displayed. Ergo Apricot and Avocado entries are not present.

To view all submissions, click the Data tab at top and all 7 entries will display.
Notice, that (B) Version Field entries are not displayed.

Not to worry, as illustrated above, the data is still there. Recall that the most recent form revision removed (B) Version Field and as a result the data table only displays key value pairs that exist within the active form.

Restoring Form Revisions

Since (B) Version Field data is hidden due to the current form revision not having that field, the restore action can be evoked to recover the former layout. From the Revision tab, selecting Restore will being the restoration process.

Afterwards, users are redirected to the form editor where additional revisions can be made, a revision note can be made, and other components added. Notice, that (B) Version Field has been restored and a note has been made.

Upon publishing the form, a return visit to the Revisions tab will reveal a new revision, Vid 4. Additionally, the note made during the restoration process is also visible.

It is important to note that restoring a form does not overwrite or alter the original revision. Instead, a new revision is made which is why there are now 4 revisions. Continuing, a visit to Data tab will reveal that (B) Version Field and its respective data, has returned.

Creating Form Drafts

Form Versioning also supports a draft feature where changes can be made without publishing a new version. Continuing with the example, (D) Version Field has been added and saved as a draft.

An inspection of the revisions tab will reveal that a draft now exists.

Drafting is primary used to test form construction without overwriting the active form revision. As a result once a draft is published, it will disappear from the revisions page. Lastly, there can only ever be one active draft at a time.