December 28, 2009

Requirements Review Web Client

Helix ALM
Since the introduction of TestTrack RM earlier this year, I've had a chance to demonstrate the product many times to prospects. While the initial feature set of the product is impressive, every once in a while I do hear about features that are not currently available. These become feature requests, which are prioritized and scoped out by our product management team. One feature request I have heard a few times is for a very specific need. This scenario is for a user whose only action related to requirements is to approve or reject them. This user is not in development, QA, or any other group directly involved with software development and does not use TestTrack. This individual is likely to only deal with business requirements and not functional requirements.  The user does not want to install the TestTrack client and learn how to use it when only a simple view is needed to review and approve or reject requirements. While this feature request goes through the process, I decided to write an ASP.NET app to help with this need.  The app is called RM Review and it is written in C#. Download RM Review now. This is a very basic web client that allows a user to access a specified requirement, view the description, and either approve or reject it.  The requirement is specified in a link sent to the user by an email notification from TestTrack.  Some sample screenshots are in the gallery below. [toc] RM Review is an ASP.NET web site. It is a simple web interface to approve or reject a given requirement in TestTrack RM. No other functionality is available. Access is given through a link passed in a notification e-mail.

Use Case

Some requirements need approval by someone that is not a TestTrack user. Having this user log into TestTrack may not be desirable as they may not want to install the client and learn how to use it. All this user needs is the ability to approve or reject a requirement, nothing more. This web client is aimed at solving this particular use case. Figure below illustrates the basic flow of the application.

RM Review Flow Chart

Workflow

RM Review is designed to work with the default workflow that comes with TestTrack RM for Requirements. It gives the user the option to perform the "Approve" or "Reject" workflow events. It also provides a text box for the user to enter any comments with the event. For example, why the requirement has been rejected.

Security

The user will be required to provide a username and password. This will be authenticated against TestTrack and the workflow event will be attributed to the logged in user. In the current version, the user will have to log in every time. The web client does use the ASP.NET log in control, which does provide a "Remember me next time" check box to save the username. However, in testing this did not work all the time, and Microsoft noted of a possible security hole when using persistent cookies. Another solution could be to get the username from the Windows session and match that against the users in TestTrack. This however, would not be very secure as this would not authenitcate the user against TestTrack.

Requirements

Any user that uses this tool must have the permission to Manage Global Users. This is set in the Seapine License Server Admin utility. Please refer to the Seapine License Server Admin User Guide for more details. This is nescessary to be able to determine the first and last name of the currently logged in user. If there is a concern in giving the user this priviledge, the risk can be mitigated:
  • If the concern is about accessing the Seapine License Server Admin utility, you can have permission to manage global users and still not access this client as illustrated by this screenshot from the Seapine License Server Admin utility.

Edit Global User window

  • If the concern is about being able to manage users in TestTrack, you can take away these permissions in the TestTrack Project. The only permission needed in TestTrack is to View Users. The following screenshot shows the permission in TestTrack

Edit Security window

This screenshot shows the access that the user would have.

View Users window

Email Template

The e-mail that the user receives should have a link to the Login.aspx page. This URL needs to have the requirement number as a parameter. The example below will take the user to Requirement number 34 (assuming successful log in, of course) http://localhost/RMReview/Login.aspx?ReqID=34 To set this up in the e-mail template you will concatenate the URL in the example above (except the number) and the field code for the Requirement Number. http://localhost/RMReview/Login.aspx?ReqID=%RQNUM% Following is a screenshot of what an email template might look like.

Sample Email Template

Automation Rule

The use case calls for an email notification to be created when a requirement arrives at the "Ready For Review" state. This should generate an e-mail using the template mentioned in the previous section. The user will get an e-mail like the one shown below.
[caption id="attachment_4131" align="aligncenter" width="405" caption="Sample email"][/caption]

If you have modified your workflow, you can set up the rule to take place when the requirement arrives at a different state. However, the application does need an event called Approve and an event called Reject.

Application

Detailed Flow

When the user clicks on the link in the e-mail, a browser opens directing the user to the login screen. Image below shows the login screen.
[caption id="attachment_4132" align="aligncenter" width="351" caption="Login window"][/caption]
As mentioned above, the credentials provided by the user are the ones in TestTrack. The user will get an error if unable to authenticate against TestTrack. If logged in successfully, the user will then be presented with the requirement, as shown in the image below.

Requirement Window

The user has the following options:
  • Log out - If the user does not want to take any action, the log out button is provided. This will log the user out of TestTrack (free up license) and close the browser.
  • Notes - A text box is provided in case the user wants to add notes to the approval or rejection. The notes are not required.
  • Approve - Will perform the Approve event in the workflow.
  • Reject - Will peroform the Reject event in the workflow
If there is an error updating the requirement, the user will be presented with a message box, with a meaningful message. Image below shows a sample error message that a user will get if the record is locked.
[caption id="attachment_4134" align="aligncenter" width="238" caption="Sample error message"][/caption]
If the user clicks OK, the client goes back to the requirement window. At this point the user can try again, or log out. If the requirement is updated successfuly, then the user will be taken to another page indicating that the action was successful and that the user has been logged out. The page also contains a close button. The user may also 'x' out of the browser.
[caption id="attachment_4135" align="aligncenter" width="480" caption="Close page"][/caption]

Tech Details

Installation

The download contains an installer. This is pretty straight forward and defaults should suffice. The only setting that you may want to change is the location of where the files will be installed. The virtual directory in IIS will be created for you and point to the installation directory. You will need to restart the web site.

Configuration

The only configuration needed is the address of the TestTrack SOAP CGI and the TestTrack project name. This is stored in the web.config file. The defaults are http://localhost/scripts/ttsoapcgi.exe and Sample Project. Use a text editor to change this to match the location of your SOAP CGI. Image below illustrates where this is set in the file.

web.config file

IMPORTANT NOTE: The IIS instance does NOT have to be on the same machine as TestTrack. For example, TestTrack could be running on a Linux machine. Also, the IIS instance that runs RMReview does not have to be the same instance running the TestTrack SOAP CGI. This could be running on a separate web server, even a different type, like Apache. So the fact that this is an ASP.NET app should not prevent it from being implemented in a Linux or MAC shop as long as there is a machine that has Windows with IIS on it.

Download

The installer is available here. It will install the source code files as well.

Enhancements/Limitations

When developing this tool, the simplest approach was taken. This means that this may not meet all of your requirements. Here are some limitations:
  • Need workflow events called Approve and Reject.
  • Text in description does not have any formatting. In line images are not included.
  • Limited data is displayed: the summary, description, status and number.
  • No support for custom fields on the Requirement window or event dialogs.
The source code is provided as part of the installer in case you would like to create your own web client and use the source code as a starting point. You may also consider having us customize this for you.

Questions/Issues

As with all other tools and samples available here, this is not supported by Seapine Software. However, feel free to shoot me an email if you think you have found a bug. I will not be of much help if you need help configuring IIS, technical issues or need modifications. I can probably address basic questions and perhaps (if I have the time) fix minor bugs.