QVscribe for Polarion

Support articles for QVscribe for Polarion

Overview and Installation

QVscribe Polarion High-Level Architecture

QVscribe for Polarion Prerequisites

QVscribe is an Add-in (extension) for Google Chrome with the following prerequisites for installation:

  • Microsoft Windows version 10, 64 bit

  • Google Chrome 85 or Greater

  • 4 GB and above RAM

Currently, QVscribe supports Polarion Requirements V20.

QVscribe for Polarion User Set up

All QVscribe for Polarion users will need the following to setup QVscribe:

  1. Download files for the QVscribe Browser extension

  2. The QVscribe Teams Server hostname/IP

  3. Their username and password *Note: this not needed if you are using Active Directory for licensing

Below outlines all the steps they will need to take to setup QVscribe for Polarion:

QVscribe Installation Process

Step 1: Run the QVscribe installer

Step 2: Open Google Chrome and type chrome://extensions in your address bar.

Step 3: Enable the Developer Mode present on the top right corner of the window.

Step 4: Select Load-Unpacked

Step 5: Select folder (%appdata%\QRA Consulting Inc\QVscribe\chrome\extension) in your Google Chrome. The QVscribe icon will show up on the top-right corner in the extension bar.

Step 6. Disable the Developer Mode.

Step 7: Click on the QVscribe 3.0 icon and check the status of the analyzer. If the analyzer is offline, click “Start up Analyzer and Log into Server”.

Step 8: Enter your QVscribe Server IP or Hostname and then click Connect to your QVscribe Team Server. Note: This should be provided to you by your QVscribe Admin.

Step 9: Pick your identity provider. This information will be provided by your QTS Admin as well. If you are connecting via QTS User Directory, you should have been provided a username and password. 

Alternatively, if you are connecting via Active Directory, you will automatically connect via your computer login credentials.

Connecting by QTS User Directory (Username and Password)

Choose QTS User Directory and click continue.  This will bring you to a page to enter your QVscribe credentials provided to you by your QTS Admin.

Once you have connected you by username and password, you should see the following message.

Connecting by Active Directory

Once you have been connected by your AD, you will receive the following message.

QVscribe 3.0 service running

The Browser extension requires the underlying QVS Analyzer service to be running

Step 1: Make sure you are logged into Polarion

Step 2: Open the  Browser extension in Chrome

Step 3: QVS Analyzer status should indicate online, if not, press "Start QVS Analyzer" and follow Steps 7-9 above

QVscribe for Polarion Connector Installation

This article outlines the steps needed to install the Polarion Server Extension for QVscribe. This servlet allows the QVscribe web client to communicate with the Polarion API and is necessary for QVscribe for Polarion users to access Quality, Consistency, and Similarity analysis for a set of Work Items.

Step 1

Stop Polarion server

Step  2

Copy the qvscribe_connector folder supplied by QRA to 

[Polarion Install Path]/polarion/extensions.

Note: If you do not have a copy of the qvscribe_connector, it can be found under %appdata%QRA Consulting IncQVscribepolarion on a computer with QVscribe Polarion installed. 

Step 3

Delete [Polarion Install Path]/data/workspace/.config

Step 4

Start Polarion server

Step 5

Log into Polarion

Requirement Selection and Views in QVscribe

Configuring Summary Analysis Using Filters in QVscribe for Polarion

When using QVscribe for Polarion, the QVscribe Analyzer will perform Analysis on any work item that has a description. To control what work items are included in the analysis, simply use the filter feature within Polarion.

Use the filter feature to control the specific work items in the summary analysis.

This feature currently supports Live Doc and Table Views.

Note: Using a filter on a Live Doc will put all items in the “read only” state, thereby causing the QVscribe authoring buttons to disappear on individual work items. As described above, Summary Analysis can be done, but authoring on individual work items cannot be done under these conditions.

Configuring Polarion for Document View

Enabling Authoring View for Work Items

QVscribe for Polarion offers the ability to open a specific work item while in Live Doc view. To use this feature the “status” of the work item must be active and visible within Polarion to see the QVscribe icon.

To enable this feature, follow the steps below.

  1. While in Live doc view, click the dropdown arrow next to the work item icon and choose “Configure”

2. Next to each work item type, there is a button titled “Select Fields”

3. If “Status” is not already in the right-hand box, find and select it in the left-hand box titled “Available Fields”, then click “Add”. “Status” will now be highlighted in the right-hand box. 

4. In the options underneath the selected fields, enable “Show in the Sidebar and Document”.  . There are two icons to represent where the status icon will appear. Set the status to “Show At” at the bottom right of the requirement, which is the icon on the right side.

5. Finally, select Render as “Icon & Text”

Save your settings as default to allow the QVscribe Authoring View Icon to be displayed when viewing work items in Live Doc View.

Summary View in QVscribe for Polarion

When viewing a Work Item with QVscribe for Polarion installed, the QVscribe icon will be displayed to the top right of the query filter. Selecting this icon will open the QVscribe Summary view for all analyzed requirements.

The summary view is organized into 3 key sections.

Quality Score Summary 

This section will display all analyzed requirements within the selected Work Item. Each requirement will be categorized according to their level of risk. Selecting any of the score bars will navigate users to the Quality Analysis section filtered for the selected quality score.

At the bottom of this view, you can select the icon to change from the quality score summary to display the same requirements broken down by the specific quality issues.

Quality Warnings

The Quality Warnings sections will display the requirements that have issues that QVscribe recommends additional attention or review.

Selecting any of the warning categories will navigate users to the Quality Analysis section filtered for the selected quality warning.

Summary Navigation

The Navigation section provides easy access to the various analysis types available in the summary view.

Selecting any section from the navigation pane will display the associated analysis views available in the summary view.

This section also includes the overall score for all analyzed requirements in the selected Work Item.

Editing/Authoring in Summary View

Users will have the ability to edit/author requirements within the Summary view. This can be done when you open a requirement within the Quality Analysis.

Once you open up a requirement, you will see an icon in the top right beside the requirement. You can click this icon to edit/author the requirement.

This icon will bring you to your authoring/editing window. Click the pencil icon to edit the requirement, then you can edit the text within Polarion or click the QVscribe icon to edit within QVscribe.

This brings you to the authoring view, where you can make changes/edits. The QVscribe analysis will update to your changes showing you whether your score is improving.

Authoring View in QVscribe for Polarion

While viewing a Work Item with QVscribe for Polarion installed, when an item is in “Draft” status  for a specific work item, the QVscribe icon will be displayed.

QVscribe also provides the ability to open the authoring view in document view. Work Items that are editable will see the QVscribe icon next to the status of the work item.

Work Item text

If this QVscribe icon is clicked you will enter the QVscribe authoring view. This section provides access to the text of the work item with any alerts highlighted and colour coded. 

Within 2 seconds of any changes to the text, QVscribe will automatically rerun the quality analysis updating the score and any associated alerts according to the active configuration. You can also re-run similarity and unit consistency analyses by selecting the “re-run” icons that will appear.

Once the text updates are complete, simply close the QVscribe authoring view to update the text in the work item. 

Note: QVscribe will not commit any changes to Polarion. It will be important to complete your changes in Polarion as you normally would.

Alerts

The alerts section will identify all associated alerts with the selected text. Red alerts indicate issues that are affecting the quality score of the requirement while yellow alerts provide warnings recommending additional attention.

Selecting any of the alerts will expand the alert, displaying additional information about the alert for the author’s consideration.

Filters

The filters section provides users with the ability to filter the specific alerts that are displayed in the Authoring View. 

Selecting any of the alert categories will filter the alerts, displaying only the selected category. 

Additionally, the filter section provides the quality score for the requirement and also displays the link to select from a number of EARS Templates.  See QVscribe for Polarion EARS Templates section for more details.

Requirement Analysis

Quality Analysis in QVscribe for Polarion

Running Quality Analysis in QVscribe for Polarion can be accessed by clicking on the QVscribe icon at the top of any Live Doc View or Table View

Once selected, the QVscribe summary dashboard will open. The 5-level scoring gives you a succinct picture of which requirements need the most attention and which ones adhere to best practices.

Quality Analysis Details and Term Highlighting in QVscribe for Polarion

When viewing the details of any analyzed artifact in QVscribe that has one or more alerts, selecting the alert will highlight the element of the artifact that created the alert.

In the example above, the quality alert for “Vague Words” has been generated. Selecting the alert will then highlight the vague words that specific alert has been generated from.

By default, all alerts will be displayed. Alerts can be filtered by using the right-most menu. This allows the user to focus on one specific type of alert, hiding all the others (e.g. select “Multiple Imperatives” to only display alerts pertaining to “Multiple Imperatives”). All the alerts can be displayed by choosing “All Alerts” from the right-most menu.
Note: If some analysis results are inconsistent with your company standards, ensure that the QVscribe Configuration being used is appropriate for the document, or talk to your QVscribe administrator about creating a QVscribe Configuration that more directly adheres to your specific standards.

Sorting and Filtering Quality Analysis results in QVscribe for Polarion

Opening Quality Analysis

Within Polarion, QVscribe enables the ability to run a Quality Analysis for requirements. To access this analysis start by selecting the “Summary View” icon next to the query menu of the set of work items from the Live Doc or Table view.

Within the Summary View, select “Quality Analysis” from the right-hand Navigation Menu.

Quality Analysis

After selecting “Quality Analysis” QVscribe will present the Quality Analysis for each of the requirements based on the order they are displayed in the Work Item. You may navigate to any of the individual requirements to see their detailed analysis. See Quality Analysis Details section for details. At the top of this view are 2 tools that will help you refine the list of artifacts to focus on the areas you want to look further.

Filter Requirement

Filter Requirement provides a drop-down list that allows you to display artifacts based on the 1-5 score calculated by QVscribe or different Quality Issues that exist within the list. Selecting any option in the list will filter the requirements displayed for the selected item.

Sort Order

The sort order drop-down provides a number of sorting options based on the requirements order, quality score, or the number of warnings associated.

 

 

 

Consistency Analysis in QVscribe for Polarion

QVscribe’s Consistency feature includes 2 types of analysis: units and terms. You can navigate to these analysis types through the corresponding section in the summary view. These analyses display the terms and units found within your requirements enumerated and in sortable and searchable lists.

Term consistency 

All found terms and phrases that appear to be domain-specific are displayed, along with a total count and number of terms similar to it.

You can search for a specific term by entering text beside the magnifying glass icon.

Terms can be organized by selecting the drop-down beside the “Alphabetical Order” text in the top right. The options are:

  • Alphabetical Order: Default option, displays terms alphabetically

  • Most Occurrences: Displays terms in order of the number of times they appear from the highest number of occurrences to least number of occurrences

  • Most Similar: Displays terms in order of the number of similar requirements, from the highest number of similar requirements to the least number of similar requirements

  • Highest % Match: Displays terms based on the highest % match to other identified terms

The terms in the Consistency section can be explored by selecting any term to show all requirements where that term appears, as well as a list of similar terms and the %-similarity for each. Each of these similar terms can be expanded to show the requirements where it appears. This helps rapidly verify that these similar terms are valid in their own right, and reside in the correct requirements.

This similarity can be tuned in real-time with the Matching Strength Min and Max settings located in the User Settings section of the QVscribe Browser Extension. 

The Matching Strength gives the tolerance in the assessment of term similarity, such that a Matching Strength of 100% means the terms have to be identical for them to be considered similar, and as this Strength is decreased, then more terms will be considered similar.

Unit Consistency

Unit Consistency displays all units detected, along with their type categorization and total count. Each unit in the list can be expanded to show the requirements where it was found and highlight the unit within. This helps ensure that the right unit is in the right requirement and that there is consistency in the system of units used throughout the document (i.e. metric or imperial).

You can search for a specific unit by entering text beside the magnifying glass icon.

Units can be organized by selecting the drop down beside the “All” text in the top right. The options are:

  • All: Default option, displays all the identified units

  • International System of Units (SI): Displays identified SI units

  • Inconsistent with International System of Units (SI): Displays identified units that are not SI units

Selecting any unit in the list will display all the requirements that include that unit with the unit highlighted.

Unit consistency can be updated any time in the Configurations section of the QVscribe Browser extension.

Units can be customized to suit your team’s needs and can be added, edited, and removed to determine what units are included in the analysis.

Similarity Analysis in QVscribe for Polarion

The Similarity section shows the results of the requirements similarity analysis. The number of similar requirements found is shown beside each requirement in the list. 

The requirements can be sorted by Order of Appearance (default), Number of Similar, or Highest % Match, by selecting the drop-down beside the “Order of Appearance” text in the top right.

Expanding a requirement lists its similar requirements on the right, along with a percentage of how similar they are. Clicking a similar requirement in the list will then display the clicked on requirement below the original with the differences highlighted in light purple.

A Matching Strength min and max setting is available in the User Settings section of the QVscribe Browser Extension.  This lets you adjust how close requirements need to be in structure and terminology to be considered similar. 

It is useful to try different Matching Strength settings within 75% to 95%. This will display requirements that may contradict each other. You can also set the Matching Strength to 100% to review if there are any identical requirements

Create a report in QVscribe for Polarion

In the Summary View, click the ‘Create Report’ button in the bottom right-hand corner.

A window will appear for you to configure the report and choose the file name. Once your settings are set, press Create Report.  This will create a PDF of your QVscribe report.

 

The QVscribe analysis report includes:

  • Document title, analysis date, the configuration used, and a total number of analyzed requirements.

  • Score Summary detailing the number of requirements with each score.

  • Analysis Breakdown showing how many requirements include each of the QVscribe quality indicators.   

  • Summary of EARS Conformance for all requirements (Easy Approach to Requirements Syntax).

  • The list of individual requirements with their corresponding scores, quality indicator/unit highlighting, analysis details, EARS conformance, number of similar requirements, and a terms list.

  • A detailed list of all terms and units present.

  • A list of highly similar requirements displayed dependent on the Matching Strength Threshold chosen.

  • A detailed Appendix of the Configuration settings used during the analysis.

Configuration and User Settings

Navigating your Configuration Window in QVscribe for Polarion

After installing the QVscribe Browser Extension, the QVscribe for Polarion configuration can be accessed by clicking the puzzle piece icon next to the address bar on Google Chrome.

From the drop-down menu that pops up, click the pin icon that appears next to the QVscribe extension option. This will pin the extension to the taskbar for easy access.

The QVscribe for Polarion configuration can be accessed using the QVscribe Browser Extension located to the right of the address bar in Google Chrome.

The QVscribe for Polarion Configuration has 3 key sections. Configurations, User Settings, and Help Center. The default screen highlights the active configuration, the user currently signed into QVscribe, the version number of the extension, the status of the QVscribe analyzer as well as quick access to the QVscribe Help Center.

The ability to select any saved configuration is available to all users, but to change settings within the configuration requires the “Configuration Author” role.  You may select a saved configuration in the drop-down menu on the top right corner of the QVscribe window.

The configuration section of the QVscribe extension is used to modify settings for:

  • Trigger words

  • Unit Consistency

  • Exclusion Prefixes

Once Configurations have been selected, there is a secondary menu that will allow users to navigate to the settings for each of the above sections.

The Trigger Words option can be further expanded to display a tertiary menu to edit each of the configurable quality indicators. Here, the user can customize their trigger words by adding new ones, editing existing ones, or removing existing ones.

The User Settings section provides a more detailed overview of the user account information, including seat pool, version number of QVscribe, status of the QVscribe Team Server, address of the QVscribe Team Server, and current selected Identity provider. Additionally, this is where users can sign out of QVscribe.

The user settings section of the QVscribe extension is used to modify settings for:

  • Artifact Analysis

  • Term Consistency match strength

  • Similarity match strength

  • EARS Template Conformance

The Artifact Analysis configuration has no impact on the Polarion analysis.

The Help Centre provides users a link to the QVscribe Knowledge Base, access to support contact details, and the ability to provide QVscribe logs that can be used to diagnose issues should they arise.  Please view the Help Centre in QVscribe for Polarion for more detailed information.

QVscribe Help Centre in Polarion

The QVscribe Help Centre details can be found by clicking the QVscribe browser extension.  

To go to the Help Centre, you can find the link directly on the main page of the QVscribe Browser Extension Menu.

If you select the Help Center option on the left, you can find more information.

 Another link to the Help Centre can be found here.

If you experience errors, unexpected behaviour in QVscribe or if you would like to contact us for assistance, select the Contact Support option on the left.

Follow the steps outlined on this page to contact QVscribe support.

 

Easy Approach to Requirements Syntax (EARS)

EARS Templates in QVscribe for Polarion

The Easy Approach to Requirement Syntax(EARS) is a standard for writing requirements that will improve the quality and consistency of your requirements. Read more here.

EARS Templates in QVscribe

When users are viewing a requirement in QVscribe’s authoring view, there is an option to insert an EARS template.

Select Template Type

Select one of the EARS templates made available within QVscribe. By clicking on any of the options listed, the full template and explanation for this type will be shown.

Insert a Template

Once you have selected the template you would like to insert, click the grey icon to insert it into your requirement.

Edit the template

Once the template has been added to the requirement section, you are able to modify it freely.  After modification, QVscribe will check for conformance with any EARS template and score it according to the active configuration. See the EARS Template Conformance document for more details.

EARS Template Conformance in QVscribe for Polarion

The Easy Approach to Requirements Syntax(EARS) is a standard for writing requirements that will improve the quality of your written requirements. Read more here.

EARS Compliance

When viewing an Artifact’s Quality Analysis, QVscribe will automatically detect if a requirement is compliant with the EARS standard. The identification of an artifact’s compliance with the EARS standard will be displayed in the Alert Column.

Selecting the Alert will provide an expanded view that includes additional information about the compliance of the standard.

Additionally, the specific type of EARS requirement will be displayed in the left-hand menu.