By Lutz DornbuschIt can happen to anyone. But it's not necessarily your worst nightmare...
... if a Polarion Work Item or LiveDoc document gets deleted by mistake. Chances are it can be recovered with relative ease, thanks to the fact that Polarion integrates Subversion (SVN). Polarion automatically tracks every change to every development artifact in a SVN repository revision, and SVN can revert any change, including deletes. In this series of 2 articles, I'll show you how to recover both deleted Work Items and deleted LiveDocs. In this first post we will look at:
Basic preparations for recovery
The recovery process
How to restore a deleted Work Item
The second article (coming soon) will discuss specifics of recovering a deleted LiveDoc document.
Regardless of whether you need to recover a Work Item or a LiveDoc, there are several things you will need in advance:
Object ID: the ID of the object to restore (Work Item ID or LiveDoc space name and document name). Without the ID of your object, it will be difficult to recover deleted information
Project ID: the ID of project the deleted object belonged to. It must be the ID, not the name, though they may sometimes be the same. The project ID is essential for locating the project folder in the Subversion repository.
Subversion client: you'll need a SVN client application to access the Subversion history and to commit changes. (My articles assume you are familiar with Subversion concepts, terms, and procedures and the TortoiseSVN client.)
Permissions: You must have repository Write permissions for the deleted object's last repository location. If you cannot write to the specific folder, you cannot make the changes needed to recover objects.
Recovery Process Overview
The steps to restore an object in Polarion are always the same. However their execution may differ in details:
Check to be sure the object was really deleted and not merely moved. Work Items can be moved to a different LiveDoc. LiveDocs can be moved to a different space.
Locate the SVN folder that last stored the object and checkout this folder
Locate the revision in the folder's history in which the Delete operation was done
Revert changes from this specific revision
That's it... you're done. (And you may have just become somebody's hero!)
Most important is step 1 to make sure you do not corrupt the index by inserting a duplicate Work Item ID. While that is not a fatal error, some undesirable quirks sneak into Polarion. For example, multiple instances of the restored item can show up in a LiveDoc. So be careful and avoid this at all costs!
Figure 1. Corrupted LIveDoc with multiple instances of EL-27
We'll walk through these 5 steps in the context of 2 examples. In the first example (this article), we'll restore a deleted Work Item. It's a bit easier, and will server as good preparation for the more difficult case of restoring a deleted LiveDoc - which will be the subject of the second and final article of the series. So hang on to your hat and let's jump right in.
Recovering a Polarion Work Item
1. CHECK IF OBJECT WAS REALLY DELETED AND NOT MOVED
Locate the SVN folder that contains the deleted Work Item. If you have the ID of your project, usually you can easily find out the location inside the repository, by browsing the repository analog to your Polarion project groups:
Figure 2. How SVN folders map to Polarion projects
Important here is that the project folder in the repository is your Polarion project ID, not the Polarion project name (these are often the same, but they don't have to be!)
Examine the history of this folder with TortoiseSVN’s show log command on the Repository Browser. TortoiseSVN has a neat function to filter the history by paths. The last revision should be a Delete operation of the corresponding Work Item, as shown below:
Figure 3. Finding the deleted Work Item in SVN
Note that Tortoise supports you on several points:
It allows you to filter revisions so you see only revisions in which your Work Item was changed.
It shows you the operations (add, delete, modify) that occurred in each revision.
It shows you the detailed action: which operation was executed on which path.
TortoiseSVN will display only 100 revisions, so if you cannot find your revision use the “Show All” button
If the last operation was not a delete, then your Work Item is still “alive” somewhere. Use the path information to find out where it is. It is probably sitting in a LiveDoc's Recycle Bin (see the Help to understand how this works). You should also be able to find the item using Polarion's search feature.
2. LOCATE SVN FOLDER THAT LAST STORED THE OBJECT AND CHECKOUT THIS FOLDER
Often you know where your Work Item resided before it was deleted. If you do not know the last location of your item, examine the path of the last commit (from Step 1).
There are two possible locations:
Inside a document:All Work Items are stored in folder:[path_to]/[project_id]/modules/[documentspace]/[documentname]/workitems/For example the full URL could be:
http://almserver/repo/Demo Projects/elibrary/modules/Testing/User Acceptance Test Specification/workitems/EL-31
Outside of any Document:
All Work Items not belonging to any Document are stored in:
For example, the full URL could be:
Keep in mind, that these Work Items are sorted in packages of hundreds.
Check out this folder from Subversion. Here is an example screenshot:
Figure 4. Run SVN checkout on folder that stored the deleted item
You can optimize the checkout time with a Subversion "sparse" checkout by selecting Only this item.
3. LOCATE THE REVISION IN THE FOLDER'S HISTORY IN WHICH THE DELETE OPERATION WAS DONE
In step 1 we already located the revision, but this time we need to do it in our working copy (checked out in step 2). Right-click on your just checked out folder and select TortoiseSVN >Show log. Locate the revision of the delete operation as in step 1. Use filtering if you cannot find it.
4. REVERT CHANGES FROM THE SPECIFIC DELETE REVISION
Figure 5. Reverting the "bad" delete
To revert the changes from this revision, highlight the revision in the client. If you have more than 1 action in this revision (as in the figure below), you can select the corresponding delete action, right-click, and select Revert changes from revision. When you respond to the dialog to confirm your decision, the change is made into your working copy. So the folder of your deleted Work Item should now be present in your working copy.
5. COMMIT CHANGES
You can now commit your changed working copy, after which the formerly deleted Work Item should be immediately available again in Polarion. If your Work Item exists in a LiveDoc, it is now visible in the Recycle Bin of the doc's sidebar. Use the Recycle Bin actions to re-insert it into the Document.
That's it. Hopefully somebody now owes you a coffee. Stay tuned to the RSS for Part 2: Recovering a Deleted LiveDoc.
About the Author
Lutz Dornbusch is a senior consultant with Polarion's Professional Services team. He is based in Düsseldorf, Germany.