QVscribe for Jama

Support articles for QVscribe for Polarion

Overview and Installation

QVscribe for Jama High-Level Architecture

QVscribe for Jama Prerequisites

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

  • Microsoft Windows version 10, 64 bit
  • Google Chrome or Microsoft Edge 90 or Greater
  • 4 GB and above RAM

 

Currently, QVscribe supports Jama Connect(Cloud) 8.58.0.

Tested on: Non-Production version

Screen Resolution: Minimum of 1024 × 768 screen resolution.

Javascript: Must be enabled.

OS: Windows 10 64 bit

 

Supported Browsers: Google Chrome – Supported by QVscribe (Note: Jama is only supported on Chrome versions released over past 12 months)
Microsoft Edge (Chromium Platform)

 

QVscribe is not supported for the following browsers:

Internet Explorer 11

Firefox

Firefox ESR as of Jama 8.10

Safari

 

QVscribe for Jama User Set up

All QVscribe for Jama 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 Jama:

QVscribe Installation Process

Installing QVscribe for Chrome

Step 1: Run the QVscribe installer

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

You can also access your extensions by clicking on the puzzle piece icon on the top right corner of your Chrome browser.  Click on Manage extensions.

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 the folder bar at the bottom of the window that opens.

Step 6. Disable the Developer Mode.

Step 7: After installing the QVscribe Browser Extension,  you can pin the QVscribe icon 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 Browser Extension can then be located to the right of the address bar in Google Chrome.

 

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.

Installing QVscribe for Edge

Step 1: Run the installer (QVscribeForChrome)

Step 2: Open Microsoft Edge and type edge://extensions in your address bar. You can also access your extensions by clicking on the elipsis icon on the top right corner of your Edge browser.  Click on Extensions.


Step 3: Enable the Developer Mode present on the bottom left corner of the window.

Step 4: Select Load-Unpacked

Step 5: Select folder (%appdata\%QRA Consulting Inc\Qvscribe\chrome\extension) in the folder bar at the bottom of the window that opens.


Step 6: Disable the Developer Mode.

Step 7: After installing the QVscribe Browser Extension, you should see the QVscribe icon in the upper right next to the address bar in Microsoft Edge

If the analyzer is offline click ’Start Up Analyzer and Log into Server’.

Step 8: Enter your QVscribe for Teams Server IP or Hostname and then click. Connect to your QVscribe Teams Server.

Note: This should be provided to you by the 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 a username and password.

Alternatively, if you are set up to connect 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 with your 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 QVscribe Analyzer service to be running

Step 1: Make sure you are logged into Jama

Step 1: Open the QVscribe Browser extension in Chrome

 

Step 2: QVscribe Analyzer status should indicate online, if not, press “Start up Analyzer and Log into Server” and follow Steps 7-9 above

Requirement Selection and Views in QVscribe

Summary View in QVscribe for Jama

When viewing items with QVscribe for Jama installed, the QVscribe icon will be displayed at the top of the page. Please note that the icon will be greyed out while Jama is processing the query.  This process may take longer if depending on the number of folders and sub-folders with items/requirements.

Once all items are ready for analysis, the QVscribe button will appear.

 Selecting this icon will open the QVscribe Summary view for all analyzed requirements/items.

You can use the QVscribe Summary View in the following ways:

  • Filters/Favourites

  • Nodes

  • Baselines

Summary View by Filters/Favourites

To view the QVscribe Summary for filtered or favourited items, access the Jama panel on the left side of the screen after accessing your Projects.  Click on the second tab, which is filters.

Your favourites will be listed if you have any created.  You can then select Add filter.

This will give you the ability to filter by your items in Jama. You can filter by projects, rules, conditions, time frames and item properties.

The Preview at the bottom will let you know how many items are in this filter.

 You can then name the filter and save, or just view the filter right away by selecting View in list.

The saved filter will then be listed in your Favourites.

You may open the QVscribe Summary View by clicking on the QVscribe icon.

Summary View by Nodes

To view the QVscribe Summary by Nodes, access your Projects in Jama. You can then select any node in your Jama panel, and a QVscribe icon will appear for those items.  

Note that any sub-items below the node selected will be included in the items list and QVscribe Summary.

Summary View by Baselines

To view the QVscribe Summary for Baselines, access the Jama panel on the left side of the screen after accessing your Projects.  Click on the fourth tab, which is Baselines.

Select a Baseline you currently have or create a new one by selecting Add and then Baseline.

To create a Baseline, select the items you want to be included in the Baseline. You can also use a filter, and select a specific release for your Baseline as well.

Select create and you will be prompted to Name the baseline and add a description.

When you open the Baseline, the QVscribe icon will appear.  Select the icon to view the QVscribe Summary View for the Baseline.

QVscribe Summary View Breakdown

The summary view is organized into 3 sections.

Quality Score Summary 

This section will display all analyzed requirements within the selected item/requirement. 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 item/requirement.

Authoring View in QVscribe for Jama

Authoring in Projects

You have the ability to edit/author an item when it is in “Draft” status.  You can do this by selecting the pencil icon to edit the item description.  

At this point, the QVscribe icon will be displayed.

Authoring in Reviews

You have the ability to edit/author items that are in Jama Reviews. You can do this by selecting an item with an active Review (meaning the review must be open and in progress).

To access QVscribe authoring, you can either:

  • Click on the drop-down icon on the item you would like to review and then click Edit Item.

  • Click on the Edit item button, when you are viewing a single item in the Reviews.

The item will then open up in a pop-up with the QVscribe icon present. Click on the icon to author in QVscribe.

Item text

If this QVscribe icon is clicked you will enter the QVscribe authoring view. This section provides access to the text of the 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 click on the icon to the right of the requirement to open it up in another tab to the specific Jama item.

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 item. 

Note: QVscribe will not commit any changes to Jama. It will be important to save your changes in Jama 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/item while yellow alerts provide warnings recommending additional attention.

Selecting any of the alerts will expand the alert, displaying additional information 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/item and also displays the link to insert an  EARS Template.  See QVscribe for Jama EARS Templates section for more details.

Requirement Analysis

Quality Analysis in QVscribe for Jama

Running Quality Analysis in QVscribe for Jama can be accessed by clicking on the QVscribe icon at the top of any Requirement Folder or Project.

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

Quality Analysis Details and Quality Indicator Highlighting in QVscribe for Jama

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.

All alerts will be displayed in the order they are found in the text. 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 Jama

Opening Quality Analysis

Within Jama, QVscribe enables the ability to run a Quality Analysis for requirements/items. To access this analysis start by selecting the “Summary View” icon at the top of the page for the set of requirements/items.

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/items based on the order they are displayed in the requirement/item. You may navigate to any of the individual requirements/items to see their detailed analysis. See Quality Analysis Details section for details. At the top of this view are two tools that will help you refine the list of requirements/items to focus on the areas you want to look further.

Filter Requirement

Filter Requirement provides a drop-down list that allows you to display requirements/items 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/items displayed for the selected item.

Sort Order

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

 

 

 

Consistency Analysis in QVscribe for Jama

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/items 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 highest number of occurrences to least number of occurrences

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

  • 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/items where that term appears, as well as a list of similar terms and the %-similarity. Each of these similar terms can be expanded to show the requirements/items where it appears. This helps rapidly verify that these similar terms are valid in their own right, and reside in the correct requirements/items.

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/items where it was found and highlight the unit within. This helps ensure that the right unit is in the right requirement/item 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(imperial)

Selecting any unit in the list will display all the requirements/items 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 Jama

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

The requirements/items 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/item lists its similar requirements/items on the right, along with a percentage of how similar they are. Clicking a similar requirement/item in the list will display the clicked on requirement/item below the original with the differences highlighted in light purple.

A Matching Strength minimum and maximum setting is available in the User Settings section of the QVscribe Browser Extension.  This lets you adjust how close requirements/items 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/items that may contradict each other. You can also set the Matching Strength to 100% to review if there are any identical requirements/items.

 

Create a report in QVscribe for Jama

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 the total number of analyzed requirements/items.

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

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

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

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

  • A detailed list of all terms and units present.

  • A list of highly similar requirements/items displayed dependent on the current Matching Strength Threshold selected in the QVscribe settings.

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

Configuration and User Settings

Navigating your Configuration Window in QVscribe for Jama

Your QVscribe for Jama configuration can be accessed in the QVscribe Browser Extension located to the right of the address bar in Google Chrome or Microsoft Edge.

The QVscribe Browser Extension 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 and view the keyword lists are 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 the trigger words by adding words, or editing/removing existing words.

The User Settings section provides a more detailed overview of the user account information including seat pool, the version number of QVscribe, the status of the QVscribe Application Server, address of the QVscribe Application Server, and the currently 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 Jama analysis.

The Help Centre provides users with 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 Jama for more detailed information.

QVscribe Help Centre in Jama

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 Jama

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

EARS Templates in QVscribe

When users are viewing a requirement/item 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/item.

Edit the template

Once the template has been added to the requirement/item 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 Conformance in QVscribe for Jama

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

EARS Compliance

When viewing a requirement/item Quality Analysis, QVscribe will automatically detect if a requirement/item is compliant with the EARS standard. The identification of a requirement/item’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 right-hand menu.