Skip to main content

Blueprint Versioning

Report Forge automatically saves a version of a blueprint each time it is published. You can view version history, compare versions, and restore a previous version at any time. This provides a complete audit trail of every structural change made to a report blueprint over its lifetime.

How versioning works​

When you publish a blueprint, the current state is saved as a named version with:

  • A version number (incrementing integer).
  • The date and time of publication.
  • The name of the user who published it.
  • An optional version note.

Draft changes are not versioned — only published states are captured. If you save a blueprint mid-edit without publishing, no version is created.

What is versioned​

Each blueprint version captures the complete blueprint state at the time of publication:

Versioned elementDetails
SectionsNames, descriptions, display modes, order.
FieldsField names, types, configurations, required/optional, visibility rules.
Form designer layoutTab structure, column layout, FormBlock configurations.
Section permissionsRole-based view/edit access per section.
Output templatesThe output page layouts bound to the blueprint.
Lifecycle settingsStatus workflow configuration.

Viewing version history​

  1. Open the blueprint in the Blueprint Designer.
  2. Click Blueprint settings in the header → Version history.
  3. A list of published versions appears with:
    • Version number.
    • Publication date and time.
    • Publisher name.
    • Version note (if set).

Comparing versions​

  1. In the version history list, select a version.
  2. Click Compare with current (or select two versions and click Compare).
  3. The comparison view shows a side-by-side diff of:
    • Sections added, removed, or renamed.
    • Fields added, removed, renamed, or reconfigured.
    • Permission changes.
  4. Use the comparison to understand what changed before deciding whether to restore.

Restoring a previous version​

  1. Open the version history.
  2. Click the version you want to restore.
  3. Review the version in the preview panel.
  4. Click Restore this version.
  5. The blueprint returns to a Draft state with the restored content.
  6. Make any adjustments if needed.
  7. Publish to make the restored version the active blueprint.
note

Restoring does not delete newer versions. The full history is preserved even after a restore.

Version notes​

When publishing, optionally add a brief note describing what changed. Version notes appear in the history list and make it easier to understand the changelog without opening each version:

Good version note examples
"Added cost variance field to financial section"
"Removed duplicate risk columns — v2 structure"
"Updated form layout — 2-column form for schedule section"
"Added section permission for commercial section (Edit: Commercial Manager only)"

Managing versions​

Versions accumulate over the life of a blueprint. There is no limit to the number of versions stored. To keep the history readable:

  • Write descriptive version notes on every publish.
  • Use the Mark as milestone option on key versions (e.g., the version used for a major project gate report) to highlight them in the history list.
  • Old versions cannot be deleted — this is by design for audit trail integrity.

Blueprint lifecycle​

Each blueprint has a lifecycle status that controls its availability to contributors:

StatusDescription
DraftChanges in progress. Not visible to contributors for new editions.
PublishedActive version. Editions can be created from this blueprint.
ArchivedRetired blueprint. No new editions can be created. History is preserved.

Transitioning between states:

TransitionHow
Draft → PublishedClick Publish in the Blueprint Designer.
Published → DraftClick Unpublish (Admin only). Existing editions are not affected.
Any → ArchivedAdmin → Blueprints → Archive.
Archived → DraftAdmin → Blueprints → Restore.

Impact of blueprint changes on existing editions​

When you publish a new blueprint version after editions have already been created:

Change typeEffect on existing editions
Add a new optional fieldExisting editions show the field as empty.
Add a new required fieldExisting editions show the field as incomplete — they may need to be updated before the next cycle.
Remove a fieldExisting editions retain the data but the field is no longer shown in form/grid mode. Data is preserved in the database.
Rename a fieldExisting editions reflect the new field name immediately.
Change field typeMay cause display issues if the stored data type is incompatible. Consult the Admin before changing types on live blueprints.
Modify form designer layoutApplies to all editions opened after the publish.
Change section permissionsApplies immediately to all editions.
caution

Changing field types on blueprints with existing editions can cause data display issues. Always test structural changes on a duplicate blueprint before applying to a live reporting cycle.

Pre-publish checklist​

Use this checklist before every publish — especially for moderate or major changes — to avoid disrupting active reporting cycles.

1. Identify active editions​

  1. Go to the blueprint → Editions tab.
  2. Filter by status: Draft, Submitted, In review, Changes requested.
  3. If active editions exist, decide whether to:
    • Wait: Hold the publish until the current cycle completes.
    • Coordinate: Notify contributors and reviewers of the upcoming change.
    • Proceed: Only if the change is minor and will not affect the current editions.

2. Classify the change​

Change typeSafe to publish with active editions?
Minor (label, help text, option label)Yes — no impact on active editions
Moderate (add non-required field, add option)Yes — notify contributors
Major (add required field, remove field, change type)No — wait for active editions to close

3. Test with a test edition​

  1. Create a test edition from the blueprint in its current (Draft changes) state.
  2. Fill in all sections — verify new fields, validation rules, and expressions work as expected.
  3. Generate a test output — verify the output template renders correctly with the new blueprint structure.
  4. If any issues are found, correct them before publishing.

4. Write a version note​

Before clicking Publish, write a version note summarising the changes. A good version note:

  • States what changed (e.g. "Added 'Recovery Plan' field to Schedule section")
  • States why (e.g. "Required by PM for at-risk editions")
  • Notes any contributor action required (e.g. "Existing editions in Draft must fill in the new field before resubmitting")

5. Notify contributors​

For moderate or major changes, send a notification to active contributors before publishing. Include:

  • What is changing
  • When it will be published
  • What action (if any) is required on their current edition

6. Publish and verify​

  1. Click Publish and enter the version note.
  2. Verify the published blueprint in the designer — confirm the new fields and layout are correct.
  3. Open an existing edition — verify that existing data is intact and the new field appears correctly.
  4. Check the Version history tab — confirm the new version appears with the correct note.

7. Low-activity publish window​

For major changes, choose a low-activity window:

  • Avoid publishing at the start of a reporting cycle (when many contributors are entering data simultaneously).
  • Prefer end-of-day or end-of-week when fewer editions are in progress.
  • For global teams, coordinate with the team in the most active timezone.