During discussions with customers, business partners and IBM client technical representatives about OSLC integrations for RQM, I’ve realized related information is rather dispatched across disparate sources. I got this impression confirmed when parsing the Jazz.net RQM-related forum questions.
The customers’ core question that typically arise aims at unblocking an on-going integration development effort and often resumes to :
“How could I access/create this test artefact in RQM through OSLC or REST APIs?“.
There are de facto resources (Wikis, etc.) that you would want to consult for an exhaustive listing of parameters and options (see “References” section below). What we want to provide you here is consolidated information I collected from both Jumpstart work (during the development of a tool importing test results into RQM) and readings of related sources of information in the community (posts, wikis, e-mails, etc.).
I decided to put an emphasis for providing sample URLs that you could quickly adapt to your CLM environment. Caution here, your attempts shall be done in a test environment first ! (remember that I’m not liable for any harm you could do to your computer…)
What this post provides you with :
- OSLC-oriented descending approach to discover test resources on your CLM system
- “Cheat sheet” for accessing test resources through OSLC
- “Cheat sheet” for accessing test resources through REST APIs
- “Cheat sheet” for creating test resources through REST APIs
As you’ll be making HTTP calls, I’d advise you use Firefox with an add-on like Poster, RESTclient, or use standalone REST utilities like curl or HTTP4e. Unless specified differently, all example HTTP requests mentioned below are assumed to contain the following HTTP headers:
Be aware that :
- I’ve cut parts of some server-returned RDF/XML contents reported below. Goal was to ease the reading of this post and focus on the main information. Each time, I’ve symbolized cuts by “…”.
- Most of the URLs I provide included some specifics (i.e. to my own CLM instance):
- it either contains reference to the “JKE Banking (Quality Management)” project area, either include some specific context string in the URL (e.g. the “_7C2_YDQIEeKh2o37xigryw” context)
- the “JKE Banking (Quality Management)” appears as “JKE+Banking+%28Quality+Management%29” (URL encoded string format). If just for playing with your favorite REST tool, you could keep the non URL-encoded format.
As a consequence, you’ll need to adapt these URLs to your own CLM specifics (including the server public URI). Which should be straightforward.
1. OSLC-oriented descending approach to discover test resources on your CLM system.
Now making our first step of our descent to the RQM testing resources.
Step 1: Retrieve the QM Root Services URL
What you locate here is the URL for discovering the QM’s various services and specific capabilities. For the following step, please note that – in contrary to the Root Services document – the Service Provider catalog document is a protected document, so the client needs to authenticate with the JTS to be able to access it (Jazz form-based authentication). As a consequence, to proceed with the following HTTP requests from your browser, you’d need to authenticate on the RQM server first.
Step 2: Retrieve the QM Service Provider catalog (basically all QM project areas)
A Service Provider publishes all the services provided by a context of an OSLC application. In RQM, it is basically a Project Area.
Step 3: Retrieve the services of the “JKE Banking (Quality Management)” project area
In the RDF content above, we distinguish shapes (“Creation Factory”, “Query capability”) and dialog (ie. representation/rendering of the properties dialogs that the QM provider has full control on).
Step 4: Access the list of test artefacts in the selected project area URLs for accessing list of Test Plans, Test Cases, Test Results, Test Scripts, TERS/TCERs appear highlighted in the above XML.
They’re consolidated with others in the following table.
2. “Cheat sheet” for accessing test resources through OSLC
Cheat Sheet #1
(GET)ting RQM Test artefacts through OSLC
3. “Cheat sheet” for accessing test resources through REST APIs.
Cheat Sheet #2
(GET)ting RQM Test artefacts through REST APIs
Note about the slug id (and how to handle them once they’re returned to you in the response header “Content-Location” following a POST operation):
- basically, the URL will be of the following format (here, for a test script): https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE+Banking+%28Quality+Management%29/testscript/slug__<some_ID>
- For a more complete procedure, I advise you to check Don’s answer in this Jazz.net forum post.
Cheat Sheet #3
(PUT/POST)ting test artifacts through REST APIs
|Create a Test Case (v4.0.6+)||https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE+Banking+%28Quality+Management%29/testcase|
|Create a Test Case (ext ID “myExternalID”)||https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE+Banking+%28Quality+Management%29/testcase/myExternalID|
|Create a Test Case Execution Results (ext ID “myChosenID”)||https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE+Banking+%28Quality+Management%29/executionresult/myChosenID|
A common pitfall I found myself helping customers with were failures at creating test resources due to failing HTTP requests (403, etc.)
Be aware such errors typically occurs in the case where :
– you’re using a browser
– you’re doing a POST access
– you’re targeting RQM version 22.214.171.124 (or later)
There, you would directly get a 403 “Forbidden” HTTP status code returned.
Indeed, starting in RQM 126.96.36.199, there is an additional check for the header “X-Jazz-CSRF-Prevent“. It’s required ONLY for a POST access coming from a browser environment (note: this is detected by the Jazz server through the ‘user-agent’ header).
To stay on the safe path, I recommend you :
– either use a PUT access instead (depending on your use case),
– either add the additional header “X-Jazz-CSRF-Prevent” with the current JSESSIONID value in your favorite browser tool (Poster, RESTClient, etc.). For this, you just need to search your cookies and copy the ‘Content‘ value of the JSESSIONID for the hostname and path (/qm) corresponding to your server public URI. A practical description on how to retrieve such value (from Firefox/Mozilla browser) is provided in this Jazz.net forum post.
Other things to keep in mind:
- If providing an external ID, you should make sure your PUT does NOT contain any /urn:com.ibm.rqm:xxxxxx content (this is reserved for GUI created test artifacts).
- If you don’t provide an external ID (like in the “Create a Test Case” sample above), RQM will auto generate one. It shall be returned in the response header “Content-Location“.
5.1 QM OSLC References
- [Open-services.net] OSLC Community
- [Open-services.net] QM specification V 1.0
- [Open-services.net] QM specification V 2.0
- [Jazz.net wiki] RqmOslcQmV2Api
- OSLC workshop (v4.0) (covers RTC + RRC. Plans for adding RQM into the scene are on-going)
5.2 RQM REST API References
- [Jazz.net wiki] RQM REST API
- [Jazz.net wiki] Field selection sample (very useful)
- [Jazz.net wiki] RQM API Debugging Tips
6. Other resources
6.1 Additional samples for RQM REST API
- [Blog post] Snapshot Your Test Assets via the RQM API (for accessing / creating snapshots through HTTP PROPFIND / SNAPSHOT custom methods respectively)