Introduction

Version Management

Version management can be tricky if not controlled properly. Versioning mechanism has numerous possibilities, but its a good idea to cover them with some additional logic. 

In that case actual version management can be performed behind the scenes and presented to the user as some sort of logical workflow. 

HyperDoc assumes that there is a Master Archive that is used as official repository and any number of Drafts that can be created by users, shared and published or discarded.

HyperDoc versions contain only change set - so no data is actually duplicated. Object created in one version will exist in the database as long as its not deleted. The version that the object was deleted in, will indicate its "end of life". If a user goes back to previous version, the object will be visible there. 

Sample use cases

Updates during building life cycle: in a non versioned system, all updates are made in place, overwriting any existing, historical data (Data update, floor plan change, sold properties, etc.). System does not allow to publish near future plans and data to be available in parallel to current data. A user of a new system should be able to work in parallel with historical, current and future plans and data.

Planned alternative layouts and building arrangements: user should be able to store alternative layouts for planning and presentation. This operation must not affect main archive that is used for everyday work and maintenance of the properties. FM systems should be allowed to interact with such alternative versions for simulations and reports.

Reporting in version context: user must be able to create reports that reflect changes in properties archive over a selected period of time. (Available space in for each quarter, number of properties, etc.)

Versioning Modes

Strict Versioning Mode allow changes in data to be made only in working drafts. Published Versions, as opposed to Drafts, cannot be changed in any way. This mode requires a new Version to be published each time a data change is required. Full audit trail is performed in this mode for each published version, as a smallest unit that is tracked. Changes performed in an editing session, within a Draft, are not tracked (consecutive changes are made in place, overwriting previous values entered in the same Draft). 
Relaxed Versioning Mode allows Version creation only when needed, Published Versions are not "sealed". Editing can be performed in selected Version overwriting existing information. Only the information about the latest change is stored. 

Drafts are simply working "copies" of entire database from the user point of view, but actually no data is duplicated, so the database growth is limited to necessary minimum (only storing incremental changes). 
Using REST API to insert, update, delete objects and documents in proper version must be provided. 

Summary for versioning modes:

• Strict - Changes are allowed in Drafts only
  • This mode that does not allow any changes in Master archive.
  • All changes must be done in Draft and published as a new Version.
  • This mode also enforces full audit trail - as all changes are recorded and cannot be overwritten. 
• Relaxed - changes are allowed in Drafts and in Master Version
  • A mode that allows creation of versions on demand
  • Allows any modifications to Master Archive
  • Consecutive changes made in Master archive in given version will overwrite each other. 

Additional Versioning options

SINCE V4.6

• Allow modifications if newer version exists (System flag: "doNotCheckNewerVersions")

  • editing of object metadata is allowed when the same object has newer versions (e.g. in Drafts - for strict mode, and both in Drafts and Master when in Relaxed mode)

  • before there was no possibility to update object, when there were modifications present in any of the existing Drafts

  • this parameter applies only to updates - we do not allow deletions, if there are some changes in future versions

  • System default: disabled

  • Q: is editing allowed if newer version exists in Master? A: yes, this option applies both to drafts and master archive

  • Q: is editing allowed when object is deleted in Draft or newer master version? A: yes

• Allow modifications of past versions (System flag: "allowPastModifications")

• allow modification not only in newest (tip) version of versions alternative (e.g. in drafts - for strict mode, and both in Drafts and Master when in Relaxed mode),

• before we have only checked whether we were working in draft or relaxed mode - from now only modifications in tip (newest version) of each version alternative are allowed by default

• System default: disabled (this was not default behavior before)

Example 1:

• System is in a relaxed versioning mode
• I have an object that is in the latest version of Master Archive
• This exact object is now modified in a Draft created by a user
• Can I modify this object in Master, since system works in a relaxed mode?
  • Yes, if "Allow modifications if newer version exists" is set to Enabled - as the version in Draft is "newer".

Example 2:

• System is in a relaxed versioning mode
• I have an object that is in one of the past versions of Master Archive
• Can I modify this object in Master, since system works in a relaxed mode?
  • Yes, if "Allow modifications of past versions" is set to Enabled (as you are trying to modify an object that is in a past version - non-tip version of Master Archive)
• Additionally, if this exact object is now modified in a Draft created by a user
  • Yes, if "Allow modifications if newer version exists" is set to Enabled

SINCE V4.6

• Allow add operations in Master archive (system parameter: "allowAddInMaster")

  • In relaxed mode, allow to create objects in Master

  • this option applies to adding all versioned entities: object, files, links, spots etc.

  • System default: Enabled

  • remarks: attaching content is treated as update object operation - should this be this way?

• Allow update operations in Master archive (System parametr: allowUpdatesInMaster)

  • In relaxed mode, allow to edit objects in Master archive (edit metadata, attach content)
    

  • System default: Enabled

• Allow delete operation in Master archive (System parameter: allowDeletesInMaster)

  • In relaxed mode, allow to delete objects in Master archive

  • System default: Enabled

Example 3:

What options are needed to perform object update in some older version from Master archive?

A: "Allow update operations in Master archive" set to true, "Allow modifications of past versions" set to true, and depending on given situation also "Allow modifications if newer version exists" set to true may be applicable

On a graphic below, blue dots represent versions of the same object in master archive and Orange dots represent versions of this object in Draft.

Can A3 be modified in place?

Yes, you will need the following options set:

• Relaxed versioning mode set to Enabled - to allow updates in Master (in general)
• Allow update operations in Master archive set to Enabled - to allow edit operations in Master
• Allow modifications if newer version exists - set to Enabled as A2.1 in a Draft is considered to be a newer version of this object. 

Can A2 object be modified in place?

Yes, you will need the following options set:

• Relaxed versioning mode set to Enabled - to allow updates in Master (in general)
• Allow update operations in Master archive set to Enabled - to allow edit operations in Master
• Allow modifications if newer version exists - set to Enabled as A3 is considered to be a newer version of this object. 
• Allow modifications of past versions - set to Enabled as you are not modifying a TIP version in Master alternative. 

Can I allow only:

• modifications in place to object A3 (only edits) (or any object in TIP of master archive)
  • yes, set Relaxed mode, and set "Allow update operations in Master archive" 
• Prevent any modifications to A1, A2 (or any object in any of the past Master versions)
  • yes, set Allow modifications of past versions to Disabled
• Allow free modifications in Drafts
  • Modifications in Drafts are always allowed.

Versioning Terms

1. Version – versions are used to manage change in every element stored in HyperDoc Database.
   1. Versioning includes objects with their properties, documents, links etc.
   2. A new version is created after every change (edit).
   3. Nothing is deleted in the system permanently. New version is created that does not contain the deleted object.
   4. By changing one object we formally obtain new version of the entire system, but without duplicating unnecessary data. Other unchanged objects are represented in their latest version in this way creating coherent view of the entire world – hence Multiple Worlds Framework will be used to describe entire set of features.
2. Alternative – alternatives are used for planning or drafting. This term is not directly available to the end user. In most cases it actually means "alternative version" when we have several versions in the system that are equally important. In user interface alternatives will be used to create personal drafts or saving future versions of the archive.
3. Label – labels are actually versions accessible by users. Label points to important version in the system. Between labels there can be many changes (low level versions) that are stored for audit trail and undo operations.
4. Current version – this is a marker that can be used to store specific version selected by administrator. This can be also seen as default version, that is the one that is visible in the system after start-up, and reflects current state of the world.
5. TIP – this is a marker used to accept new alternative versions into main branch. Versions are accepted, but they do not become current at the same time. It can be seen as placing versions in order. This term is also not visible to the end user and. Setting TIP in version control system will be performed behind the scenes by user functions like "publish changes".

(Detailed Version Management scenarios and Use Cases are described in separate documents.)