Object versioning

From (http://ez.no/doc/ez_publish/technical_manual/3_9/concepts_and_basics/content_management/object_versioning)

Object versioning

eZ publish comes with a built in versioning system which is implemented at the object level. This mechanism makes it possible to have several versions of the contents (attributes) of an object. It basically provides a generic, out-of-the-box version control framework that can be used with any kind of content. The different versions are encapsulated by the object itself. The following illustration shows a more detailed example of the object structure seen from the outside world.

Example of a content object that consists of two versions.

Every time an object is edited, a new version of the object's contents will be created. It is always the new version that will be edited, the old version(s) remains untouched. This is how eZ publish keeps track of changes made by various users. An accidental or unwanted change can thus be undone by simply reverting an object back to the previous version.

Version limitations

Since every edit procedure results in the creation of a new version (unless the new version is discarded), the database can be quickly filled up by different versions of the same content. In order to prevent this problem, the versioning system can be limited to a certain number of versions per object. It is possible to assign different version limitations for different object types (different classes). The default limitation is 10, which means that every object can have a maximum number of 10 versions of its content. If the maximum count is reached, the oldest version will be automatically deleted and thus a free slot will be available for the new one. This is the default behavior. An alternative setting can be used to disallow the creation of new versions until an existing version is manually deleted by a user.

Version structure

A version consist of the following elements:

• Version number
• Creation time
• Modification time
• Creator
• Status
• Translations

Version number

Every version has a unique version number. This number is used by the system to organize and keep track of the different versions of an object. The version number is automatically increased for each version that is created inside an object.

Creation time

The creation time contains a timestamp pinpointing the exact date and time when the version was initially created. This information is set by the system and will remain the same regardless of what happens to the version.

Modification time

The modification time contains a timestamp revealing the exact date and time when the version was last modified. This information is set by the system every time the version is stored and when the version is finally published. When a version is published, the modification time of the object itself will be updated (it will simply be set to the same value as modification time of the version that was published).

Creator

The version's creator contains a reference to the user that created the version. Although a content object can only belong to a single user (revealed by the "Owner" field), each version may belong different users. The creator reference is set by the system when the version is created. It can not be manipulated and will not change even if the user who created the version is removed from the system.

Status

The state of a version is determined by its status. There are five possibilities:

• Draft (0)
• Published (1)
• Pending (2)
• Archived (3)
• Rejected (4)

In eZ Publish versions 3.8 and later, there is an additional possibility: if a version of a content object is created but not modified (for example, if someone clicked an "Add comments" button but didn't actually post anything), the status of the version will be "Internal draft (5)". In the administration interface, status "5" drafts are called "untouched drafts". From 3.9, you can set the number of days, hours, minutes and seconds before an internal draft is considered old and removed by the "internal_drafts_cleanup.php" cronjob script. Another cronjob script called "old_drafts_cleanup.php" can be configured to remove status "0" drafts that have been in the system for a specified period of time.

A newly created version is a draft. This status will remain until that version becomespublished. Although an object can have many versions, there can only be one published version (the others are usually drafts and archived versions). The published version can be considered as the "current" version and it is the one that is accessed when the object is viewed. A published version can not become a draft. However, it will become archived as soon as another version is published. The following illustration shows how the versioning system actually works.

Overview of the object states.

The illustration above shows the most common states of a content object. When a new object is created (step 1), eZ publish will also create a new draft version. Because the object has not been published yet, its status is set to draft and the current version is unknown. Storing the draft (steps 2a and 2b) will not change the state of the object. The only thing that will happen is that the contents of the draft will be stored in version 1. If the draft (which is the only existing version) is discarded, the object is completely removed from the system (step 2c). When the draft is published (step 2), both the draft and the object's states will be set to published. In addition, the current version will be set to 1, which reveals the currently published version of the object. When published, the contents of the object can be viewed by others. A published object can be removed/deleted from the system (step 3a). When removed, the object's state will be set to "Archived" and thus it will be in the trash. The object can be recovered from the trash to its previous state. Among other things, this involves the status field being set to "Published" again. When a published object is edited (step 4), the current version (version 1 in this case) will remain untouched and a completely new version will be created. The contents of the new version (version 2 in this case) will be a copy of the contents of the current version. Again, storing the draft (steps 4b and 4c) will not change the state of the object. If the draft is discarded (step 4a), it will be completely removed from the system and thus the object will be in the exact same state as it was in before it was edited. If the newly created and edited draft is published, it will become the current version of the object and thus the previous version (version 1 in this case) will be set to "Archived". Step 5a illustrates what would happen if the object (now with two versions) would be removed.

The pending and the rejected states are used by the collaboration system. When a version is waiting to be approved by an editor, the status is set to pending. If the version is approved, it will be automatically published and thus the status will be set to published. On the other hand, if a pending version is rejected by the editor, the status will be set to rejected.

A version can only be edited if it is a draft and it can only be edited by the same user who initially created it. In addition, rejected versions can also be edited. When a rejected version is edited, it will become a draft. Published and archived versions can not be edited. However, it is possible to make copies of them. When a published or an archived version is copied, the status of the copy is set to draft and thus it becomes editable. When/if the new draft is published, the system automatically sets the status of the previously published version to archived and the new draft will become the published version.

Translations

The actual contents of a version is stored inside different translations. A translation is a representation of the information in a specific language. In other words, the translation layer allows a version of the object's actual contents to exist in different languages. A version always has at least one translation of the content (which represents the data in the default/standard language).