This topic provides the following versioning-related code examples:
For examples on using security templates with document versions, see Working with Security Policies.
For an overview of versioning, see Versioning Concepts.
The following Java and C# examples show how to add two versions to an existing document. (For examples on creating a new document, see Creating a Document Object.) You can create a version from a Document object (or any of its subclasses), or a VersionSeries object. In the examples, the first version is created from the Document
object, on which the checkout method is called and from which the reservation object is retrieved. The second version is created from the VersionSeries
object, which is retrieved from the Document
object. Properties of the VersionSeries
object are returned to print information about the versions.
Note that the first version is checked in as a minor version and has no content, whereas the second version is checked in as a major version and contains content. The autoClassify
parameter of the checkin method specifies whether auto-classification should be enabled for the document. For more information on auto-classification, see
Document Classification Concepts. For more information on adding content, see Document Content.
After a successful check-in, the reservation object becomes the new current version of the document.
If versioning security templates exist and are enabled,
the Content Engine will apply the appropriate template to the current document
version and to any previous document versions whose VersionStatus
state changes
as a result of the check-in. See Security Policies for details on versioning security templates. For information on version status changes, see Checkin in the Content Engine Administration Help.
In addition, the values of a number of other properties change after a successful
check-in. (The value of the document's Id
property remains
the same.) For example, the value of the IsReserved
property for the current
version, the previous version, and the VersionSeries
object is set to false.
The value of IsCurrentVersion
is set to true for the current version, and set
to false for the previous version. The value of ReservationType
is unset. To retrieve these properties, see Working with Versioning Properties.
Java Example
// Add the first of two new versions. // This version will have no content. Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{D6DCDE1F-EF67-4A2E-9CDB-391999BCE8E5}") ); // Check out the Document object and save it. doc.checkout(ReservationType.OBJECT_STORE_DEFAULT, null, null, null); doc.save(RefreshMode.REFRESH); // Get the reservation object from the Document object. Document reservation = (Document) doc.get_Reservation(); // Check in reservation object as minor version reservation.checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MINOR_VERSION); reservation.save(RefreshMode.REFRESH); //////////////////////////////////////////////////////////////////// // Add the second of two new versions. // This version will have content. VersionSeries verSeries = doc.get_VersionSeries(); // Print information about new version 1 of 2 Versionable version = verSeries.get_CurrentVersion(); System.out.println("Status of current version: " + version.get_VersionStatus().toString() + "\n Number of current version: " + version.get_MajorVersionNumber() +"."+ version.get_MinorVersionNumber() ); // Check out the VersionSeries object and save it. verSeries.checkout(ReservationType.OBJECT_STORE_DEFAULT, null, null, null); verSeries.save(RefreshMode.REFRESH); // Get the reservation object from the VersionSeries object. reservation = (Document) verSeries.get_Reservation(); // Add content to reservation object File file = new File("C:\\officePolicy.doc"); try { //Create a ContentTransfer object ContentTransfer ctObject = Factory.ContentTransfer.createInstance(); FileInputStream fileIS = new FileInputStream(file.getAbsolutePath()); ContentElementList contentList = Factory.ContentTransfer.createList(); ctObject.setCaptureSource(fileIS); // Add ContentTransfer object to list and set on reservation contentList.add(ctObject); reservation.set_ContentElements(contentList); } catch (Exception e) { System.out.println(e.getMessage() ); } // Check in reservation object as major version reservation.checkin(null, CheckinType.MAJOR_VERSION); reservation.save(RefreshMode.REFRESH); // Print information about new version 2 of 2 version = verSeries.get_CurrentVersion(); System.out.println("Status of current version: " + version.get_VersionStatus().toString() + "\n Number of current version: " + version.get_MajorVersionNumber() +"."+ version.get_MinorVersionNumber() );
C# Example
// Add the first of two new versions. // This version will have no content. IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{D6DCDE1F-EF67-4A2E-9CDB-391999BCE8E5}")); // Check out the Document object and save it. doc.Checkout(ReservationType.OBJECT_STORE_DEFAULT, null, null, null); doc.Save(RefreshMode.REFRESH); // Get the reservation object from the Document object. IDocument reservation = (IDocument)doc.Reservation; // Check in reservation object as minor version reservation.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MINOR_VERSION); reservation.Save(RefreshMode.NO_REFRESH); //////////////////////////////////////////////////////////////////// // Add the second of two new versions. // This version will have content. IVersionSeries verSeries = doc.VersionSeries; // Print information about new version 1 of 2 IVersionable version = verSeries.CurrentVersion; System.Console.WriteLine("Status of current version: " + version.VersionStatus.ToString() + "\n Number of current version: " + version.MajorVersionNumber +"."+ version.MinorVersionNumber ); // Check out the VersionSeries object and save it. verSeries.Checkout(ReservationType.OBJECT_STORE_DEFAULT, null, null, null); verSeries.Save(RefreshMode.REFRESH); // Get the reservation object from the VersionSeries object. reservation = (IDocument)verSeries.Reservation; // Add content to reservation document Stream fileStream = File.OpenRead(@"C:\\BootstrapConfigUtility.bat"); // Create ContentTransfer object IContentTransfer ctObject = Factory.ContentTransfer.CreateInstance(); IContentElementList contentList = Factory.ContentTransfer.CreateList(); ctObject.SetCaptureSource(fileStream); // Add ContentTransfer object to list and set on reservation contentList.Add(ctObject); reservation.ContentElements = contentList; // Check in reservation object as major version reservation.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION); reservation.Save(RefreshMode.REFRESH); // Print information about new version 2 of 2 version = verSeries.CurrentVersion; System.Console.WriteLine("Status of current version: " + version.VersionStatus.ToString() + "\n Number of current version: " + version.MajorVersionNumber +"."+ version.MinorVersionNumber );
The following Java and C# examples show how to cancel a checkout on a document.
Java Example
// Create Document instance and check it out Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{D6DCDE1F-EF67-4A2E-9CDB-391999BCE8E5}") ); doc.checkout(ReservationType.EXCLUSIVE, null, null, null); doc.save(RefreshMode.REFRESH); // Get the reservation object Document reservation = (Document) doc.get_Reservation(); // Cancel checkout on Document object and // save the reservation object doc.cancelCheckout(); reservation.save(RefreshMode.REFRESH);
C# Example
// Create IDocument instance and check it out IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{D6DCDE1F-EF67-4A2E-9CDB-391999BCE8E5}") ); doc.Checkout(ReservationType.EXCLUSIVE, null, null, null); doc.Save(RefreshMode.REFRESH); // Get the reservation object IDocument reservation = (IDocument)doc.Reservation; // Cancel checkout on IDocument object and // save the reservation object doc.CancelCheckout(); reservation.Save(RefreshMode.REFRESH);
The following Java and C# examples show how to retrieve a VersionSeries object from a document. The VersionSeries
object allows you to perform an action on all document versions collectively by issuing one call. In this example, the moveContent
method moves the content for all the document versions to a different storage location.
Java Example
// Get document and put VersionSeries object in property cache PropertyFilter pf = new PropertyFilter(); pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSION_SERIES, null)); Document doc = Factory.Document.fetchInstance(os, "{393472DA-7958-48CF-8C9F-7EA0E6B25678}",pf ); // Get VersionSeries object VersionSeries verSeries = doc.get_VersionSeries(); // Get the storage area where you want to move the document content FileStorageArea fsa = Factory.FileStorageArea.fetchInstance(os, new Id("{DE42374D-B04B-4F47-A62E-CAC9AC9A5719}"), null ); // Move content verSeries.moveContent(fsa); verSeries.save(RefreshMode.REFRESH);
C# Example
// Get document and put IVersionSeries object in property cache PropertyFilter pf = new PropertyFilter(); pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSION_SERIES, null)); IDocument doc = Factory.Document.FetchInstance(os, "{393472DA-7958-48CF-8C9F-7EA0E6B25678}", pf); // Get IVersionSeries object IVersionSeries verSeries = doc.VersionSeries; // Get the storage area where you want to move the document content IFileStorageArea fsa = Factory.FileStorageArea.FetchInstance(os, new Id("{DE42374D-B04B-4F47-A62E-CAC9AC9A5719}"), null); // Move content verSeries.MoveContent(fsa); verSeries.Save(RefreshMode.REFRESH);
The following Java and C# examples show how to delete a VersionSeries object. When the object is deleted, the document that contains the VersionSeries
object is also deleted.
Java Example
// Get document and put VersionSeries object in property cache PropertyFilter pf = new PropertyFilter(); pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSION_SERIES, null)); Document doc = Factory.Document.fetchInstance(os, "{3488C44F-D4BB-455F-AEED-553E9EADCC4E}", pf ); // Get VersionSeries object VersionSeries verSeries = doc.get_VersionSeries(); // Delete VersionSeries object verSeries.delete(); verSeries.save(RefreshMode.REFRESH);
C# Example
// Get document and put IVersionSeries object in property cache PropertyFilter pf = new PropertyFilter(); pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSION_SERIES, null)); IDocument doc = Factory.Document.FetchInstance(os, "{3488C44F-D4BB-455F-AEED-553E9EADCC4E}", pf); // Get VersionSeries object IVersionSeries verSeries = doc.VersionSeries; // Delete VersionSeries object verSeries.Delete(); verSeries.Save(RefreshMode.REFRESH);
The following Java and C# examples show how to retrieve properties from all of the versions of a Versionable object, in this case a document. The code gets the document's Versions
property, iterates the VersionSet
object, and prints numbering and status information about each version.
Java Example
// Get document and put Versionable object in property cache PropertyFilter pf = new PropertyFilter(); pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSIONS, null)); Document doc = Factory.Document.fetchInstance(os, "{9B289B8A-DDD9-42DC-9D51-6B485509B68A}",pf ); // Return all document versions VersionableSet versions = doc.get_Versions(); Versionable version; // Iterate the set and print information about each version Iterator iter = versions.iterator(); while (iter.hasNext() ) { version = (Versionable)iter.next(); System.out.println("Status of version: " + version.get_VersionStatus().toString() + "\nNumber of current version: " + version.get_MajorVersionNumber() +"."+ version.get_MinorVersionNumber() + "\nIs reserved: " + version.get_IsReserved() + "\nIs current version: " + version.get_IsCurrentVersion() + "\nIs frozen version: " + version.get_IsFrozenVersion() + "\n----------------------" ); }
C# Example
// Get document and put IVersionable object in property cache PropertyFilter pf = new PropertyFilter(); pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSIONS, null)); IDocument doc = Factory.Document.FetchInstance(os, "{9B289B8A-DDD9-42DC-9D51-6B485509B68A}", pf); // Return all document versions IVersionableSet versions = doc.Versions; IVersionable version; // Iterate the set and print information about each version System.Collections.IEnumerator iter = versions.GetEnumerator(); while (iter.MoveNext() ) { version = (IVersionable)iter.Current; System.Console.WriteLine("Status of version: " + version.VersionStatus.ToString() + "\nNumber of current version: " + version.MajorVersionNumber +"."+ version.MinorVersionNumber + "\nIs reserved: " + version.IsReserved + "\nIs current version: " + version.IsCurrentVersion + "\nIs frozen version: " + version.IsFrozenVersion + "\n----------------------" ); }
The following Java and C# examples show how to use the demoteVersion method to demote a major version to a minor version. To successfully demote a document, the document must be the latest major version (the value of its VersionStatus
property is RELEASED), must be the current version (IsCurrentVersion
is true), and must not currently have a reservation on it (IsReserved
is false).
After a successful call to demoteVersion
, the Content Engine will apply the
versioning security template (if it exists and is enabled) for the VersionStatus.IN_PROCESS
state
to the document being demoted. It will also apply the security template for the
VersionStatus.RELEASED
state (if one exists) to the previous major version. See Security Policies for more information on security templates. For more information on version status changes, see Checkin in the Content Engine Administration Help.
Java Example
Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}") ); doc.demoteVersion(); doc.save(RefreshMode.REFRESH);
C# Example
IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}")); doc.DemoteVersion(); doc.Save(RefreshMode.REFRESH);
The following Java and C# examples show how to use the promoteVersion method to promote a current minor version to a released major version.
To successfully promote a document, the document must be the latest minor version (the value of its VersionStatus
property is IN_PROCESS) and must be the current version (IsCurrentVersion
is true).
After a successful call to promoteVersion
, the Content Engine will apply the
versioning security template (if it exists and is enabled) for the VersionStatus.RELEASED
to the document being promoted. It will also apply the Security template for the VersionStatus.SUPERSEDED
state (if one exists) to the previous major version that is being superseded. See Security Policies for more information on security templates. For more information on version status changes, see Checkin in the Content Engine Administration Help.
Java Example
Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}") ); doc.promoteVersion(); doc.save(RefreshMode.REFRESH);
C# Example
IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}")); doc.PromoteVersion(); doc.Save(RefreshMode.REFRESH);
The following Java and C# examples show how to use the freeze method to prevent changes to the custom properties of a checked-in document version.
Java Example
Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}") ); doc.freeze(); doc.save(RefreshMode.REFRESH);
C# Example
IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}")); doc.Freeze(); doc.Save(RefreshMode.REFRESH);