Versioning

Versioning is the mechanism that enables Verne to create and manage discrete snapshots of registry data.

This allows Verne to do things like provide the details of the registry data that is live on the register for a particular entity as it is now, or how it was last week, or last year, or the second Thursday last April, or at any other point in time in the past.

Similarly, versioning allows Verne to manage details relating to a service instance before it is activated. For example discarding the latest changes made to a saved service instance, reverting to the saved version.

Versioning also allows registry data that is already live on the register to be corrected so the changes can tracked and easily viewed when required.

Finally versioning is also a key concept when it comes to merging changes.

As the above examples highlight, versioning is a powerful feature within the Verne product suite and mission critical for a registry.

Versions and Service Transactions

The Life Cycle outlines in more detail how service transactions are used during the processing of a service instance. Suffice to say service transactions can be thought of as demarcating meaningful units of work relating to a service instance. Meaningful in this context relates to actions that can change the registry data.

A service transaction is therefore a discrete version or snapshot of the service instance data. A version or snapshot may relate to the current live registry data, a previous live version, a user-saved but not-activated version, some in-flight un-saved changes that can still be progressed, in-flight changes that have been discarded or cancelled, etc.

A service transaction can be thought of as a version or snapshot of the registry data. A version can relate to data currently or previously live on the register, or not yet applied. 

Version Dimensions

Given a service transaction represents a version of registry data as outlined in the section above, and as outlined in the business service concept one or more service transactions can make up a service instance and registry data relates to one or more service instances, there needs to be a way to manage the service transactions that collectively represent the versions of some registry data.

The relating of service transaction versions is done using a linked list strategy. That means a service transaction can point to a service transaction to its right, or left, or both or neither. A service transaction that is being pointed to may point back to the same service transaction, or it may point to another, or it may not point to any at all. What this means is that starting from any service transaction (version) you can follow the links to other related service transaction versions (if any) to build up a picture of what actions were performed and how the data was affected by each.

The diagram below is a simple illustration of a linked list between four service transaction versions where each subsequent version follows the previous without any breaks or detours.

Below is another left-to-right example but where the third version (V3) is not part of the main chain.

The section above talked about a service transaction pointing left or right and the illustrations reflect that, and although the second one does not follow a single straight line, they are still both one-dimensional in the left to right plane. One dimension may suffice for simple systems, but because registry data can be complex some additional "dimensions" or contexts are required when talking about the versioning linked lists.

The different version dimensions within Verne for supporting registry data are:

• versions – the main version dimension for activated registry data
• siblings – the version dimension for correcting activated registry data or distinct edits for non-activated service instances
• merges – the version dimension for service transaction merges

These dimensions can be thought of as different axes on a three dimensional graph – an X, Y & Z axis. It’s not important which is X, which is Y, etc., but what is important is that they have different functions in terms of versioning. In other words they manage a different component of service transaction versioning.

Service Transaction Version Properties

The three version dimensions listed above are managed by different properties on a service transaction. These properties are:

• versions – managed by the previousVersionId and nextVersionId properties
• siblings – managed by the previousSiblingId and nextSiblingId properties
• merges – managed by the previousMergeId, nextMergeId and merge properties

Returning briefly to the diagrams in the section above and assuming each of the version symbols represent a single service transaction for a different service instance all activated on the register (i.e. one register (V1) and three maintain (V2, V3 & V4) service instances). These service transactions would then have the following properties:

Diagram 1: four versions going from left to right with no breaks or detours:

• V1:
  • previousVersionId: N/A
  • nextVersionId: id of V2
• V2:
  • previousVersionId: id of V1
  • nextVersionId: id of V3
• V3:
  • previousVersionId: id of V2
  • nextVersionId: id of V4
• V4:
  • previousVersionId: id of V3
  • nextVersionId: N/A

Diagram 2: four versions where the third version is not part of the main chain (i.e. the service instance relating to V3 was based on V2 but never applied*):

• V1:
  • previousVersionId: N/A
  • nextVersionId: id of V2
• V2:
  • previousVersionId: id of V1
  • nextVersionId: id of V4
• V3:
  • previousVersionId: id of V2
  • nextVersionId: N/A
• V4:
  • previousVersionId: id of V2
  • nextVersionId: N/A

Version Property Assignment

It’s worth looking a little more in depth at when the service transaction version properties are set to help understand the versioning process.

Previous properties

The previous version properties are:

• previousVersionId
• previousSiblingId
• previousMergeId

These properties are set early, typically when a service transaction is created. This is because a service transaction tends to know what service transaction it is based on right from the start. This applies equally to the version, sibling or merge dimensions.

For example, if a maintain service is started to maintain the live version of the registry data then it knows the id of the service transaction it’s changing to use for its previousVersionId when it’s created. Similarly if something triggers a merge and a new service transaction is created as the result of a successful merge, then it knows the id of the service transaction merge target to use for its previousMergeId. Finally if you’re starting a new correction service to correct a version of the live registry data, or loading in a previously save-committed non-activated service transaction to make more changes, you know the id of the service transaction the new one is based on to use as its previousSiblingId value.

Previous version properties are set early on a service transaction, when it is created.

Note, the only service transactions that don’t have any previous version properties specified are the first service transaction for a new registration service instance (i.e. a Create mode service).

A service transaction can have multiple previous version properties set. For example a non-activated maintain service that is saved and exited, then loaded again will have a previousVersionId for the live service transaction it is maintaining, plus a previousSiblingId for the save-committed service transaction this one is based on for making further edits to.

Next properties

The next version properties are:

• nextVersionId
• nextSiblingId
• nextMergeId (and merge)

These properties are set late on the service transaction. That means these values will be absent on a service transaction when it is first created. They are set as the result of some action happening against some other service transaction, specifically one that has this one’s id as one of its previous version properties (above).

Next version properties are set late on the service transaction, usually triggered by an action against another service transaction.

If either of these next version properties are set, then the service transaction is considered superseded and is no longer a "current" version. It’s either an old version of the live registry data, or an old version of a service instance prior to it being activated.

What do we mean by next version properties are set late? Unlike the previous version properties (above) where they’re known when a service transaction is first created, it’s not until some other service transaction is activated or save-committed resulting in a direct replacement, or triggering a merge and an indirect merge replacement, that a next version property is assigned and the service transaction is superseded.

Like the previous version properties above, more than one of these next version properties can be set on the same service transaction. For example a previous live version of the registry data that is corrected will have both a nextVersionId from the maintain and a nextSiblingId from the correction. Unlike the previous version properties though, the nextSiblingId and nextMergeId are mutually exclusive – you will never have both of these properties set on that same service transaction.

Royal example

It may be useful to illustrate how and when a next version property is set using royalty as an example. If a king has a son, then that king would be the son’s predecessor if the son ever became king, which is known right from when the son is born. The son is in line to be king but has not yet replaced the king as his successor. It’s not usually until many years later that the son succeeds the king to become the new king. Furthermore, a king may have many sons and daughters who are in line to the throne, all of which have the current king as their predecessor, but only one will ever succeed him. To complete the analogy, if something happens to the king before one of his offspring was able to take the throne, then someone else would be appointed king or queen and a correction would be made to the line of succession, effectively updating the predecessor should they ever take the throne associated with each of the king’s offspring.

Multi-Dimensional Versioning

So far we’ve given examples of one-dimensional versioning, but stated there are three version dimensions at play within Verne. This section attempts to provide some further details and examples of multi-dimensional versioning without getting too bogged down in numerous examples, diagrams and explanations – instead we’ll just jump right into the complex examples.

Example: Activate Maintain with Merge

In this scenario there is an activated service instance live on the register. Two maintain service instances are then started from this live version, then one of them is applied. This means the version of the data that is live on the register has changed, and the maintain service that is still in-flight needs to have these changes reflected in its data (via a merge attempt). To further complicate things the maintain service that is still in-flight has been saved by the user, but then has been reloaded to make further changes that have not yet been saved by the user. Let’s assume all merge attempts are successful throughout.

It may take a while to absorb this scenario and the service instances and service transactions that relate to it. To help, it has been broken into two as follows:

• the state prior to activating the maintain service
• the state after the maintain service has been applied

Take your time looking at the details outlined for the first state below and/or the diagram that represents it until you are comfortable with the versions involved and their property values – it should eventually seem quite straight forward. Once done, consider the next step where the maintain service is applied.

Also note, when it says "X->Y" it means the value of property X is the id of service transaction Y.

State 1: Before the maintain service is applied

Prior to the maintain service being applied there are three service instances involved with service transactions relating to them as follows:

• S1 – An activated service instance, live on the register
  • 1 – The only service transaction for this instance, containing the registry data that is live on the register
• S2 – A maintain service based off S1
  • 2 – The first service transaction relating to S2 which has been saved & exited and is the current tip for S2 (previousVersionId->1)
  • 4 – A second service transaction, loaded in to make further changes (previousVersionId->1, previousSiblingId->2)
• S3 – The second maintain service based off S1
  • 3 – The only service transaction for this instance, which is about to be applied (previousVersionId->1)

State 2: After the maintain service is applied

The user then applies the second maintain service (S3/3), which leaves the same three service instances but with service transactions now relating to them as follows:

• S1 – An activated service instance, now a previous version on the register
  • 1 – The only service transaction for this instance (nextVersionId->3)
• S2 – A maintain service based off S1
  • 2 – Service transaction which was saved & exited, superseded by merge to 5 (previousVersionId->1, nextMergeId->5)
  • 4 – Service transaction, loaded in to make further changes, superseded by merge to 6 (previousVersionId->1, nextMergeId->6)
  • 5 – New service transaction created by the merge into 2 and the new current tip for S2 (previousVersionId->1, previousMergeId->2)
  • 6 – New service transaction created by the merge into 4 (previousVersionId->1, previousSiblingId->2, previousMergeId->4)
• S3 – The second maintain service based off S1
  • 3 – Service transaction now activated and contains the registry data that is live on the register (previousVersionId->1)