QVscribe Application Server

Articles related to the setup and configuration of the QVscribe Application Server (QAS)

Prerequisites & Overview

QVscribe for Teams Overview

QVscribe for Teams provides user management and enables project teams to share QVscribe configurations to ensure consistency in requirements analysis. 

The QVscribe Team Server (QTS) is installed in a centralized server for the management of users, roles, and analysis configurations. The QVscribe clients connect to QTS via HTTPS and information flows both ways between clients and QTS.

QTS serves two basic functions

  1. QVscribe Licensing 

  2. QVscribe Analysis Configuration sharing and storage

The System Environment

How does one use QTS?

There are two main ways to interact with QTS:

 

Prerequisites for installation of QVscribe Team Server (QTS)

Below lists the prerequisites for installing QTS. If you have any further questions, please contact support@qracorp.com

Environment

Windows 2012 Server or later

  • Ensure that the server is up-to-date with all latest patches installed
  • Check for updates, install them and restart your machine

System Requirements

  • Processor: 2 * 2 GH x 64 chip
  • RAM: 8GB (12 GB recommended)

Public IP address

  • The IP or hostname must be accessible to the end-users. If end-users are mandated to be on VPN within your networks, then the IP address will be within your LAN. If the end-users are connecting outside of your VPN, then you would need a public IP address.

Browser

Please ensure that Google Chrome (latest edition) is installed on the server. Google Chrome will be needed to open the QVscribe for Teams dashboard.

License Management

Active Directory

If your Team plans to use AD for license management, please ensure the following details are prepared before the installation meeting.

Active Directory credentials for the LDAP form in QTS

Example:

AD User : CN=Administrator,CN=Users,DC=qra,DC=qts, DC=com

AD Password : ******

AD Host and Port : 10.10.42.217:389

Base Domain : DC=qra,DC=qts,DC=com

  • The form would look similar to the image below:

Active Directory Connection Details

Field Description
Username The distinguished name of the user that the application will use when connecting to the directory server.

Examples:
– cn=administrator,cn=users,dc=ad,dc=example,dc=com
– cn=user,dc=domain,dc=name
user@domain.name

The specific privileges required by the user to connect to LDAP are ‘Bind’ and ‘Read’ (user info, group info, group membership, update sequence number, deleted objects), which the user can obtain by being a member of the Active Directory’s built-in administrators group.

Password The password of the user-specified above.

Note: Connecting to an LDAP server requires that this application log in to the server with the username and password configured here. As a result, this password cannot be one-way hashed – it must be recoverable in the context of this application. The password is currently stored in the database with obfuscation. To further guarantee its security, you need to ensure that other processes do not have OS-level read permissions for this application’s database or configuration files.

Host:port The hostname of your directory server and the port on which your directory server is listening.

Examples:
-ad.example.com:389
-ldap.example.com:636 (for example, for SSL)
BaseDN The root distinguished name (DN) to use when running queries against the directory server.

Examples:
– o=example,c=com
– cn=users,dc=ad,dc=example,dc=com

For Microsoft Active Directory, specify the base DN in the following format: dc=domain1,dc=local. You will need to replace the domain1 and local for your specific configuration. Microsoft Server provides a tool called ldp.exe which is useful for finding out and configuring the LDAP structure.

SSL Check this if the connection to the directory server is an SSL (Secure Sockets Layer) connection. Note that you will need to configure an SSL certificate in order to use this setting

 

Non-AD

If your Team does not plan to use AD, the QTS server gives the QVscribe admin the ability to create a username and password for any users to use when using QVscribe on their computer.

The QVscribe admin will be responsible for the distribution and maintenance of these usernames and passwords.

 

 

Installation

QVscribe for Teams Server Installation

All download information and license will be provided to you and your team prior to installation.

You will receive the following items as part of your download package:

  1. QVscribe for Teams download file

  2. PostgreSQL 10.4.-1

  3. External Properties file

  4. License Key 

  5. QVscribe Client download file(s)

Creating Folder for all QTS Artifacts

All files sent to you should be copied and save the folder on your C drive. We usually suggest C:qts.

Validating Windows

Ensure you have a validated Windows edition: Windows Server 2012 R2 or above is required.

Installing PostgreSQL

Your next step is to install PostgreSQL Version 10 or above from PostgreSQL Global Development Group:

1. You can find the download file for PostgresSQL in your google drive folder provided by QRA Corp.

2. On the Select Components page, please unclick Stack Builders.

3. Fill out the following credentials during the download:

Username: postgres Port: 5432

4. Enter your created PostgreSQL password details in the external.properties file

Please note that the external.properties file is used for externalizing QTS instance-specific information necessary for it to function in different environments. At Service start up the configuration details contained in this file are applied in the initialization of the application. The particular values configured in this file need to be provided by the user in order for QTS to work as expected. 

Contents of this file by default are:

server.port.http= 8080*

server.port=8443*

server.ssl.key-store = file:c:/qts/yours.jks*

server.ssl.key-store-password = password*

server.ssl.key-password = keypairpass*

server.ssl.key-alias=solid*

postgresEnabled = true*

postgresUrl=jdbc:postgresql://127.0.0.1:5432/postgres*

postgresUsername=postgres*

postgresPassword=password*

Please be sure to update all details within the external properties file with your specific information before starting QTS.  Failures in the service successfully starting are often due to misconfiguration in this file so it is important to take care in setting them. Changing these values and restarting the service will reapply any changes made.

Installing QVscribe for Teams Server

Your next step is to run the QVscribe for Teams installer which you can find in your google drive folder provided by QRA Corp.

1. During the setup, ensure you select the folder you created in your C drive for your logs and your external properties. C:qtslogs

2. When the installation completes, the installer will automatically open a browser window and navigate to the localhost for you.

Please note: the browser opened will be the default browser on your machine. However, it is recommended to ensure QVscribe Team Server is accessed via Google Chrome to avoid any issues.

3. Please wait for QVscribe Team Server service to launch. Wait approx. 30 seconds before refreshing the page on the browser to bring up QTS. The QTS launch time may vary depending on the machine.

4. Set the QVscribe admin username and password and use the license key sent to you to initialize the server on startup. The key will create a request file.  

Please send the request file to support@qracorp.com.  The request file is a secure key that node locks the QVscribe for Teams license to your server. 

We suggest completing the installation during a call with us so we can send over the license to you on the call, and complete the installation right away.  Once you have the license file, you can login.

Once you have set the QVscribe admin username and password and are logged into the QVscribe, you should see the below dashboard.

SSL Certificate in Teams Server

Finding the external.properties file

A custom SSL certificate can be configured through external.properties. The external.properties is input to windows service. This window service and properties file location can be found.

  1. Open the Windows menu, type in “services” and select the application.

  2. Choose QTSAuth service

  1. Right-click and select Properties, scroll to find the path of external.properties

Configuring in external.properties file 

To configure the external.properties file, please follow the below steps:

  1. Uncomment the following lines in external.properties by removing the ‘#’ in the line beginnings

    1. #server.ssl.key-store =  <file path for key store file *.jks>

    2. #server.ssl.key-store-password = <key store password>

    3. #server.ssl.key-password =  <keypairpass>

    4. #server.ssl.key-alias= <key alias>

  2.  Complete the entries. 

    1. server.ssl.key-store =  <file path for key store file *.jks> The keystore file can be a jks (java key store) or pfx file. Please ensure the file path uses forward slashes versus backslashes (usually used for Windows paths).

    2. server.ssl.key-store-password = <key store password> Enter the password to open the key store

    3. server.ssl.key-password =  <keypairpass> Enter the key alias in the store

    4. server.ssl.key-alias= <key alias> Enter the password used to protect the key-alias in the store

Example : Trying to open using keystoreexplorer

Example entries once populated : 

server.ssl.key-store =  c:/qts/bdtesting.pfx

server.ssl.key-store-password = password

server.ssl.key-password =  password

server.ssl.key-alias= ssl

3. Restart windows service to restart QTS with new external.properties

a. Open the windows menu, type in “services” and select the application.

b. choose QTSAuth service

c. Restart

4. If the client trust certificate is installed on the local computer CA, opening the QTS dashboard in browser

QTS Dashboard Logs

If you or your team are experiencing errors or unexpected behavior with the Teams Server configurations or license management, please follow the below steps to locate your Log files. These may be useful to QRA engineers to help troubleshoot and find the root cause. It is a 2 step process.

Step 1: Sign in to the QVscribe dashboard, under the Metrics, Click the setting icon and click “Download all Metric Data”. This step can be ignored if you are unable to reach the QVscribe Dashboard.

Step 2 : RDP into Windows server where the QTS is hosted, open up file-explorer, and enter

“%QTS_LOG_PATH%” 

Click Enter.

Select all files, zip and send to support@qracorp.com

License Management

QTS Dashboard Identity Providers

What is an Identity Provider/User Directory?

This is a system entity that creates, maintains, and manages identity information for users while providing authentication services to relying applications.  So in a simple sense, QTS uses Identity providers for two purposes.

  1. To know a user of the system in order to association roles and license pools to support product functionality/access.

  2. To authenticate users and verify they are valid within the system to access functionality.

The origin of the user is only important in fulfilling these purposes. Beyond that, it treats users in the system equally.

Currently, there are two types of  Identity Providers supported

  1. Internal QTS User Directory: This is installed by default

  2. Active Directory

Adding an Active Directory Identity Provider

Start by Clicking on the “Add Identity Provider” Button

There is a simple 4 step wizard implemented to help guide the user in adding an Active Directory. By completing the 4 steps a QTS Admin will have configured a connection to a particular AD and saved a valid configuration in the QTS system.

 Steps to Setting up Active Directory :

Username

The distinguished name of the user that the application will use when connecting to the directory server.

Examples:
  • cn=administrator,cn=users,dc=ad,dc=example,dc=com

  • cn=user,dc=domain,dc=name

  • user@domain.name

The specific privileges required by the user to connect to LDAP are ‘Bind’ and ‘Read’ (user info, group info, group membership, update sequence number, deleted objects), which the user can obtain by being a member of the Active Directory’s built-in administrators group.

Password

The password of the user-specified above.

Note: Connecting to an LDAP server requires that this application log in to the server with the username and password configured here. As a result, this password cannot be one-way hashed – it must be recoverable in the context of this application. The password is currently stored in the database with obfuscation. To further guarantee its security, you need to ensure that other processes do not have OS-level read permissions for this application’s database or configuration files.

Host:port

The host name of your directory server and the port on which your directory server is listening.

Examples:

BaseDN

The root distinguished name (DN) to use when running queries against the directory server.

Examples:

  • o=example,c=com

  • cn=users,dc=ad,dc=example,dc=com

For Microsoft Active Directory, specify the base DN in the following format: dc=domain1,dc=local. You will need to replace the domain1 and local for your specific configuration. Microsoft Server provides a tool called ldp.exe which is useful for finding out and configuring the the LDAP structure.

SSL

Check this if the connection to the directory server is an SSL (Secure Sockets Layer) connection. Note that you will need to configure an SSL certificate in order to use this setting

Editing an Active Directory Identity Provider

For Active Directory Identity Providers you will see a gear icon on the bottom right of their card.  Click on that and edit the details via the wizard dialog provided.

Removing an Active Directory Identity Provider
Click on the Garbage can of the provider card you wish to remove. After being prompted to confirm this the provider and all associated groups and users will be removed from the system.

Internal QTS User Directory Setup

Since the QTS User Directory is baked into the product there is no configuration required prior to adding users.

Using QTS Identity Providers with the Client

Users can obtain a Licence from QTS when they are given the appropriate privileges, for Users that are using an Active Directory or the Internal QTS Directory they connect to the server in the same location.  From a QVscribe client standpoint, the main difference in experience between these two types of users is that for internal QTS Users they will be prompted with a dialog to enter their credentials.  Active Directory Users will have their credentials automatically determined.   In both cases, the license request will be tied to the particular system by a unique system identifier.

QVscribe Floating Licenses

The number of seats available to a team is decided when QVscribe is purchased, this number can be added to anytime during the term if needed. In QTS, this total number can be divided among one or more Licence Pools. In order for a user to be eligible for a license, they need to be assigned to at least one pool.  In order for a user to obtain a license to access QVScribe, there must be an available license among the pools they are associated with.  Pools allow the admin to reserve a segment of the licenses for a particular individual or group of individuals. 

  • A Licence Pool with no licenses will never give users a license.

  • A Licence Pool with no users but license assignments will prevent them from being assigned.

  • A Licence Pool with one license will give it out in first come first serve fashion.

  • A Licence Pool with one member and a license assigned will ensure that users can always get a license.

A combination of pools and assignments can be set up as the QTS Admin desires to allow for flexibility in how different users obtain a license.

When is a Licence used?

One instance of the available license(license session) is used when a user requests access to QVscribe.  This means all users, regardless of role or origin can use a QVScribe product as long as they are eligible and able to obtain a license session.  Each user can also have parallel Licence sessions (use more than one at a time) if they request access from more than one machine at a time. As long as the user keeps that machine’s session going they will be taking one of the licenses available.

How to manage user sessions in the dashboard?

License Management

When a User receives a license you can see the basic details in the ribbon of the client. 

On Chrome Extension :

On QVscribe Dashboard,  you can see this active session on the Active License Session Tab.

On the Licence Pools tab, you can see the basic information about the pool and related active sessions.

When you click on the rows in the tables you are able to view or edit details around the particular Licence area.

Click on the Licence Pool row:

Clicking the Active Session row:

 

How to edit session duration?

On Active License Sessions Tab, the QVscribe admin has an option to edit the length license session duration as shown below :

Click it, edit and save to define session length after which unless user has an interaction on QVscribe Office or Chrome Extension :

QVscribe Office: If any QVscribe add-on has already obtained a valid license session, the license is automatically renewed unless the user explicitly sign-outs or closes all the office applications with QVscribe installed or goes offline for at least the length of session duration.

Then Signout.

QVscribe Chrome: If the QVscribe extension has already obtained a valid license session, the license is automatically renewed on the navigation of UI elements, during the time between expiry and navigation, another user has an opportunity to take away the license. The user also can explicitly sign out to pass the license back to the QTS pool.

Explicit signout from chrome extension on user setting tab : 

Then Signout :

QTS Dashboard License Pools

The QVscribe Teams Servers provides the ability to create license pools for managing your licenses.  This can be helpful for one of the following scenarios:

  1. To split licenses into groups for different departments or teams.  This means that different groups can purchase their own seats without having to set up a new QVscribe server.

  2. To ensure a seat is always available. You can create pools to help manage the usage of seats. If one or two individuals need a license at all times, you can create a license pool just for those specific users.

  3. To increase the chance that a certain set of users has access to a seat, you can add certain users to multiple pools.

Alternatively, you can create 1 license pool to hold all your seats. You have the ability to change this if or when necessary.

The QVscribe License Pools section can be found on the QTS dashboard, under License Management.

Managing License Pools

Select ADD LICENSE POOL to create your license pool or pools

To make changes to your license pool seats number, you can select the blue icon beside Active Licenses, and directly make the changes on the dashboard. Once completed, select the blue icon to accept your changes.

Adding Users to a License Pool (non-AD)

To a user to a license pool, select ADD USER under the User Management.

Step 4 of adding a user will ask for the license pool details.

You can also make changes to an existing user, by selecting the user directly in the User Management section. You can then select EDIT at the bottom right corner to make changes to the user, including changing their license pool.

Adding AD groups to a License Pool

Under User Management, select Identity Providers and then select See Users & Groups under your AD directory.

This will bring you to another screen, where you can add a new user group or edit an existing group.

To add a group, please select ADD USER GROUP on the right.

Step 3 will ask for a License Pool.

You can also make changes to an existing group, by selecting the group directly in the Groups section. You can then select EDIT at the bottom right corner to make changes to the user, including changing the license pool.

QVscribe Teams Server Groups

There are three types of user groups:

  1. Configuration Authors

  2. Authors

  3. QVscribe Admin

—–

Configuration Authors would have access to made changes to the QVscribe Configuration window. This gives the user access to add, edit and remove trigger words, and units.

The user would also have the ability to save and delete configurations (that all users – authors and configuration authors) will have access to use.

Authors would only have the ability to select a configuration to use.  They cannot edit, delete, or add any changes to the configuration.

QVscribe Admins will have access to the QVscribe for Teams dashboard, where they can edit license management, license pools, and sessions. We suggest having at least 2 individuals designated with this access. These users can also be authors or configurations authors, they do not need to be solely Tenant Admin

These users will be created directly on the QVscribe for Teams dashboard.

Adding Users 

In order to add users to the system, there are two current paths a QVscribe Admin can take

  1. Add to the Internal QTS User Directory

  2. Add from a configured Active Directory

Of the two options, the first is the quickest for getting the system up and running. Adding users from Active Directory takes more upfront configuration/knowledge to get a working round trip environment.  

 

Easy Approach to Requirements Syntax (EARS)

EARS Templates

Available to those who have QVscribe for Teams, QVscribe provides assistance to authors of requirements based on the Easy Approach to Requirements Syntax (EARS), with both EARS templates and a conformance check against these EARS templates.

Within the QVscribe ribbon, QVscribe for Teams users will have access to an EARS templates button. When you want to author a requirement, you have the ability to select an appropriate EARS template from the list.

When a template is selected it will appear at the cursor location on the document. See example below.

You can then easily fill in the areas in the template to create a well-structured requirement.

All 12 EARS templates are described in detail below.

EARS Type

Description

Template

Event-driven

An Event-driven requirement is activated when a triggering event is detected at the system boundary

WHEN <trigger> the <system name> shall <system response>

Option

An Option requirement is used for systems that include a particular feature

WHERE <feature is included> the <system name> shall <system response>

State-driven

A State-driven requirement is active while some pre-condition remains true

WHILE <pre-condition> the <system name> shall <system response>

Ubiquitous

A Ubiquitous requirement is continually active

The <system name> shall <system response>

Unwanted behaviour

An Unwanted Behaviour requirement defines the required system response to an unwanted external event

IF <trigger> THEN the <system name> shall <system response>

Complex

A Complex requirement contains a combination of the basic EARS patterns

See table 3 below

Complex EARS Template

Label

WHERE <feature is included> WHILE <pre-condition> IF <trigger> THEN the <system name> shall <system response>

Optional feature, state-driven, and unwanted-behaviour

WHERE <feature is included> WHILE <pre-condition> WHEN <trigger> the <system name> shall <system response>

Optional feature, state-driven, and event-driven

WHERE <feature is included> WHILE <pre-condition> the <system name> shall <system response>

Optional feature, and state-driven

WHERE <feature is included> WHEN <trigger> the <system name> shall <system response>

Optional feature, and event-driven

WHERE <feature is included> IF <trigger> THEN the <system name> shall <system response>

Optional feature, and unwanted-behaviour

WHILE <pre-condition> IF <trigger> THEN the <system name> shall <system response>

State-driven, and unwanted-behaviour

WHILE <feature is included> WHEN <trigger> the <system name> shall <system response>

State-driven, and event-driven

EARS Template Conformance

In conjunction with EARS templates, QVscribe can automatically check how closely requirements conform with EARS templates. This helps you assess if the requirements have good structures or if the requirements need to be clarified and further structured.

When you click and expand a requirement in the analysis window, you will also see information on EARS conformance. You will see either a drop-down stating EARS – ‘Template type’, Non-conforming, which means that the requirement does not conform with any EARS templates, or you will see EARS – ‘Template type’, describing which template this requirement conforms to along with what parts of the requirement correspond to the different elements of that EARS type structure.

To include EARS conformance check in the quality analysis of your requirement, just check the “Include in Analysis” box in the Templates tab of the Configuration window.

If the EARS conformance check does not align with your needs or approaches, you can un-check the “Include in Analysis” box in the Templates tab to turn this feature off from your analysis.

Note: The EARS templates and conformance checking features are only available for users with QVscribe for Teams.