Extending Rational Quality Manager using Reportable REST API
This article explains how to start customizing Rational Quality Manager (RQM) to use the REST API. IBM provides jar file for interacting with the RQM server and you can build your own customization. This article also explains how to use the REST client add-on with Mozilla Firefox for analysis of CRUD methods, various options to call/deploy your customization piece, and an explanation of CRUD methods.
Contents:
1. Brief of overview of RQM
2. Need for customization
3. Getting started with customization
4. Authenticating RQM server
5. GET Method
6. POST Method
7. PUT Method
8. DELETE Method
9. Integration of customization with RQM
10. Conclusion
1. Brief of overview of RQM:
- RQM is a test management tool, web based and its built on the IBM Jazz Platform.
- IBM Jazz technology is new technology from IBM and it has several characteristics and is designed to allow collaboration across different teams spread across geographic location and to transform how people work together, making software delivery more collaborative, productive, and transparent.
- Jazz is an extensible framework and dynamically integrates with other products. It helps to make people aware of different processes and assets associated with the software development process.
- RQM supports various roles of testing process; it supports roles like Test Manager, Test Lead, Automation Engineer, Manual Tester and Test Lab Manager.
- All Testing activities like test authoring, planning, and execution, reporting and end-end traceability between test artifacts like test case, test script, test suite and test plan can be managed using RQM.
2. Need for customization:
The following explains why we need customization of any COTS product:- The features and functions we’re looking for aren’t necessarily available in the existing systems
- Specific customer requirements
- Customer satisfaction and high expectations from the customer
- To increase business values by decreasing effort and time-to-market
- To provide value added services to the products and customers
3. Getting started with customization:
Rational Quality Manager is also a COTS product and may need customization from time to time to enhance its functionality. To that end, we need to run our utility/program outside of RQM which will connect the RQM server and perform certain database transaction using RESTful web services (GET, PUT, POST and DELTE), also called as CRUD methods which we will discuss later in separate section.
To start your customization, we need to import an external jar file provided by IBM into your Eclipse Client workspace. To download RQMUrlUtility.jar, go to “All Downloads” page of the respective RQM version. You’ll fine it under the ‘Extra’ subheading.
Pre-requisites:
Compatibility: The RQM URL Utility is built on the RQM Reportable REST API, which is not compatible between RQM versions
Permissions: Reportable REST API’s require users to have project-level permissions to do transactions. Please take a look at this RQM API wiki for more details on permissions.
Requirements: Requires Java 6.0 (Sun JRE 6.0 Update 23 or IBM JRE 6.0 Service Refresh 8) or later
The usual steps for any database transactions include:
- Login using Authentication mechanism with appropriate credentials
- Perform transactions on database (here transaction mean GET, PUT, POST, DELETE)
- Logout
Please note that database transactions meas only CRUD methods and data flow will be in the form of XML representation only. There is no direct access to any of the database tables which RQM uses. It is not recommended to touch the RQM database.
The pictorial representation of the same is shown below:
The type of response depends on the type of CRUD method invoked. For example: For the GET method, the HTTP response body will be XML representation of the resource.
Installing REST client add-in on Mozilla for Analysis of CRUD methods:
Similarly for RQM reportable REST API’s you can analyze the XML data and write your design accordingly by installing REST client/Poster on Mozilla which comes as an add-on. Both REST client and Poster work in similar fashion. They only differ in their user interface. In this article we focus on the REST client, which I feel is a bit easier to use. Just Google REST client and install the add-on. I’ve included a screenshot of what it looks like after installation.
Add the required request header using the Headers link provided. Usually the format is a name and value pair, for example, here we have added the header as:
Name: Accept
Value: application/xml
These headers normally used for all CRUD methods
Method drop down specifies the type of the request (GET, PUT, POST and DELETE)
URL specifies REST url of any resource (like in RQM Test Case, Test Script, Test Plan etc). The detailed url representation of these resources are discussion later in this article. Once adding Headers, Method and URL click on SEND button, the user gets the response header and response body in the form of XML / success message depending on type of CRUD method.
The URL format of the resources:
singleProjectFeedUrl
integrationUrl/resources/projectAlias/resourceType
IntegrationUrl:
https://host:port/contextRoot/service/com.ibm.rqm.integration.service.IIntegrationService
The contextRoot of the Rational Quality Manager application
Rational Quality Manager 1.x and 2.x: jazz
Rational Quality Manager 3.0.1 or later: qm
The above context roots are default but configurable during installation.
For more information on resource URL specifications, please visit: URL Specifications
In general, simple way to understand the format of the complete resource url is:
https://host:port/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources
/ProjectArea/resourceType/urn:com.ibm.rqm:resourceType:resourceId
where resourceType can be, testcase, testscript, testsuite, test plan etc.
For more information on resource types and their supported operations, please refer the url: Resources and their supported operations
4. Authenticating RQM Server:
Before accessing any resource, we need to login with appropriate credentials with RQM server. Login method is already available with the RQMUrlUtility.jar, you can use this method for logging into RQM.For e.g., the line of code that will login to RQM server:
rqmLogin.login(userid, password, context);
Where rqmLogin is http client object created from the following constructor from RQMUrlUtlyLogin class.
userid stands for user name of the RQM member who is having permission to act on specific resource.
password is password of RQM user
context is “qm” in RQM 3.0.1 or later
To create rqmLogin object, for e.g.,
rqmLogin = new RQMUrlUtlyLogin(protocol, hostName, port, projectArea);
Where:
protocol is name of the protocol being used for e.g., HTTP
hostname is name of the host where RQM server is hosted for e.g., mycompany.com
port is a port number being used by RQM server, by default it will be 9443
projectArea to which you want to connect, e.g., JKE Banking (Quality Management)
5. GET Method:
The GET method is used to get XML representation of any resource. For e.g., to get the XML of Test Case resource from RQM, the URL for the same is:Where, URL= https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE Banking (Quality Management)/testcase/urn:com.ibm.rqm:testcase:1
Where, the value “1” is test case id generated by RQM when created. As discussed above, we can use the REST client to get the XML of test case:
Input Specifications: Method, URL and Headers, see Fig below:
Output:
On click of SEND, response body contains XML representation of the test case and response header contains response code, content type etc. Sample example is given below with Fig
Response Header:
Response Body:
XML string variable will have all the information of artifacts and can use either SAX/DOM parser to get values and display in custom web UI
6. PUT Method:
The PUT method is used for editing the existing artifact.
Input Specifications for PUT method are
Method name, Headers, URL and body, see in Fig below
Where,
Method Name: PUT
Headers: name=accept: value=application/xml
URL: The url must contain details of host, project area etc as specified in PUT method
Body: XML schema of the test case which you want to modify.
e.g.:
https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE Banking (Quality Management)/testcase/urn:com.ibm.rqm:testcase:1
Where “1” is internal test case id generated by RQM and the artifact you want to modify
Output:
On click of send you can see response header status as 200 OK, and the response body will be empty.
Response Header:
Response Body:
Response body will be empty
POST Method:
7. POST method is used to create artifacts on the go. POST method takes XML representation of the test artifact as input body.
Input Specifications for POST method are (See Fig below)
Method: POST
Header: name=Accept: value=Application/XML
URL:
https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE Banking (Quality Management)/testcase/urn:com.ibm.rqm:testcase
Here we do not specify ID, as artifact is getting created and POST method returns some randomly generated ID called Slug Id contains in response header
e.g.: slug_123scfvhrt2wsd
Body: XML schema of artifact
Once you get slug Id you can append this Id to URL to get the XML of the artifact by using GET method
8. DELETE Method:
DELETE method is used to delete the artifact from RQM server. See Fig below
The input specifications for DELETE Method are:
Method: DELETE
URL: Complete URL of the artifact to delete
e.g., for test case having Id as “5”
https://localhost:9443/qm/service/com.ibm.rqm.integration.service.IIntegrationService/resources/JKE Banking (Quality Management)/testcase/urn:com.ibm.rqm:testcase:5
Header: name=accept: value=application/xml
On click of send, on successful delete, you will get status code as 200 OK in response header of the HTTP response
9. Integration of customization with RQM:
So far we have seen how to develop the extension to enhance the functionality of RQM. There are several ways of deploying our utility developed. Some of them are listed below:
- Developing .exe / jar file / batch file and invoking the utility manually by user.
This method involves manual intervention as it needs to be invoked manually by using some command line interface or by using windows task scheduler
- Developing .exe / jar file / batch file and invoking the utility with the help of RQM command line adapter
Another way of invoking utility is to create separate test case and attaching this test case to script (script can contain batch file and its stored in some machine and has the instruction to execute .exe / .jar/ batch file) and execution of test case using command line adapter. For e.g., you have test suite having 10 automated test cases and are being executed sequentially and 11th test case can be your extension utility where it can be invoked using command line adapter.
For more information on command line adapter and its usage please visit following URL on jazz.net:Command Line Adapter
- Developing your extension using rich web UI using web technologies
You can develop your utility in the form of web and you can invoke the web UI from RQM Related Sites as show in following Fig. To add related site go to Mange Project Properties, under properties section click related sites
Related site gets added in related site section on left side of the RQM:
You can invoke web UI and get all the artifacts into web with the help of REST API’s and implement all required functionalities.
10. Conclusion:
Rational Quality Manager Reportable REST API’s has the strong capabilities and rich set of API’s and sopports various artifact type and various operation like GET, PUT, POST, DELETE, LOCK etc. You can implement any kind of exteniosn that may satisfy the requirements and expectation that are not exist in RQM
For more information
About the author
Chandrahasa Reddy is working as an IBM Rational Product Specialist in Tata Consultancy Services Ltd.(TCSL) with in Technology Excellence Group (TEG) group. He has over 5+ years of experience in various rational products mainly on testing tools like RFT, RPT, AppScan and various other jazz tools like RQM, RRC and RTC and research in industry best practices. He can be contacted at chandrahasa.reddyd@tcs.com.