Template Versioning and Customisation
Template versioning tracks changes to the template over time. Versioning occurs when a template that has been "published" is modified. This is done to prevent existing plans that were based off of the original template from becoming invalidated. Plan creation always uses the "published" version of a template.
The system generates a complete copy (phases, sections and questions) of the original published template. The user's modifications are then applied to this new copy.
There are two attributes/columns that facilitate this workflow:
-
templates.family_id- This value is used to connect all versions of a template. It is generated when a user creates a new template. The value is copied (remains unchanged) when the system creates a new version of a template. -
[templates, phases, sections, questions, question_options].versionable_id- This value is used to customisation of a template and its use is described below
Template customisation allows an Org Admin to add additional question specific guidance and example answers to a template that was authored by a different Org (often a funder template). It also allows them to add additional sections with their own questions.
Customisation becomes complex when a template is versioned and then republished. When this happens, the Org Admin that owns the customisation sees a visual cue on in the UI that lets them know that the original template has changed and they are provided with a link to "transfer their customisations".
When an Org Admin customises a template, the system makes a copy of the original template but generates a new family_id for the customisation and places the family_id of the original template into the customization_of field.
If the Org Admin publishes their customised copy of the template and later makes changes, the same versioning rules as described above apply. The customization_of value remains associated with the family_id of the original funder template across all versions of the customised template.
When a new version of the original template is published and the Org Admin who owns the customisation attempts to transfer their customisations. The following describes the process of customisation transfer:
Some terminology to start with:
- The customised template based on the original funder template (call this CT)
- The original funder template that it was customised from (FT);
- The new version of the funder template (NFT).
Where we want to get to in a new version of CT which is NFT + whatever customisations were added to create CT in the first place (NCT).
We do this by:
NCT = copy of NFT
for each phase in NCT
find it in CT by matching versionable_ids
if found
we now have NCT_phase and CT_phase
for each section in CT_phase
if they are modifiable then pull them over to the NCT and renumber them if needed
(if a new section was added to NFT then the customised section will clash with it so needs renumbering).
So the new template starts off with everything in the new funder template and then adds in anything from the old customised template which looks like a customisation (identified by the fact that it is modifiable) Note that this process uses versionable_id to match phases but NOT sections. Sections get pulled over based on their modifiable status.
There is also code using versionable id's to match questions which is used by annotations and conditions.
 |
 |