Recently I had an issue where a tester had deleted a number of artifacts from RQM by mistake and wanted to know how to restore them. My first port of call was the jazz.net forums, hoping that maybe RQM has an undelete button somewhere in the UI, however I quickly found that this is not the case:
Unfortunately, you cannot unarchive a test resource from the RQM UI
Thankfully the developer that posted the above reply was also kind enough to provide the necessary information to allow you to manually restore records through the REST API:
<protocol>://<server>:<port>/<context>/service/com.ibm.rqm.planning.common.service.rest.ITestCaseRestService/archiveTestCases?uuids_versionable=<test>&archive=false&processArea=<project>
This is certainly a step in the right direction, however it leads to the next obvious question of how do I find the UUID of each of my deleted records? My first line of investigation was the OSLC API, however this quickly hit a dead-end when I found that the OSLC query capability did not return deleted records.
Reportable REST API to the rescue
In the past I’ve had occasion to download the contents of individual test cases in XML format using the RQM URL Utility tool. This tool is invaluable when you are trying to write a custom configuration file for the RQM Word and Excel importer because it enables you to see the identifiers for custom sections. The examples you see in the URL utility documentation are all based on the RQM Reportable REST API, which provides a means of both listing and viewing individual records within RQM.
Looking through the documentation I was able to find the holy grail: the includeArchived query parameter. Performing a GET on the test case feed URI with this parameter set to true I was able to get an XML response that contained all of the test cases in my RQM project area, both active and deleted. The last remaining issue was to get the UUID of each of the test records, which is also catered for in the API via the metadata query parameter.
Putting this all together you end up with a query shape of:
<protocol>://<server>:<port>/<context>/service/com.ibm.rqm.integration.service.IIntegrationService/resources/<project-alias>/<resource-type>?includeArchived=true&metadata=UUID
Which leads to a result-set that contains entries similar to the following:
<entry xmlns="http://www.w3.org/2005/Atom"> <id>_KSwzJeLrEeGnZrjoVKQNBw</id> <title type="text">My Test Case</title> <summary type="text"/> <updated>2012-08-13T13:52:08.259Z</updated> ... </entry>
The results from the query then just need to be parsed, and a POST sent to the URL mentioned by the developer in the forum post. The one thing that I need to mention is that the processArea query parameter of the URL you have to POST to needs to be the UUID of the project containing the record you are restoring. I’ve found that the easiest way to obtain this is to simply open the “Manage This Project Area” page within RQM, then get the UUID from the itemId query parameter.
Overall this is quite a complicated process for an operation that should really only take a couple of clicks through the user interface. Hopefully this article will help someone avoid either having to manually re-type a bunch of information, or worse, restoring their database from a backup. With any luck IBM will plan this functionality in for a release sometime soon, however after being open for 15 months at the time of writing this, I feel it’s already long overdue.
Note: I should mention that this method of restoring deleted content is using an undocumented API, so the usual warnings apply about backing up your database beforehand, etc, etc.
