Propagating Versions
The repository engine can sometimes create a new versioned object automatically, in response to the versioning of another, related object. More specifically, you can create a new version of an origin object automatically when you purposely create a new version of a destination object. The automatic creation of an object version is called a propagated version. Version propagation is the process by which the repository determines which propagated versions are necessary and then performs those propagated version.
You can implement version propagation for collections that contain versioned objects and versioned relationships. The occurrence of version propagation depends on flags you set for the collection that contains the versioned items.
To implement version propagation, you must set the COLLECTION_NEWDESTVERSIONPROPAGATE flag on the collection. When this flag is set, invoking the CreateVersion method on a destination object propagates versioning to origin objects related through collections of this type.
After version propagation is in progress, it can continue to propagate origin-destination pairs. This occurs when a newly versioned origin object is simultaneously a destination object of another relationship. In this case, its origin object is also versioned. The versioning of paired objects continues up the version graph until a frozen origin object is encountered. This behavior occurs only while the origin object is unfrozen, and it occurs only for relationships that are created within the same transaction.
Version propagation creates a new, unfrozen version that has property values that are identical to the property values of the creation version. You can set additional CollectionDefFlags to further determine how object versions are propagated.
The following CollectionDefFlags can be set to determine how and whether version propagation occurs.
| Flag | Result |
|---|---|
| COLLECTION_NEWDESTVERSIONPROPAGATE | Version propagation occurs when the CreateVersion method is invoked on a destination object that is related to an unfrozen origin object. |
| COLLECTION_NEWDESTVERSIONADD | The origin object always links to the latest version of a destination object, eliminating manual versioning of an origin object in response to a newly versioned destination object. |
| COLLECTION_NEWORGVERSIONSDONOTPARTICIPATE | The origin collection is not copied from the creation origin object to the newly versioned origin object, even if other flags support version propagation. |
| COLLECTION_NEWDESTVERSIONSDONOTPARTICIPATE | The destination collection is not copied from the creation destination object to the newly versioned destination object, even if other flags support version propagation. |
Usage Scenarios
The version propagation functionality supports the following scenarios:
The first scenario, shown in the following figure, demonstrates the case when the origin object should be linked to the latest version of the destination object. In this case, the new version of Dest, Dest1, is added to the TargetVersions collection of the relationship. In this scenario, the COLLECTION_NEWDESTVERSIONADD flag is set, and the origin object is not frozen.
The second scenario, as shown in the following figure, demonstrates the case when the origin object needs to be versioned when the destination object is versioned. In this scenario, the COLLECTION_NEWDESTVERSIONPROPAGATE flag must be set, and the origin object must be frozen.
In this example, a new version of Dest0, Dest1 is created. A new version of Org0, Org1 is then created. Because, by default, the COLLECTION_NEWORGVERSIONSDONOTPARTICIPATE flag is not set, the new version of Org1 includes a relationship to Dest0. This relationship is deleted, and a new relationship with Dest1 is created. Note that this behavior happens only if the origin object is frozen. If it is not frozen, the origin object is not versioned.
This behavior can propagate. That is, any object for which Org is a destination will also be versioned. The behavior will propagate until the engine reaches an object that is not frozen, or is not the destination of any relationships or any relationships for which the propagation flag is not set.
The third scenario, as shown in the following figure, demonstrates the case when an origin object has multiple relationships with destination objects that must be versioned. In this scenario, the COLLECTION_NEWDESTVERSIONPROPAGATE flag is set.
In this example, Org0 is the origin of relationships with both DestA0 and DestB0. A new version of DestA0 is created, DestA1, and the version is propagated to Org0, as described in the previous example. Both the Org0 and Org1 have relationships to the existing DestB0. When a new version of DestB0, DestB1, is created, a new relationship to the already versioned Org1 is added, and the relationship between Org1 and DestB0 is deleted.
To summarize, propagating relationships during a transaction creates only a single version of an origin object.
See Also
CollectionDefFlags Enumeration
IRepositoryObjectVersion::CreateVersion