Guide to Form Schema Configuration

Introduction

Form templates in the Ctrl Hub platform are configured as JSON schemas.

In general, changes to form schemas must only be carried out by trained Ctrl Hub staff, however there are several customer-managed changes that can be made. These are detailed in the ‘Customer Manageable Changes’ section later in this document.

Summary

1. Only modify content listed under Customer-Manageable Changes.
2. Test any schema changes in a Test Form first before applying to a live schema.
3. Always make a backup of a live schema before applying any changes.
4. Send any modified schemas to Ctrl Hub to keep on record and for reference for support.
5. Issues resulting from unauthorised schema changes will be supported but are outside the scope of the Standard Ctrl Hub Support Agreement.

The Form Template JSON Schema Structure

A Ctrl Hub Form Schema consists of the following core sections: fields, sections & behaviours

Fields – contains the definitions for all fields contained within the schema.

Sections – defines the structure and sequence of fields and sections within the schema.

Behaviours – used to (1) define validation rules, (2) calculate field values and (3) apply conditions to the setting of field properties such as ‘conditionally mandatory’ rules.

In addition to these sections, a schema may also contain sections for presets, list_columns and others. Modifications to these sections should only be made by trained Ctrl Hub staff.

Customer-Manageable Changes

Customer-managed changes are limited to the following elements within the fields section.

Any other content within a Ctrl Hub Form Schema CAN be edited, however issues resulting from unauthorised schema changes, including loss of data or loss of access to a form or submissions, are not covered under the Standard Ctrl Hub Support Agreement. In such cases, please contact support@ctrl-hub.com as soon as possible.

Values in CHOICE fields

Caveat: Values in CHOICE fields may be used in behaviour logic. Before making any changes to this type of field, contact Ctrl-Hub for confirmation of impact.

The choices node contains the values that are displayed in dropdown / choice fields in a form submission. In the example above, if you wanted to add a third choice, eg, ‘Not Applicable’, the modified content would look like this:

The first value, eg Not Applicable, is the content displayed to the user in a form submission; the second value, eg NA, is the content stored in the database when a submission is saved.

Field labels

Where a field does not have a label defined, or is defined as “label”: false, the label may not be used, or may be defined elsewhere in the JSON schema. In this case, CONTACT CTRL-HUB FOR GUIDANCE BEFORE MAKING CHANGES.

HTML Text

The HTML field type is used to display styled content within a form. In the screenshot above, the text content will be displayed in a submission in a red colour with a bold (strong) font.

Modifying Form Schemas

Before making schema changes

Before you make any changes to a form schema, make sure you have a copy of the current version of that schema, to allow you to revert should you introduce any issues.

To make a copy of a schema

1. Firstly, go to Forms, find the form you wish to edit and choose Update from the dropdown action menu. (Contact Ctrl Hub for guidance if you do not see these options as this requires elevated permissions.)

2. Select the Schema tab, click into the main body of the schema and Ctrl-A to select all content, the Ctrl-C to copy that content.
3. Now you can choose Cancel to close this page.

Next, add your copied schema content to a test form.

Using a test form allows you to test your changes safely before committing to making modifications to a live form.

1. The first time, create a new Test Form as follows.
   1. Go to Forms and select Create Form (If you do not see these options, contact Ctrl Hub for guidance as elevated permissions are needed)
   2. Reference – give your form a unique reference, eg test_form_001
   3. Label – give your form a label, eg Test Form 001
   4. Category – select a Category. (If no categories are available, contact Ctrl Hub for guidance.)
   5. Workflow – select a suitable workflow. (Contact Ctrl Hub for guidance if unsure which workflow to choose.)
   6. As this is a test form, and not intended for live use, you may wish to tick the Hidden checkbox. (To find Hidden forms, there is a filter field on the Form list page, labelled Hidden that you can set to Show Hidden.)
   7. Description – give your form a description.
   8. Now select the Schema tab, click into the main body of the page and replace all content with the content of your clipboard (ie the schema you copied in the previous section).
   9. Select Create Form to save your new test form.

Over time, as you test schema changes, you can continue to use this Test Form and modify or overwrite the schema content. Equally, you may wish to create additional Test Forms, eg Test Form 002, etc for different uses – whatever works best for you.

Making schema changes

*Note* Never save a change to a live form schema without first having taken a copy of the latest version of the schema to revert to if necessary.

Now you have a Test Form, from the Forms list page, select Update from the action dropdown menu, as you did before, and select the Schema tab.

• Make your changes directly in this page or you may prefer to copy the JSON content to an external text editor (such as Notepad++, Visual Studio Code, etc), to make your changes there, then paste the content back into the Ctrl Hub form later.
• Once you are ready to test your changes, select Update Form.
• Then select New Submission to create a new submission. (You may prefer to right-click the New Submission button to open it in a new tab and keep the Form Schema open too.)

Form Schema Versioning

Each time you save changes to a form schema, a new version is created. When a submission is created from a form schema, it uses the latest version of the schema at that time.

You can update an existing submission to the latest, or another, schema version. To do this:

1. From the Submissions list page, find the submission you want to update.
2. Select that submission to open it.
3. From the dropdown action menu (right hand side), select Change Form Version.

4. In the Change Form Version window, you can see the latest and previous versions of the form schema in the Form Version dropdown list.

• The latest schema version is identified (at the top of the list, marked Latest).
• The current schema version for your selected submission is the greyed-out entry in the list (eg version ref 741d36 in the screenshot below).

If you choose to change the schema version for a submission, the system will attempt to update the submission content to match the chosen (most commonly ‘Latest’) schema version.

Tip: While testing changes to a schema, if you create a single test submission, using Change Form Version allows you to update that same submission to the latest version to test your changes, each time you save your modified schema.

*Important Note* Take care before choosing to update the schema version of an existing submission.

Any significant changes to that schema could result in a loss of data.

For example, if you have removed an option from a CHOICE field, that field would result in having no selected value. The same is true if any other schema configuration has changed significantly.