What is the Document Versioning feature in IBM® Lotus® Quickr™ 8.2 /8.1 services for Lotus Domino®? How do you use it?

Contents:

Content is written by Andreas Goelzer; I simply copied/pasted what he provided.

• Overview
• Version Types
• Configuring Document Versioning in Lotus Quickr 8.0.0.2 for Domino
• Document Versioning in Lotus Quickr 8.1 for Domino
• Using the Quickr Connectors
• Using the WebUI
• Customizing Versioning for a specific PlaceType using the WebUI
• Customizing Versioning for System Forms (server-wide)

---

Overview

Document Versioning in Lotus Quickr provides the ability to create and manage one or more "snapshots" of an existing document. These read-only snapshots can be used to review previous editions of the document, or to replace the current version of a document with a snapshot taken earlier. When a new version is created, a read-only copy of the document (including attachments, subject, description, and other metadata) is created, which could be restored or reviewed at a later point.

The Document Versioning feature should not be confused with the "Revision" (8.0.0.2) or "Response with History" (8.1) action buttons. These are different features compared to Versioning:

• Versions allow you to create a snapshot of an existing document that cannot be modified and can be reverted
• "Revision" / "Response with History" creates a new copy of the document that can be modified

In the Web user interface (WebUI), previous versions are listed when you open a published document. You see previous versions in the "Versions" dialog box of the Quickr Connectors.

---

Version Types

Lotus Quickr supports three version types, as follows:

• "Disable document Versioning"
• All versioning functionality is hidden from the user interface (UI).
• In the Quickr Connectors, the "Versioning" metadata field shows "None".

• "Enable document Versioning"
• This type exposes the versioning functionality but lets each user manually decide when a version or snapshot is being created.
• To create a version, you must manually click the "Create Version" link in the Web UI or "New" on the Connectors "Version..." dialog box. A new version or snapshot can only be created when the current document is different from the last snapshot.
• In the Connectors, the "Versioning" metadata field shows "Explicit."

• "Always store updates as new version"
• This type automatically creates a new copy of the document as a read-only version every time the document is published.
• In the Connectors, the "Versioning" metadata field shows "Implicit."

---

Configuring Document Versioning in Lotus Quickr 8.0.0.2 for Domino

Document Versioning is implemented in Lotus Quickr 8.0.0.2 services for Domino as a Technical Preview. To get the full functionality of the Versioning feature, you must upgrade to Lotus Quickr 8.1/8.2.

In the 8.0.0.2 version, the system administrator can configure Document Versioning by changing a notes.ini variable on the Lotus Quickr server, as follows:

• h_VersionType= none
• h_VersionType= explicit
• h_VersionType= implicit

Once you set the notes.ini variable and restart the HTTP task of the Domino server, document versioning applies to all already existing documents and all newly created documents. If you change the notes.ini variable to a different value, then document versioning affects all newly created documents since the change, as well as documents that have not been modified since the notes.ini setting was first introduced. This behavior allows you to change the notes.ini setting without affecting existing documents and their version type. This setting applies to all document types / forms.

---

Document Versioning in Lotus Quickr 8.2/8.1 for Domino

In Lotus Quickr 8.2/8.1 services for Lotus Domino, the versioning feature is much more fine-grained than in 8.0.0.2. You can create custom forms and specify one of the three version types for each custom form in each place. To create or change a custom form, you need to be Manager or Owner of a place. You click the links "Customize this place" and "Forms" and then do appropriate modifications on these screens.

For the predefined Forms, the version type has been set by default and cannot be changed from the WebUI. You can hide some or all of the predefined forms by going to "Customize this Place", then "Forms" and "More Actions\Show/Hide Forms." You can then create customized forms with your desired Version Type instead. The default values for the predefined forms are these:

Predefined Forms	Version Type
Post	none
Imported Page	none
Event	none
Online Meeting	none
Task	none
Microsoft Word Page	explicit
Microsoft Excel Page	explicit
Microsoft PowerPoint Page	explicit
Multiple Imported Pages	none
Link Page	none
Upload	explicit
Page	none
Image	none

Once users create documents from either a predefined or customized form, the version type is stored in the newly created documents. If the version type is changed on the forms, it will not affect existing documents. For documents created pre-8.1, the versioning feature is disabled by default. This can be changed by setting the notes.ini variable "h_VersionType" to either "explicit" or "implicit". Once those documents have been modified and published (checked in), these documents will keep the setting.

---

Using the Quickr Connectors

For documents to show in the Quickr Connectors, the document has to contain at least one attachment because only documents with attachments are shown in the Connectors. To find out if a certain file is enabled for versioning, right-click the file and select Properties. Under the "Standard Metadata" section, find "Versioning." It will show either "None", "Explicit" or "Implicit" to show the version type for this particular file.

To create a new version, select a file, right-click and choose "Versions...". Click the New button, enter a comment, and click OK. This action creates a snapshot of the current state of the published document and links the comment to the currently created snapshot. If this document has been modified and published, you can replace the current published document with one of the previously created snapshots if you wish.

When adding new files, Lotus Quickr automatically determines which form to use. By default, when dragging a file to the Library folder, Quickr uses the "Upload" form that has explicit versioning enabled. Most other folders (for example, Home, Discussion, and so on) use the "Post" form by default, which has versioning disabled. This default behavior can be changed from the WebUI by selecting the folder and clicking the "More Actions" - "Folder Options" action button. Choose the appropriate form in the "Present a link to a default form for authors to use in this folder?" combo box and click "Next" twice.

With the Connectors there is another option to specify a different Form than the default Form assigned to the folder. To do so, right-click in an empty space in the folder, select "New" - "From Document Type..", select a Form that has Versioning enabled, and click "OK" then specify a file name (with extension if none is pre-defined). If documents are moved or copied from one folder to another one in the same place, the current version state (None, Explicit or Implicit) will be kept unchanged, while for other places the file will be moved/copied with the default form of the destination folder.

---

Using the WebUI

The behavior of the Web user interface (WebUI) is very similar to that of the Quickr Connectors. To create a new version (a snapshot of an existing published document), open a document that has "Explicit" versioning enabled and select the action button "More Actions" - "Create Version" to enter a comment for the snapshot being created. Lotus Quickr shows these snapshots (Versions) at the bottom of the published document. Clicking one of the links in the Version list opens the selected snapshot and metadata and files can be seen from this state. With "More Actions" - "Revert Version", a previous snapshot can replace the current published document.

For a document that has "Implicit" versioning enabled, a new version is created automatically for you once you Publish the document.

---

Customizing Versioning for a specific PlaceType using the WebUI

Lotus Quickr services for Domino comes with three templates by default:

• the Standard Place for Teams
• the Wiki
• the Blog

The "Standard Place for Teams" template come with default Versioning features enabled (see Predefined Forms table above) and cannot be modified directly.

Therefore, in the following example, we will create a new PlaceType (a template) from this Standard Place and perform several changes. Most of the changes are related to Versioning. We will also perform changes that are not related to this topic but that you might find useful doing at the same time. We will do these modifications:

• Limit all forms to just the "Post", "Calendar" and "Upload" forms
• Only use the above forms in the appropriate views "Discussion", "Calendar" and "Library"
• Hide all other folders
• Modify the "Upload" form to use implicit versioning
• Replace the "Standard Place for Teams" with our new template

For simplicity of these instructions, we use "bold italic" characters where different names can be used as desired or needed.

1. Create a Place

1. Enter "http://servername.ibm.com/lotusquickr" in browser's window
2. Click "Create a Place" and click "Standard place for Teams"
3. Fill out the fields:
   Name your place: Standard Place
   Describe your place: Use for most of IBM's corporate collaboration
   User name: username
   Password: password
4. Click "Create"
5. Click "Go to Standard Place" and log in

2. Hide forms, folders and other items

For our example, we want to reduce the functionality and allow only three forms: the Post, the Calendar and the Upload form.

1. Click "Customize this Place"
2. Click "Forms"
3. Click "More Actions" - "Show/Hide Forms"
4. Clear (uncheck) all boxes except "Post" and "Event". Also uncheck the "Upload" form; we will create a customized version later
5. Click "Next"
6. Click "Customize this Place"
7. Click "Basics"
8. In the "Show/Hide" section, clear (uncheck) the "Tasks" checkbox
9. Click "Done"

3. Create a customized "Upload" form with versioning enabled to implicit

1. Click "Forms" in the "Customize" page
2. Click "New Form"
3. Leave "Simple Form" selected and click "Next"
4. Enter "Upload" in the "What is the title of the form?" field
5. Click "Add", select "Attachments" and click "Next" twice
6. Click "Add", select "Rich Text", click "Next" and enter "Summary" in the "What is the title of the field?" text box and click "Next"
7. Select the "Title" in the list box and click "Modify..."
8. Change the "What is the title of the field?" from "Title" to "Name" and click "Next"
9. Click "Reorder", select the "Show Attachments" item from the list box, and click the up arrow to bring it to the top and click "Next"
10. From the "Do you want to create version documents with this form?" combo box, select "Always store updates as new version"
11. Click "Done"

4. Replace the default form for the Library folder to our customized "Upload" form

1. Click the "Library" link
2. Click "More Actions" - "Folder Options"
3. In the combo box "Present a link to a default form....", select the second "Upload" item. The first one is the default "Upload" form, while the second one is our customized one
4. Click "Next" twice

5. Replace the "Standard Place for Teams" with our "Standard Place"

1. Click "Customize this Place" and "PlaceType Options"
2. Select "Yes" for "Allow PlaceTypes to be created from this place"
3. Fill in the "Description to be used in the PlaceType gallery" field some descriptive information
4. Click "Next"
5. Click "Places" on the top of the browser window
6. Click "Log in" in the top right corner if needed and log in as the server administrator
7. Click "Work with Templates" link at the bottom left of the browser window
8. Click "Create PlaceType"
9. Enter "Standard Place" in the "Please enter a name for this PlaceType" field
10. Select "standardplace" from the combo box
11. Click "Next"
12. Click "Show/Hide" and uncheck the checkbox before "Standard Place for Teams" and click "Next"
13. Click "Reorder", select "Standard Place" and click the up arrow a few times to get it to the top and click "Next"

From now on, all new places created from the "Standard Place" template will have "Implicit" versioning enabled for the "Upload" form that can be created in the "Library" folder. The above example is a simple modification to adjust a Place template. It is verify flexible and several customized forms or folders can be created to change a default template behavior.

---

Customizing Versioning for System Forms (server-wide)

Overview

In Lotus Quickr 8.2/8.1 services for Domino, the default system forms (Post, Upload, MS Office forms and others) cannot be modified with the WebUI to modify the Versioning behavior or to perform other changes to these predefined forms. The alternative is to create custom forms instead and "hide" the system forms; this change allows different versioning behavior for different PlaceTypes but would not affect all places based on those system forms. There are plans to allow some modifications to system forms in the future; however, a timeline or the extent of those modifications has not yet been defined. Until these changes make it into the product, you can perform a programmatic change to allow different version type behavior for the system forms. Note: This method is only supported until these changes can be done with the Web user interface or until support of this agent is discontinued.

Installation of the tool
To install the Notes-based agent (tool) that allows you to modify the system forms, you need the following:

• Notes 8.x client (If using a Notes 7.x client, substitute "Database" for "Application" in the description below)
• Administrator access to the Domino Directory of the Lotus Quickr server
• Database Creation rights on the Lotus Quickr server

Perform the following steps to install:

1. Copy the attached file h_VersionType.nsf to your Notes client data directory:
   (See attached file: h_VersionType.nsf)
2. From the Notes client, press "CTRL+O" to launch the Open dialog. Open the file "h_VersionType.nsf" you just copied.
3. In this database, select from the menu File - Application - New Copy...
4. In the New dialog box, switch to the Lotus Quickr server, specify a file name, and click OK.
5. Open the newly created copy on the server, and select File - Application - Access Control
6. Make appropriate changes to the ACL and click OK.
7. Add a group named "LotusQuickplaceAdministratorsSUGroup" to your Lotus Quickr server's Domino Directory. Add your name as a member (and other administrators who need to adjust those settings). This group allows you to perform changes to the PageLibrary.ntf and MeetingRoom.ntf files on the Lotus Quickr server.

Using the tool
To use the tool, take these steps:

1. Using a Notes client, open the database you created on the server earlier (by default, it is called "Quickr VersionType change").
2. Click the action button "Adjust Version Type of System Forms" in the opened database, which opens a form.
   
   The tool runs a script and retrieves all the Version Type information of the default system forms of the MeetingRoom.ntf on the Lotus Quickr server.
   
3. Make appropriate modifications to the fields and press "Update System Templates."
4. Review the log. The last line should show "Completed successfully" if everything worked as expected.

When to run the tool
You should run this tool every time you want to modify the default version type of the system forms. Keep in mind that existing documents created in 8.1 or later will have the VersionType already set for them; therefore, the changes with the tool would not affect the existing documents.

Once the tool has run, perform a "load qptool upgrade -a" command on the Lotus Quickr server's console to refresh the existing places with the new versioning settings to take effect for newly created documents.

When you upgrade the server to a new release or hotfix, all the settings will be overwritten. For this reason, you should use the following order when upgrading the Lotus Quickr server:

1. Upgrade the Lotus Quickr binaries
2. Run this tool to change the VersionType in the MeetingRoom.ntf and PageLibrary.ntf files
3. Run "load qptool upgrade -server" (from the normal upgrade instructions)
4. Run "load qptool upgrade -a" (from the normal upgrade instructions)