Appearance
Best practices for version management
The following is a best practice guide to configuration management / version management of Forms, Building Blocks and Reference Data.
In general terms we want the following to be true as our solution and related configuration evolves.
- We want data that has been captured on prior versions to be visible and editable if the context allows.
- We want to be able to query and view prior versions.
- We want new information/data to be captured using the latest published templates.
- We want all persisted data to be medico-legally compliant (we know exactly what the user / healthcare professional was viewing at the time of capture).
- We want to be able to make changes in our development environment with minimal ceremony (breakages are acceptable), and minimal downstream impact on configuration (such as workflow triggers).
The tables below represent how change should be managed for forms versions (and related building-block and reference data) that have been used in environments downstream from the development environment, where we need to consider the impact on forms and data, reports etc. Specifically we need to consider the impact on:
- Previously captured and completed forms - can we open the Read and PDF views.
- Draft forms - which are likely to be subsequently edited and completed.
- Submitted forms which can be amended.
- New forms created with the latest published template / versions.
Up-versioning cascade
Whilst it is good practice to up-version to indicate the changing nature of the data schema, this can (and should) have downstream consequences for consumers of that data.
Within AireForms, if you up-version reference data (not generally required), it is recommended you up-version any building-blocks that use this latest reference data version. Similarly, if you up version a building block and you update a form to point to this updated version, the form should also be up-versioned.
Beyond AireForms, up versioning of a form may impact:
- AireFlow custom events / workflow triggers (typically form custom events in AireFlow are
<form-key>-<version>). - AireGlu endpoints - If you have any AireGlu endpoints that process the form data - for instance SinglePass form delivery channels - they might need to be updated/up-versioned to match the new form data schema.
- AireForms extract APIs - Changing a form or building block (with or without up-versioning) necessarily alters the data returned from the extract APIs. Any services that consume these APIs will need to be examined for impact - hence why up-versioning is recommended for any breaking changes of published forms.
- AireFrame data extracts - AireFrame data extracts in turn depend on the AireForms extract APIs, and so up-versioning can thus require re-configuration of AireFrame datasets / widgets as well depending on the tenant configuration.
Reference Data
Reference data is used when common value-sets sit externally to one or more building blocks. Reference data is a special case in terms of version management as it has a built-in capability to deprecate terms in the value-set meaning that some changes are possible without up-versioning. The table below shows what the recommended course of action is with any given change (🟢 - no need to up-version, ❗ - up-version required, ⚠️ - depends on exact circumstances).
| Change | Consequences | Up Version? |
|---|---|---|
| Remove (deprecate) an existing term | Existing persisted form data will contain the deprecated term. As the term is deprecated the form will load and the deprecated term will be visible. If the form is submitted it will just be displayed. If the form is draft the term will appear in the control it will be displayed, however if the value is deselected the end user cannot re-select it. New forms will not show the deprecated term as an option in the control. | 🟢 No |
| Minor change in term label | Existing term is modified (for instance to fix a typo). Draft, New or amended forms will show the new term. Saved forms will be saved with the label the user saw at the time of completing the form (for medico-legal compliance). | 🟢 No |
| Semantic changes in term label | Existing term is amended that changes its meaning in a material way. This will affect interpretation and reporting and is strongly discouraged, it is better to deprecate the existing term and add a new term. If you have to do it you will need to up-version. | ❗ Yes |
| Adding a new term | You are adding a new term to an exiting reference data value-set. All the other terms are left unchanged. Technically and data wise this is not a problem for AireFrame, however consideration of whether this is a breaking change is whether the new term is semantically similar or a subset of the existing terms. If it is, it is best to consider it a breaking change from an interpretation and reporting point for view and up-version. | ⚠️ ? |
| Sub-divide a term | Refine an existing coarse grained term into two or more, fine grained terms. This can be managed by relabeling the original term and adding other terms (not recommended), or deprecating the original term and adding the new fine grained terms. From a reporting / interpretation perspective the change is large enough to warrant up-versioning. | ❗ Yes |
Building Blocks
Forms are comprised of one or more building blocks and building-blocks can be used across many forms: as such building blocks require the utmost care when managing change. The table below shows scenarios that you might consider a breaking change and should up-version the building-block. When you up-version a building block the new building-block version is not automatically applied to forms that reference the building block. Instead you will need to amend the relevant forms to use this later version (the form designer UI will indicate when you are not using the latest available version).
The table below represents changes, and what is considered a breaking change. A breaking change is where either the data structure is change and/or the semantics affecting how a user might fill out a form is changed in a significant way.
The guidance below assumes you are using the shorthand $<control-name> XPath notation rather than full/relative XPaths (both within the building block and for any cross building block logic). If you are using relative XPaths it is recommended you update the logic to use the dollar shorthand notation, both for clarity and reduction in fragility of XPath logic. The only exception to this is the need to use relative XPaths in some repeat control scenarios - for instance counting the previous items in a repeat.
| Change | Consequences | Up Version? |
|---|---|---|
| Add a new non-mandatory control | The data in the building-block now includes an additional field associated with the control. Strictly speaking this is a breaking change, however data captured before the control will still load in edit, read and PDF views so it will depend on the specific uses of this data - for instance could the change effect consumers of the extract API. | ⚠️ ? |
| Add a new mandatory or conditionally mandatory control | The data in the building-block now includes an additional mandatory field associated with the control. This is a breaking change. Draft or baselined data already held in the database will not conform to the data schema leading to potential run-time errors. | ❗Yes |
| Remove a control | The data in the building-block no longer includes the field associated with the control. Strictly speaking this is a breaking change, but depending on your local configuration you could satisfy yourselves that this is a change which does not need up-versioning - for instance that data item did not appear in any extracts / reports or visualisations. | ⚠️ ? |
| Layout changes | As long as all the controls remain consistent in the building block you are fine to change the layout. | 🟢 No |
| Adding or removing sections | As long as all the controls remain consistent in the building block you are fine to change the layout including adding or removing sections. | 🟢 No |
| Adding or removing a repeat | This materially changes the data captured / the data format. | ❗Yes |
| Minor change of the label(s) of a control | This could be to correct a typo, add or amend hint and help text where it does not meaningfully change the semantics of the form control for end users. | 🟢 No |
| Semantic change of the label(s) of a control | Generally speaking changing the semantics of an existing control is not recommended. If you have to do it, consider it a breaking change. For instance consider the impact in terms of understanding the data where you change a question from What is your gender? to What is your sex? | ❗Yes |
| Renaming the Control Name | Generally speaking altering the Control Name is not recommended. If you have to do it, consider it a breaking change as it will change the building block / form schema and will break existing persisted data or anything that depends on the data schema and extract APIs | ❗Yes |
| Up-versioning of the reference data associated with a control | This could mean existing data will no longer load if the reference data has changed in a breaking fashion - up versioning is needed. | ❗Yes |
| Changes to validation logic | If validation logic (including constraints) is changed it could mean that whilst the data will load, it could give rise to validation errors that the user is unable to address. | ⚠️ ? |
| Changes to calculation logic | If calculation logic is changed it could mean that existing data will not be consistent with the new logic (updates will only be applied on edit). | ❗Yes |
| Changes to initial value logic | If initial value logic is changed it won't negatively impact existing data captured, only new. | 🟢 No |
| Changes to visibility logic | This might be ok in exceptional circumstances, however if the updated visibility logic makes some mandatory fields visible/hidden it could potentially break some downstream services that may have made assumptions that the field would be present. It is recommended to treat this as a breaking change | ❗Yes |
| Changes to read-only logic | In general terms this should be ok, however care must be taken not to make a mandatory field read-only for any previously persisted data. For instance if the field was mandatory on form amend, but there was a new rule that made it read-only based on different criteria you could be left with a form that the end user cannot submit due to validation issues. | ⚠️ ? |
| Changes of data type from Number, Date etc. to String | Generally speaking it is ok to change the data type of a control from a more narrowly typed value (Email, Date, Date / Time, Number etc) to a simple String. However care should be taken on the impact of extracts etc. which may rely on the stronger typing | ⚠️ ? |
| Changes of data type from String to Number, Date etc. | Changing the type from String to a narrow type such as Date, Email offers no guarantees about existing persisted data. It is a breaking change | ❗Yes |
Forms
See below details of form changes that are considered breaking / non-breaking.
| Change | Consequences | Up Version? |
|---|---|---|
| Up versioning of one or more building blocks | This materially changes the form schema and/or semantics and should be considered a breaking change. | ❗Yes |
| Adding or removing a building block | This materially changes the form schema and should be considered a breaking change. | ❗Yes |
| Adding or removing form pages | Assuming you are not adding or removing building blocks, changing the layout by adding or removing pages and moving building blocks between them does not alter the form schema, it is purely visual. Only consideration is whether there is any cross building block logic where the form order is important | 🟢 No |
| Changing the form label | Assuming this does not alter how users will perceive the contents of the form (for instance in a clinical record or a report), it is fine to change the label of a form. | 🟢 No |
| Disallowing save draft | No up-versioning is required. Any existing draft can be launched and edited until such time they are submitted. No new drafts can be created. | 🟢 No |
| Allowing save draft | No up-versioning is required. | 🟢 No |
| Disallowing amend | This is ok to change without up-versioning. In flight amendments can proceed to conclusion, but no new amends will be allowed. | 🟢 No |
| Allowing amend | This is generally fine to change without up-versioning as existing data will be there as the current baseline ready for amendments if needed, however consideration should be given to any impacts on downstream services such as workflows that may also fire on amendment as well as initial save. | ⚠️ ? |
| Disallowing discard | This is ok to change without up-versioning. Prior items that were discarded will remain as they were, no new items can be discarded. | 🟢 No |
| Allowing discard | This will simply allow any in-flight or new drafts to be discarded. | 🟢 No |
| Changing form context | This does not directly alter the form schema, however it might alter the behaviour of the form/building-blocks that may have rules configured against the form context - so needs to be considered - but up-versioning is not required. | 🟢 No |
Form level building block configuration
The following are changes that you configure at the building block level.
| Change | Consequences | Up Version? |
|---|---|---|
| Adding or altering cross-building block relevance logic | This effectively alters the form schema, some items that might have previously been considered mandatory could no longer be present. Existing drafts might be missing whole building blocks of data | ❗Yes |
| Changing building block pre-population rules (enabling / disabling and changing the days) | Pre-population is an end user / workflow optimisation and does not affect the form schema. It is fine to change the rules without up-versioning. | 🟢 No |
| Changing to locking pre-population by correlationId. No guarantees can be made about the provenance of pre-existing data, however you do not need to up-version when you enable correlationId pre-population. | 🟢 No | |
| Setting a building block to be data only. | Does not affect the data schema | 🟢 No |
| Changing a building-block view from edit to readonly. | This could mean that draft form data with missing mandatory fields can never be amended / submitted. | ❗Yes |
| Moving the position of a building block in a page or across pages. | As above - other than considering form order and cross-building block XPaths - this is fine to change without up-versioning. | 🟢 No |