Introduction

Purpose

This document provides a technical system overview of VERA version 2.0 or higher for Micro Focus ALM.
This document is not intended to provide a detailed configuration specification of the ALM template, nor is it intended to describe the design of any other software components in the VERA application architecture.

Definitions

The following terms are used throughout this document:

Overview

VERA is deployed as a project template extending ALM core functionality to enable test management in a controlled, validated environment. VERA implements electronic signatures, customer-defined procedures, and business rules via ALM's scripting and programming capabilities.

Tx3 VERA is an enterprise application that enforces shared business policies pertaining to the control of electronic records across multiple systems. Using VERA, an organization can define one or more policies describing the types of electronic records the organization maintains, along with business rules describing the expected user access permissions, electronic workflows, and electronic approval rules for each type of record. These policies can then be enforced across all the organization's information systems that are integrated with VERA.

The VERA ALM Template is a template project for the ALM application that functions as a system adapter between Tx3 VERA and ALM. The template provides customized workflow script that enforces VERA records management, approval, and notification policies within ALM. It also provides an integration point between the two applications that enables users to access VERA features for electronic records stored within ALM.

High-level Software Architecture

The VERA client contains the VERA user interface and library files to support:

• Controlling record creation based on user permissions
• Controlling record and field modifications based on user permissions and record status
• Controlling record deletion based on user permissions and record status
• Transitioning record status and requiring fields on status transition
• Routing records for approval and assigning approval tasks
• Approving and signing electronic records
• Rejecting records and capturing rejection reason
• Reassigning approval tasks
• Withdrawing approval routes
• Revising records and capturing revision reason
• Copying records and resetting the status, revision, and signature fields on the copy

The VERA Policy files allow for the configuration of business rules, approval routes and notifications.

ALM template projects provide a mechanism for maintaining and deploying ALM project configurations across multiple projects within an enterprise. VERA is concerned with the following categories of configurations:

• User groups and permissions
• Fields
• Lists of values
• Requirement types
• Workflow script

The workflow script is the most important configuration item, as it provides the integration point between the two systems. The workflow script in the VERA ALM template is customized to do the following:

• Load configured VERA policies
• Enforce the VERA policies within the ALM project
• Launch the VERA application with an initialized context for the selected record(s) in ALM.

Figure: Technical Architecture

Integrating with the VERA Windows Client

The VERA ALM Template integrates with the VERA Windows client, which is a locally installed application comprised of a collection of Microsoft .NET library files (.dll).

In this implementation, the configured VERA policies are stored directly inside each ALM project as JSON files in the ALM requirements module. When a user logs in to their VERA-enabled project, the ALM workflow script will locate the policy files and load their contents into memory. The rules contained within the policies can then be enforced by the workflow script as the user continues to work within the project.

The user can access the VERA application by pressing a configured toolbar button in the ALM project. The toolbar button exists in all ALM modules in which VERA functionality is supported. When the user selects to open VERA, the workflow script will create a new VERA instance from the VERA ALM Adapter library of the VERA Windows client. The workflow script will provide to VERA the currently configured policy information, as well as context information about the currently selected record(s) in ALM.

The VERA Windows client will then load and display a context-sensitive menu of available actions to the user. While VERA is open, the VERA client will continue to run in the foreground, and the ALM application window (web browser) will be blocked. The VERA application will automatically close and return control to ALM after the user's activity has completed, or after the user has cancelled their operation.

Figure: VERA integration flow

Records Management Policy

Description

The VERA Records Management Policy is a data model that is used to represent a configured set of business rules that will be shared by software components within the VERA application architecture.

The VERA Records Management Policy data model consists of two basic data elements: a list of defined record types and a list of defined actions that can be tailored to meet business requirements.

Loading the Policy

VERA-configured projects in ALM must contain a VERA Records Management Policy. The records management policy must be stored in a JSON file attached to the root requirement folder in the ALM Requirements Module. The file must be named: Records Management Policy.json.

When a user logs in to the ALM project, the ALM workflow script will locate the records management policy file and load its rules into memory. The CanLogin event hook of the ALM workflow script is used to trigger this process. The loaded policy rules will then be enforced throughout the user's login session as subsequent workflow events are triggered.

If the file cannot be found—or if there is any error while parsing the file as a JSON document—then an error message will be displayed to the user, and the project will operate as though no policy rules have been configured. This will result in the user having no permissions to create, edit, or delete any electronic records that are controlled by VERA. That is, the user will be forced to work in a "read-only" mode.

During login is the only time at which the records management policy file will be read by the workflow script. Therefore, if the policy file changes while the user is logged in, the updated rules will not be enforced until they log out or their current session expires and they are forced to login again.

Policy File Security

ALM project administrators are the only users that have permission to modify the attachments of the root requirement folder in the ALM requirements module. ALM project administrators are defined as the users assigned to the TDAdmin user group in each ALM project. This restriction prevents any other users from being able to modify or replace a project's configured policy rules.

This rule must be enforced directly by the workflow script without requiring a records management policy to be loaded. It is imperative that project administrators have access to add, remove, and modify policy files, regardless of project configuration. Otherwise, the administrators would not be able to troubleshoot and repair issues with missing or improperly configured policy files.

Item Types

The following table shows all item types provided by the ALM workflow engine and identifies which item types are controlled by VERA's custom workflow script:

The item types recognized by VERA can be referenced in a Record TypeDefinitionItem Types element of a records management policy by using the corresponding item type name listed above.

User Permissions

User permissions are controlled through user groups defined in the ALM template configurations. Role names referenced in the records management policy should correspond with the name of an ALM user group. For example, if a Record TypeEditors element within a records management policy references a role named Business Analyst, then the custom VERA workflow script will automatically attempt to associate that role with a group named Business Analyst in the ALM template. All users assigned to the Business Analyst user group will have the records management policy permissions defined for the Business Analyst role.

It is not required that all roles referenced by the policy are represented by configured user groups. If a user group cannot be found, then the workflow script will operate as though no users are assigned to the corresponding role. An error condition will not be raised.

Field Editability

ALM workflow script is used to control field editability. When event hooks are triggered, the workflow script will identify the relevant policy rules for the current record, and then set the editability of all fields in the record based on those rules.

Action Execution Permissions

Action execution permissions are controlled by mapping the various action names used by the ALM workflow engine into the basic action categories recognized by VERA. For example, the ALM action named Defects.NewDefect is mapped into the Create action category of VERA because it represents creating a new record. Likewise, the ALM action named Attachment.Rename is mapped into the Edit Attachment action category of VERA because it represents editing an attachment.

The ActionCanExecute event hook of the ALM workflow script is used to control action execution permissions. When the event is triggered, the custom VERA workflow script will first convert the specified ALM action name into its corresponding VERA action category using hard-coded look-ups. The workflow script then references the records management policy rules to determine if the current user has permission to execute the action category on the associated record type.

Always Allowed Actions

Some ALM action names are hard-coded in the custom VERA workflow script as actions that are always permitted to be executed. These actions are not mapped into any VERA action category, and are instead automatically granted permission to be executed, regardless of current context or current user permissions.

This category of action is used for non-destructive actions that will not result in the creation, modification, or removal of an electronic record. Pressing the Refresh button in the toolbar or selecting to view the details of a record are examples of actions that are always permitted to be executed.

Never Allowed Actions

Some ALM action names are hard-coded in the custom VERA workflow script as actions that are never permitted to be executed. Just as with always-allowed actions, these actions are not mapped into any VERA action category. Instead the actions are automatically denied permission to be executed, regardless of current context or current user permissions.

This category of action is typically used for ALM actions that will open dialog windows in which the VERA custom workflow script has no control over user actions and field editability. For example, the RequirementImpactAnalysis.ReqDetail action will open a Requirements Details dialog in which the fields will always be editable without regard to the workflow customizations.

Create Actions

Actions in the Create action category require special handling because their permissions are defined on a per-record-type-basis, but there is no specific record in context when the action permissions are evaluated. For example, if a records management policy defines several different record types that map to the Requirement item type in ALM, when the user selects to create a new requirement the workflow script does not yet know which type of requirement the user is trying to create.
The VERA custom workflow script provides the following extra handling to control the creation of new records:

1. When a user selects to create a new record within ALM, the workflow script determines if the user has permission to create any record type of the corresponding item type. For example, if a user presses the New Requirement button in ALM, then the workflow script will verify if the user has permission to create any type of requirement. If the user can create at least one type of requirement the action is permitted. If the user cannot create any type of requirement the action is denied.
2. The VERA custom workflow script uses the FieldCanChange event hooks to ensure that as the user does not select field values that correspond to a record type that the user does not have permission to Create. For example, if the user is populating the fields of a requirement record and they select a Requirement Type of Functional, the workflow script will verify if they have permission to create a functional requirement.
3. Finally, the VERA custom workflow script uses the CanPost event hooks to ensure that the final configuration of the record matches what the user is permitted to create before allowing the record to be saved to the database.

Delete Actions

Actions in the Delete action category are always prohibited in the VERA ALM template regardless of the current records management policy configuration. Anytime a user invokes a delete command on an entity in ALM, the workflow will display a message instructing the user to use the VERA Smart Delete feature instead.

Duplicate (Copy) Actions

As with the Delete action category, actions in the Duplicate action category are always prohibited in the VERA ALM template, regardless of the current records management policy configuration. Anytime a user invokes a copy command on an entity in ALM, the workflow will display a message instructing the user to use the VERA Smart Copy feature instead.

Edit Link Actions

A records management policy will typically specify linking rules based (at least in part) on user group membership and the record type of each record on either side of the link.

However, the ALM workflow engine has a limitation in that the workflow script is unable to determine which specific record exists at the other end of a linking operation. Therefore, it is impossible for the VERA workflow script to properly control linking actions based on target record type.

Instead, the VERA workflow script is designed to infer the ALM item type of the target linking record based on the ALM action name. For example, the action named 'ReqCoverageReqEntitySelection.AddSingleReq' is known to represent adding a requirement link to another record, and therefore it is known to be associated with the requirement item type. The workflow script will then determine if the target record type specified by the records management policy is associated with the ALM item type. If it is, the rule is assumed to be satisfied.

This implementation represents a limitation of controlling actions within ALM. It is possible for a user to be able to establish a link between two record types in ALM that would normally be prohibited by the VERA records management policy, assuming an ALM item type corresponds with multiple record types in the given records management policy. For example, assuming the records management policy only permits linkage between test cases and functional requirements, when the user selects to add requirement coverage to a test, the workflow script will not be able to control which types of requirements can be added.

Special Rule: "Add and Link Defect" Feature

ALM has a feature named Add and Link Defect that allows users to create a new defect and automatically link it to the selected record. This feature requires special handling by the VERA workflow script to ensure that the current user has permission to both create defects and link them to the current record type. Therefore, when the user selects the Add and Link Defect feature, the workflow script will first verify that they have permission for the Edit Link action of the selected record. If they do have permission, the workflow script will next verify that the user has permission for the Create action for any record type associated with the Defect item type. If that permission check succeeds the Add and Link feature is permitted.

Error Messages

The workflow script should attempt to provide useful error messages to the user when an action is prevented from execution. The following rules are used to determine the type of error message to display:

1. If an action is explicitly prohibited by a workflow state exception, then the user should be informed that the action is not allowed in the current workflow state.
2. If an action is explicitly prohibited by an action execution rule based on user permissions, then the user should be informed that they do not have permission to execute the action.
3. If an action is explicitly prohibited by an action execution rule based on other, then the user should be informed that they do not have permission to execute the action with a summary of the constraints prohibiting the action.
4. If an action is prohibited because there are no special rules defined and the user is not an Editor, then the user should be informed that they do not have permission to execute the action.
5. If an action is prohibited because there are no special rules defined and the current workflow state is not editable, then the user should be informed that the action is not allowed in the current workflow state.
6. If an action is prohibited because any special rules are not relevant in the current workflow state, then the user should be informed that the action is not allowed in the current workflow state.

Notification Policy

The VERA Notification Policy is a data model that is used to represent a configured set of business rules pertaining to the notification of approval tasks that will be shared by software components within the VERA application architecture. VERA-configured projects in ALM must contain a VERA Notification Policy. The notification policy must be stored in a JSON file attached to the root requirement folder in the ALM Requirements Module. The file must be named: Notification Policy.json.

The Notification Policy allows you to enable or disable VERA Approval task notifications and approval route notifications as well as configure the email subject and body. The following email notifications are configurable:

• Route Completed – sent to record owner when an approval route is complete record is approved
• Route Rejected – sent to record owner when an approval route is rejected
• Task Cancelled – sent to pending approvers when an approval task is rejected or reassigned
• Task Withdrawn – sent to pending approvers when an approval task is withdrawn
• Task Assigned – sent to pending approvers when assigned to approval task either by approval route or by reassignment of an approval task

Approval Policy

The VERA Approval Policy is a data model that is used to represent a configured set of business rules pertaining to the approval of electronic records that will be shared by software components within the VERA application architecture. VERA-configured projects in ALM must contain a VERA Approval Policy. The approval policy must be stored in a JSON file attached to the root requirement folder in the ALM Requirements Module. The file must be named: Approval Policy.json.

The VERA Approval Policy data model consists of two basic data elements: a list of defined approval roles and a list of defined route templates.
Approval Routes can be created, modified, or deleted to meet business needs. Below are some examples of approval routes:

For each defined route template, the data model provides a name and all the following:

• A rank: A number indicating the hierarchical precedence of the route template in comparison with other templates. Lower numbers have higher precedence.
• A list of record types: The types of records for which the policy may be enforced. These record types should correspond with types defined by the records management policy.
• A list of approval levels: A listing of sequenced approval task groups. Tasks within a level (group) may be completed in any order, but all tasks in a given level must be completed before any tasks in the next level may be started.
• A list of selection rules (optional): Template-specific rules that determine when the route template should be used (e.g. based on certain field values)

{
  "Approval Policy":
  {
    "Version": "0.0.0.4",
    "Approval Groups": [
      "Business",
      "Process Owner",
      "Quality",
      "System Owner",
      "Technical",
      "Validation"
    ],
    "Route Templates": [
      {
        "Name": "GxP Approval: System Tests",
        "Rank": "1",
        "Record Types":["Test Case"],
        "Levels":[
          {
            "Name": "Level 1",
            "Approvers":["Content Originator"]
          },
          {
            "Name": "Level 2",
            "Approvers":["Business"]
          },
          {
            "Name": "Level 3",
            "Approvers":["Quality"]
          }
        ],
        "Constraints":[
          {
            "Type": "Field Is One Of",
            "Name": "GxP",
            "Values": ["Y"]
          },
          {
            "Type": "Field Is One Of",
            "Name": "Category",
            "Values":["System"]
          }
        ]
      }
    ]
  }
}

Figure: Sample Approval Policy in JSON format

VERA Client

The VERA Windows client is a locally installed application comprised of a collection of Microsoft .NET library files (.dll).

Launching the VERA Action Menu

The VERA Action Menu is launched through the button in a VERA-enabled module. The action called by the button is UserDefinedActions.VERA_Action_Menu. The Common Workflow script calls the appropriate module-based script and ActionCanExecute function. The VERA Action Menu is populated with actions based on the current user permissions. Buttons are enabled or disabled based on the selected entity status and the selected entity's children constraints such as status and/or field value.

Figure: VERA Action Menu

Viewing Version Information

Once the VERA Action Menu has been launched, the Version Information can be displayed by clicking the Version Information link in the lower left-hand corner of the Action Menu window. The Records Management Policy version is generated from the policy JSON, the Script version is passed in through the Initialization of the VERA Action Menu, and the Software Component version numbers are loaded from the assemblies loaded in memory when the Action Menu is launched.

Figure: VERA Version Information

Applying Electronic Signatures

When an electronic signature is applied to an entity, VERA builds a signature record based on information contained within the entity and information from the user and system. The following information is collected about the entity being signed:

• Name
• Record Type
• ID
• URL
• A Hash of the record's defined data fields (See Note Below)

The signature is also composed of the following user and system content:

• User Name
• User ID
• Signature Meaning
• Signature Time Stamp
• Record Location
• Signature Full Text

The user, system and record information is then collected into a Signature Components object. This object is also hashed to provide the ability to verify the signature integrity. After the information is collected and hashed, the system will save the plain text signature in the Signatures field and the full signature information (in JSON format) in the Signatures (Raw) field. The Signatures (Raw) field is hidden in projects and should not be cleared.

VERA ALM Template

The VERA ALM Template is a template project that functions as a system adapter between Tx3 VERA and ALM. The template contains user groups, fields, lists, requirement types, and workflow script.

User groups and permissions

User permissions are controlled through user groups defined in the ALM template configuration. Role names referenced in the records management policy should correspond with the name of an ALM user group.
ALM User Groups are configurable and can be modified in concert with the Records Management Policy and Approval Policy to meet business needs. The following ALM Groups are recommended for VERA.

Blacklisted Groups

The following groups cannot be used in ALM VERA projects. User login is prevented if you are a member of one or more of these groups unless you are also member of the TDAdmin group.

• Developer
• Project Manager
• QATester

Fields

VERA requires the following ALM fields to function.

The VERA ALM Template contains additional fields to support the Standard Records Management Policy. The field labels are configurable.
Requirement Types that do not require approval do not require the fields listed above.

Audit Log

Fields in the VERA ALM Template have History enabled to utilize ALM Audit Log.

Lists

ALM Project Lists are configurable and can be modified in concert with the Records Management Policy and Approval Policy to meet business needs.

Requirement types

ALM Requirement Types are configurable and can be modified in concert with the Records Management Policy and Approval Policy to meet business needs.

Workflow script

The template provides customized workflow script that enforces VERA records management, approval, and notification policies within ALM. It also provides an integration point between the two applications that enables users to access VERA features for electronic records stored within ALM.

Figure: VERA ALM Workflow integration

Document ID: Tx3.1022.SPC.003
Document Version: 01
Date Issued: 16 OCT 2017