QVscribe Application Server

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

Prerequisites

QVscribe for Teams Overview

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

QVscribe for Teams is composed of:

1. The QVscribe clients for Microsoft Word and Microsoft Excel. The client installers are distributed to all users. This license file installs an MS office control and the QVscribe analysis server on the client machine.

2. The QVscribe Team Server (QTS) for the management of users, roles and analysis configurations.

The diagram below illustrates the components and communication that form QVscribe for Teams:

The QVscribe clients install as add-ins in Microsoft Word or Excel and connect with the QVscribe Analyzer on the same client machine:

  • The QVscribe Team Server (QTS) is installed in a centralized server for 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 connects to the Identity Provider (Active Directory) for read-only access to the user directory. This allows QTS tenants to provide QVscribe seats based on users within their Active Directory.

Prerequisites for installation of QVscribe Team Server (QTS)

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

Environment: Ensure that the server is up to date with all latest patches installed (Windows 2012 Server or later).

1. Check for updates

2. Install all updates

3. Restart your machine

Browser: Install Google Chrome latest edition

Directory service: Active Directory 2012 Schema Version 69

  • In order to connect QTS to the In-House Active Directory (AD), gather the following details:

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:

Create two QVscribe user groups in AD

  • The main group is the Authors group who will be using QVscribe to analyze their requirements

  • Create a Group called Authors’ and add say 5 users to that group

    • A secondary group which is a subset of the Authors group called as Configuration Authors, these are the users who will manage how requirement analysis is performed

  • Create a Group called ‘ConfigurationAuthors’ and add one among the 5 users to this group.

    • One user will belong to both the groups and the remaining 4 users shall belong to only ‘Authors’ group

Installation

QVscribe for Teams Server Installation

All download information and licenses files will be provided to you and your team in a google drive folder (or alternative source if necessary).

Creating Folder for all QTS Artifacts

All files from your Google Drive folder should be copied and save the folder on your C drive. We usually suggest C:qts.

Create the following subfolders:

· Configuration

· License (add your license properties file to this folder)

· Logs

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. Fill out the following credentials during the download:

Username: postgres Port: 5432

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

Installing QVscribe for Teams Server

Your next step is the 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 tenant admin username and password and use the licence.properties file provided to you to initialize the server on startup.

Activating QVscribe for Teams

The diagram below illustrates the components and communication that form QVscribe for Teams:

The QVscribe clients install as add-ins in Microsoft Word or Excel and connect with the QVscribe Analyzer on the same client machine.

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 connects to the Identity Provider (Active Directory) for read-only access to the user directory. This allows QTS tenants to provide QVscribe seats based on users within their Active Directory.

Setup of QTS with external Identity Provider

In order to connect QTS to the In-House Active Directory (AD), gather the following details:

Active Directory credentials in LDAP form

(QTS > Identity Provider > EDIT & TEST).

Example:

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

AD Password : ******

AD Host and Port : 10.10.42.217:389

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

Optionally, if your AD requires SSL, obtain a certificate and add it to a Java Key store. A Java key store can be created as shown in the following example:

Example: “cacertschange” file in Examples folder.

Note: Keystore password and alias are irrelevant for this connection only

Once Active Directory credentials are entered, click on Test to validate the connection and if the connection is successful Save the configuration.

You will need at least 2 groups in AD to use with QVscribe for Teams:

  1. One group (or more) will be the users that will use the QVscribe clients. These users will each need a QVscribe seat allocated to them within QTS. In the example below, we call this the “QVscribe_authors” group.

The second group will be a subset of users from the regular user group(s) who have elevated privileges as configuration administrators. These configuration administrators are able to modify and publish shared Analysis Configurations to QTS that users in the other group(s) can then access. In the example below, we call this the “QVscribe_ConfigAdmins” group.

SSL Cert

If you would like to optionally provide the QTS admin pages above using your company’s certificate, gather the certificate details to be added to a java keystore (could be same as the one you added the AD cert in). A self-signed certificate (p12 file) is in the Examples folder, the folder "SSLExampleCertjks" shows the process and the assets used to generate the "example.jks"

(The folder “SSLExampleCertjks” shows the process and the assets used to generate the “example.jks”)

This is will be entered into an external.properties file at a later step:

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

server.ssl.key-store-password = ExamplePassword

server.ssl.key-password = keypairpass

server.ssl.key-alias=solid

External.properties (This is step 3.3 in readme file)

Create this file which has deployment-specific properties related to SSL and Couchbase

Example: external.properties file in the examples folder.

Set properties for connection to PostgreSQL server and ssl dependencies in an external properties file ( q this file will be referenced during installation)

Create an artifacts folder like C:qts

Drop external properties files and the keystore files here

Configure AD and License seats in QTS:

Use the information collected in “Gather following details for QTS to integrate with local Active Directory(AD)“

QVscribe for Teams Installation of the Office Client

Once the QVscribe for Teams Server has been set up. The following files and information need to be provided to all QVscribe users:

  1. QVscribe download files. These are provided in the Google drive folder, under the QVscribe Office Client. QVscribeForExcelInstaller_vX_X_X.exe / QVscribeForWordInstaller_vX_X_X.exe

  2. QVscribe for Word and QVscribe for Excel user guides. These are provided in the Google drive folder, under the QVscribe Office Client. QVscribeWord_user_guide_v_X_X.pdf / QVscribeExcel_user_guide_v_X_X.pd

  3. The QVscribe for Teams Server IP or Hostname

Prerequisites

The QVscribe for Word and Excel add-in have the following prerequisites for installation:

  • PC that can be signed into with AD credentials of a user in group 1.

  • Microsoft Windows version 7, 8.1, or 10 operating system

  • Microsoft Office version 2010, 2013, or 2016

  • Visual Studio 2010 Tools for Office Runtime, and Visual C++ 2010 Runtime *

  • QVscribeFor[Word/Excel]_[version].exe installer files

*Note: The installer will automatically determine if these Runtime Environments are present in your system and if necessary, it will ask to download and install them prior to the QVscribe installation

Installation

All QVscribe users should follow the below steps when first logging into their QVscribe client. For a detailed breakdown of QVscribe for Word/ QVscribe for Excel installation steps, features, etc.

Please refer to QVscribeWord_user_guide_v_2_10 and QVscribeExcel_user_guide_v_2_10.

Step 1: Install clients

  • Sign in to the client PC using the AD credentials.

  • Save and run the QVscribe installer file in the client machine. This will first run a dependency checker to ensure your system has everything it needs to run the version of QVscribe and install any pre-requisite packages. Follow the on-screen instructions.

  • Once the QVscribe installation wizard finishes, you will need to close and restart all Word and Excel instances to finish the installation.

Step 2: Open Microsoft Office application

Step 3: Press QVscribe tab on the ribbon

Step 4: On the first use a QVscribe Intro box will pop-up with options to choose between QVscribe for Individuals OR Teams; select Teams

Step 5: Enter QTS hostname, applicable port number and Connect to the Teams Server

Step 6: Once the Server is validated, click on Continue to validate the license, receive a token to use QVscribe and Start QVscribe Add-In

Active Directory

QTS setup of external Identify Provider

In order to connect QTS to the In-House Active Directory (AD), gather the following details:

Active Directory credentials in LDAP form

In QTS, go to “Identity Provider” and click on “EDIT & TEST”.

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

Optionally , if your AD requires SSL, obtain a certificate and add it to a Java Key store. A Java key store can be created as shown in the following example:

Example : “cacertschange” file in Examples folder.

Note : Keystore password and alias are irrelevant for this connection only

Once Active Directory credentials are entered, click on Test to validate the connection and if the connection is successful Save the configuration.

Active Directory Groups

You will need at least 2 groups in AD to use with QVscribe for Teams:

1. One group (or more) will be the users that will use the QVscribe clients. These users will each need a QVscribe seat allocated to them within QTS. In the example below we call this the “Authors” group.

2. The second group will be a subset of users from the regular user group(s) who have elevated privileges as configuration administrators. These configuration administrators can modify and publish shared Analysis Configurations to QTS that users in the other group(s) can then access. In the example above we call this the “ConfigurationAuthors” group.

SSL Certificate

If you would like to optionally provide the QTS admin pages above using your company’s certificate, gather the certificate details to be added to a java keystore (could be same as the one you added the AD cert in). A self-signed certificate (p12 file) is in the Examples folder, the folder "SSLExampleCertjks" shows the process and the assets used to generate the "kishorestore.jks"

(The folder“SSLExampleCertjks”shows the process and the assets used to generate the“example.jks”)

This is will be entered into an external.properties file at a later step:

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

server.ssl.key-store-password = ExamplePassword

server.ssl.key-password = keypairpass

server.ssl.key-alias=solid

You should then update all SSL dependencies in your external.properties file.

Adding Groups and Users to QVscribe for Teams Server

When setting up Groups, you will need at least 2 groups in AD to use with QVscribe for Teams (QTS):

1. One group (or more) will be the users that will use the QVscribe clients. These users will each need a QVscribe seat allocated to them within QTS. We call this the Author group.

2. The second group will be a subset of users from the regular user group(s) who have elevated privileges as configuration administrators. These configuration administrators can modify and publish shared Analysis Configurations to QTS that users in the other group(s) can then access. We call this the Configuration Author group.

Adding Groups, user and adjusting Seats

To add groups, select the ADD GROUP button, and search for the specific group and select the permissions (Author or Configuration Author).

To add a user as a Tenant Admin User, select the ADD USER button, and fill in the Username/Email and password of the user.

To adjust your seat numbers, click on the blue icon beside seats.

You can adjust the numbers directly, besides the groups. When in edit mode, the seats will be underlined.

Once you have adjusted your seat numbers, click on the blue icon again to confirm your adjustments.

QVscribe for Teams Group Roles

Within the QVscribe for Teams Server (QTS), there are 2 distinct groups in terms of roles:

  1. Tenant admin role is only applicable for QTS dashboard (browser).

  2. Author and Configuration Author roles are applicable only for Word and Excel clients.

Tenant admins have the privilege of using QTS dashboard, they can do following jobs using QTS web dashboard:

  • Adding/removing tenant admins(up to maximum 3).

  • Assigning roles of “Author” and “Configuration Author” to the users present in pre-created Active directory groups. Active Directory IT admins manage Active directory groups membership outside of QTS

  • Only the role of “Author” would have the ability to grab a license to use QVscribe in Word or Excel. The groups with “Author” role would need to be allocated a pool of seats.

  • The role of “Configuration Author” augments an “Author”. The “Configuration author” just by itself has no purpose without those users also having “Author” privilege. The users with “Configuration Author” are a subset of users with “Author” privilege.

Note: Email id as user ids is not recommended for tenant admins.

Authors have the privilege of getting a license from QTS to use QVscribe in Word or Excel to do the following jobs:

  • Run QVscribe analysis on their documents

  • Create Reports

Configuration Authors augment Authors to do following additional jobs which require a license to use QVscribe in Word or Excel:

  • Ability to edit/add analysis configurations

  • Ability to publish the analysis configuration for other “authors” to use it for their analysis.  

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.