Though this implies multi-user environment client/server setup, this article could still be of use to a single user. If you are a lone developer working in a stand-alone environment (sometimes referred to as a single-user environment), you may want to just skip straight to the section Exporting and importing content, at the end of this article. Sorry, but version management in a stand-alone environment is almost nonexistent, so you're largely on your own.
In a client/server environment, all content objects are stored on a central server. Developers create and edit content on their own workstation (typically, a PC), and then send this content to a database on the central server for storage when they have finished with it. This is referred to as checking in a content object. If they subsequently want to change a content object that is on the server, they need to check out the content object, change it, and then check it back in.
Checking in a content object
When you create a content object in a client/server environment, the content object is stored in your local repository (that is, on the client side of the client/server set-up). It is important to understand that your local repository is located on your local workstation. This means that if you have a content object in your local repository, and then move to another workstation, you will not see your local version of this content object on the new workstation. This is because they are located on the workstation on which you created them or checked them out. You should, therefore, always use the same workstation, or check in all of your content objects before moving to a new workstation.
In UPK 3.5.1 client/server edition, it is possible to choose a specific location for your local repository.
Documents that are checked out to your local repository are identified by a green check-mark () to the left of the object details in the Library. You will need to check these objects in if you want them to be stored in the central library so they will be accessible to other developers. Generally, you should do this whenever you have finished working on a content object. However, there are good reasons for checking in objects more frequently. Your local repository is (typically) in the C: drive of your computer, whereas the central library is on a central server. Unless you are very fastidious about backing up your PC, the chances are that the server is backed up more often than your PC, and is usually backed up automatically. Placing your files in the central library will, therefore, provide greater security in terms of having a backup that you can revert to in the event of a disaster.
In addition to this, whenever you check in a content object, a back-up of the previous version is taken. Should you need to back out your changes, you can simply revert to a back-up version of the content object. Related to this, content objects are never really deleted from the server library. Actually, they can be deleted, but only by an Administrator, and typically as part of a cleanup. However, if you delete an object (that has never been checked in to the central server) from your local repository, it is gone. Forever!
Finally, it is not unheard of that for a local repository to simply disappear when UPK crashes (which thankfully doesn't happen that often, but it has been known to happen). If this does happen to you, then you may again lose all of the content that you currently have checked out even though the Lost documents view, introduced in UPK 3.5, may save you.
For all of these reasons, and more, it is recommended that you check in all of the content that is stored in your local repository to the server at least at the end of each work day. Fortunately, UPK provides a quick way of doing this. If you click the Check In All button (), then all of the content objects that you currently have checked out will be checked in again. The downside of this is that if you do check in all of the documents that you are currently working on at the end of the day, you need to remember which objects these are so that you can check them out again the next day.
Before checking the documents in, you can use the All Checked Out view to identify all of the documents that you currently have checked out. You can then print this list, and will know which files you need to check out again the next day.
There is one further thing to bear in mind when deciding how often you are going to check in your content objects. As mentioned above, UPK retains every version of a content that has been checked in. These are accessible via the Document History, as we will see later. This means that if you check in a content object ten times, then UPK will retain ten versions of it. This can also make it difficult to identify the "released" versions of the content object in the Document History, should you subsequently need to roll back to the last-released version. The Administrator can clean up the database periodically, but the only way of differentiating between versioned drafts and versioned released content objects is by using the check-in comments. These are explained in the section Step 2: Confirming the scope of the check-in, ahead.
The down-side to checking in content objects that you may not have finished working on is that these objects could be mis-perceived as being final, and actually used or published. In some cases, you may have checked some of them out not because you want to change them, but specifically to stop anyone else from changing them.
UPK does not provide you with a simple, automatic solution to these shortcomings, but there is a manual workaround that you can use. This is to use the Workflow properties of the objects.
UPK does not have a "real" workflow, it does not have "routing" of content objects based on their status, or automatic email notification of content objects that are due for review, or any of the things that you'd expect from workflow functionality. Of course users can use a Custom View to display content objects according to their Workflow properties, but this is still not really "workflow".
If you display the Properties for a content object, by clicking on the Properties button (), the last category of properties (at the end of the Properties list) is the Workflow category. Within this, there are two properties:
- Assigned To: This property allows you to select (from a drop-down list) the user ID of any developer who is authorized to access the content object. If you select your own user ID in this field, then this is an indication to the other developers that they should not work on this content object themselves.
- State: This property can be used to specify the current status of a content object. The default values are (blank), Not Started, Draft, In Review, and Final. If you select a status of Draft, then this is an indication that you have not finished with the object.
An example of the Properties pane, showing the Workflow category, is in the following screenshot:
Of course, these Properties do not provide "hard checks". You still rely on people seeing, and then paying attention to, these Properties but it is a start. Some strong guidance from your Project Manager or Team Leader would help, here.
Administrators can add, remove, or rename statuses. It is recommended that a suitable set of statuses are established and defined prior to any development work starting, and that these statuses and their meaning are communicated to all developers.
Step 1: Selecting the content objects
To select content objects for checking in, carry out the steps described below:
- In the Library, select the content objects that you want to check in. Normally, you will want to check in specific content objects, so you would only select these. As always, you click on a content object to select it. You can Ctrl-click to select multiple objects, or Shift-click to select a series of objects. You can also select a folder in the Library to check in all of the content objects in that folder. Do not worry if some of the objects that are included in your selection are not checked out; UPK will simply ignore these objects during check-in (it will not "error-out").
You can also check in content objects by selecting them in an Outline Element.
- Once you have selected all of the content objects that you want to check in, click the Check In button ().
Step 2: Confirming the scope of the check-in
When you check in one or more specific content objects and have not selected a folder in the Library to check in, UPK will automatically check for any content objects that are related to the object that you are checking in. You will be prompted to check these in, as well. An example of this prompt is shown in the following screenshot:
What are related documents? In general, they are Web Pages and Packages used by the content object that you are checking in. For example:
- If you have created, or changed, an Outline Element (Module or Section) then UPK will automatically select all of the content objects (Modules, Lessons, and Topics) included in this Outline Element, along with any Web Pages used by any of these content objects will be selected as well.
- If you are checking in a Topic for which you have also created a Web Page that is linked to the Concepts pane, then UPK will automatically select this Web Page as a related document during check-in.
- If you have created a Glossary and are checking this in, the related documents will be all of the Web Pages for the content definitions used by the Glossary.
An example of the Related Documents dialog box is shown in the following screenshot:
This list of related documents can be confusing, as it does not match the list that you see in the Related Documents pane for the content object that you are checking in. The list will include Web Pages that have been explicitly linked to from the content object that you are checking, but will not include Glossaries, Templates, Packages, or icons, all of which are listed in the Related Documents pane.
This limitation is important to understand. If you checked out, and updated, a Glossary and as a result UPK checked out several content objects during the glossary link regeneration, UPK will not identify all of the Glossary elements (Web Pages) as "related documents". You will need to locate these and check them in separately using custom views.
Adding to the confusion, the list of related documents will include all of the explicitly-linked content objects, and not only those objects that are currently checked out to you. Do not worry about this – UPK will only physically check in the content objects that you do have checked out (these are the ones that have your User ID in the Checked Out To column of the Related Documents dialog box). In the example above, we are checking in an Outline Element that contains one Topic, which in turn contains a Web Page. The Topic is checked out, but the Web Page is not.
Step 3: Specifying a reason for the change
When you check in one or more content objects, you will be prompted to enter a short description of the change, as shown in the following screenshot:
The title of the content object that you are checking in is shown above the comment text box. If you are checking in multiple content objects, then this will initially specify the first object and (assuming that you deselect the Apply same comments to all documents option) will specify the next object when you click OK. It then moves on to the next object. In this way, you can provide separate comments for each content object, even though you are checking them all in at the same time.
Although it is entirely optional, it is a very good practice to always enter a comment. This comment will appear in the object History, and therefore serves as a useful audit log.
Specify a reason for the change by carrying out the steps described below:
- Enter a suitable comment in the space provided. Note that you do not need to specify the date and time of the change, or your user ID. These are captured automatically by UPK.
- If you are checking in multiple objects, then UPK will initially suggest applying the same comments to all of the objects. You will see that the Apply same comments to all documents checkbox toward the bottom of the dialog box is selected. If you do not want to use the same comment for all objects that you are checking in, then deselect this checkbox. Now, when you click on OK, the Check In Comment dialog box for the next content object in the check-in selection will be displayed. You can repeat the above processing from Step 3.
- Once you have entered your description of the change (or reason for the change), click on OK.
- Once you have specified a comment, and clicked on OK for the last time, then the content objects are checked in, and the Library screen is redisplayed.
Checking out a content object
If you want to change a content object that is currently checked in to the server library, you need to check it out from the Library.
As from UPK 3.5.1, if you try to open a content object for editing that you currently do not have checked it, UPK will ask you if you want to check it out first. Prior to version 3.5.1, UPK did not warn you (other than a small text of "Read only" in the title bar – which was easily overlooked), and would simply prompt you to save the read-only content object as a new content object when you tried to save it. This is a significant improvement.
To check out a content object from the server, carry out the following steps:
- In the Library, click on the content object that you want to check out.
- Click on the Check Out button () on the Versioning toolbar. If there are other content objects related to the content object that you are checking out, then UPK will ask you if you want to check out these objects as well, as shown in the following screenshot:
- Select whether you want to check out only the selected document, or the selected document and all related documents. Then click on OK. Refer to Checking in a content object, for additional guidance, if necessary.
The document is checked out into your local repository. A green check-mark () is shown to the left of the content object's name to indicate that the content object has been checked out. All other developers will see a lock symbol (), indicating (to them) that another user has the content object checked out. If you have a content object checked out, then other developers can still display the currently checked in version of the content object. However, they will not be able to make any changes to it as this would necessitate them checking it out themselves, which they will not be able to do. They will also, obviously, not see any changes that you have made to the content object since you checked it out (as these changes exist only in your local repository).
You can now edit this content object as required. Once you have finished editing the content object, you should check it back into the server.
Cancelling the check-out of a content object
If, after checking out a content object, you realize that you do not want to change it after all, you can cancel the check-out. If you do this, then any changes that you have made to the content object will be discarded.
To cancel the check-out of a content object, carry out the steps described below:
- In the Library, select the object for which you want to cancel the check-out.
- Click on the Cancel Check Out button (). If you have changed the content object in your local repository, then the following warning message is displayed:
- Click on Yes to confirm the cancellation of the check-out.
The document is removed from your local repository and will be available to other users for check-out. This will not create any entries in the version history.
If you did not actually make any changes to the content object, then it is simply "unlocked"—nothing is moved to the server, and no new version is created.
Working with document versions
Every time that you check in a content object (and not every time that you save it in your local storage), UPK takes an archive copy of the previous version. You can list all of the previous versions of any content object by clicking on the object to select it, and then selecting menu option Document|History. An example of the resulting History dialog box is displayed in the following screenshot:
The History dialog box lists every version of the content object since it was first created, along with the User ID of the person who created the version (that is, the person who checked in the content object) and the date and time at which this was done. The Comments field shows the comments that were entered when the document was checked in.
Displaying an earlier version
You can display any version of a content object from the History. To do this, follow the steps shown below:
- Select the content object in the Library.
- Select menu option Document|History.
- In the History dialog box, select on the version that you want to.
- Click on View.
The content object is opened in the relevant editor: Outline Editor, Topic Editor, Web Page Editor, and so on. The title bar shows the version number that you are displaying, as shown in the screenshot below:
In this example, we are displaying version 3 of the content object.
Reverting to an earlier version
If you have checked in a content object, and then realize that you do not want to keep your latest changes (or you are an Editor and want to back out someone else's work because they made a rubbish job of it) then you can revert to an(y) earlier version of the content object. To do this, follow the steps shown below:
- Select the content object in the Library. Note that the document must be checked in; you cannot roll back a document that is currently checked out (by you or any other user).
- Select menu option Document|History.
- In the History dialog box, click on the version to which you want to revert back to. This is shown in the following screenshot:
- Click on Rollback.
The version that you selected becomes the latest version again, with the Comments set to Rolled back to version "X", as shown in the screenshot below:
What has happened is that a new version has been created, by taking a full copy of the selected version. The version that you wanted to back out has not been deleted, it is still available, but it has just been superseded by the new (copied) version. This means that if you subsequently realize that you shouldn't have reverted to the earlier version, and really do want to keep your latest changes, then you can simply select the last version before the rolled back version (in the example above, this would be version 4), and roll back to that. In the example above, this would be version 4.
Also note that the content object is not checked out when you revert to an earlier version.