Set up Requirements Projects

Project Structure

Documents

ReqView projects are organized into one or more documents grouping the same type of project artifacts. For example, high-level stakeholder requirements, system requirements, software requirements, tests, or risk registers.

Each project in your organization should have a unique ID (for example “ReqView”). Also, all documents within a project should have a unique ID (for example “SRS” or “TESTS”).

Document Objects

A document consists of document objects organized into a tree hierarchy with numbered sections, similarly as in a Word document. Document objects are identified by an automatically generated unique ID and consist of a section heading, a rich text description, and a discussion.

For each document, you can define additional custom attributes, thereby extending information about document objects. For example, for requirements you can define a status attribute allowing management of requirements lifecycle.

Traceability Links

A traceability link represents a relationship between document objects stored in the same project. You can define several types of traceability links for a project. For example, “satisfaction” type for links from downstream requirements to the related upstream requirements, “verification” type for links from verification tests to the related requirements, and so forth. It is important to maintain the way of linking to ensure consistent traceability reports.

Example Software Project

The following diagram illustrates the structure of a typical SW development project with two traceability levels:

Level 1 Document:

• STAKEHOLDER REQUIREMENTS — the highest-level user stories formulated using the "As a [type of user], I want [some goal] so that [some reason]" template

Level 2 Documents:

• SW REQUIREMENTS — Software Requirements Specification (SRS) containing detailed downstream software requirements that are derived from the user stories
• VERIFICATION TESTS — test cases verifying specific elements of the SW

Traceability Links Types:

• Satisfy — satisfaction links from SW requirements to stakeholder requirements (M:N)
• Verify — verification links from verification tests to SW requirements (M:N)

Example System Project

The following diagram illustrates the structure of a typical system development project with three traceability levels:

Level 1 Documents:

• RISKS — project risks described using Failure Mode and Effects Analysis (FMEA)
• STAKEHOLDER REQUIREMENTS — the highest-level stakeholder requirements specification
• VALIDATION TESTS — description of system validation procedures and information about validation reports

Level 2 Documents:

• SYSTEM REQUIREMENTS — detailed System Requirements Specification (SyRS)
• VERIFICATION TESTS — description of system verification procedures and the related verification reports

Level 3 Documents:

• SW REQUIREMENTS — Software Requirements Specification (SRS) containing detailed downstream software requirements that are derived from the system requirements
• VERIFICATION TESTS — description of software verification procedures and the related verification reports

Types of Traceability Links:

• Mitigate — mitigation links from system requirements to the related failure modes (M:N)
• Satisfy — satisfaction links from downstream requirements one level up to the original requirements from which they were derived (M:N)
• Validate — validation links from validation procedures to stakeholder requirements (M:N)
• Verify — verifications links from verification procedures to the related software system requirements (M:N)

Project Workspace

ReqView presents structured information about the project and the current document in left panes, a structured table view of the document in the center pane, and detailed information about the selected document object in right panes.

Left Panes:

• Project — shows all the documents in the project and their status, see Organize Documents.

  To toggle it, click View, mouseover Left Panes, and select Project Pane. Or press CtrlAltP.

  It displays by default IDs of all documents. To display also document name in the pane, click Edit, select Preferences, and tick Show document name in Project pane.

• Linked Projects — shows all projects linked to the current project, see Manage Linked Projects.

  To toggle it, click View, mouseover Left Panes, and select Linked Projects Pane. Or press CtrlAltO. The pane is hidden if there is no linked project.

• Document — displays the table of contents of the current document for easy navigation in its structure, see Review Requirements Documents > Document Sections.

  To toggle it, click View, mouseover Left Panes, and select Document Pane. Or press CtrlAltT.

• Table Views — lists table views defined for the current document, see Table Views.

  To toggle it, click View, mouseover Left Panes, and select Table Views Pane. Or press CtrlAltV.

Central Pane:

• Requirements Table — displays content of the current document, other open documents are showed as tabs at the bottom, see Requirements Table.

Right Panes:

• Instructions — displays help text related to the current document object, see Custom Requirement Attributes and Instructions example.

  To toggle it, click View, mouseover Right Panes, and select Instructions Pane. Or press CtrlAltI.

• Attributes — lists the custom attributes of the current document object, see Custom Requirement Attributes.

  To toggle it, click View, mouseover Right Panes, and select Attributes Pane. Or press CtrlAltA.

• Discussion — shows discussion comments related to the current document object, see Control Project Changes.

  To toggle it, click View, mouseover Right Panes, and select Discussion Pane. Or press CtrlAltD.

• Links — shows traceability links related to the current document object, see Requirements Traceability Links.

  To toggle it, click View, mouseover Right Panes, and select Links Pane. Or press CtrlAltL.

• History — shows the history of changes to the current document object, see View Object History.

  To toggle it, click View, mouseover Right Panes, and select History Pane. Or press CtrlAltH.

Project Data Storage

Application Persistency

ReqView application persists user settings and current project data in its secure local storage and restores the project state when it is restarted automatically.

Note: No project data are sent to the Internet unless you explicitly upload your project to Google Drive, collaborate via a Git or Subversion (SVN) repository hosted in cloud, or via Jira Cloud.

File System

You can save the current project on your local or network file system either as a Project Folder or a Project File. The project is saved in JSON format (see ReqView Open File Data Format), the advantage of which is that the data are human readable. You do not need to install any database server. The JSON files can be easily managed in a version control system such as Git or Subversion (SVN).

Project Folders

A Project Folder stores all project data in separate files:

• project.json file stores configuration of project documents and traceability in JSON format.
• documents/ directory stores document files in JSON format using the document ID as the file name.
• attachments/ directory stores attachment files using the attachment ID as the file name.

Example: A sample project folder structure on the file system:

+--- attachments
|       SRS-40_0_Overview.png
+--- documents
|       NEEDS.json
|       SRS.json
|       TESTS.json
\--- project.json

The advantage of Project Folders is that they keep the project documents and attachments separated on the file system. This enables team collaboration by more editors if you store Project Folders on a Shared Drive, or manage them under Git or Subversion (SVN) version control systems.

Note: ReqView Web Application does not support storing projects in Project Folders because it cannot directly access your file system from security reasons.

Project Files

A Project File stores all project data (configuration, document objects, attachments and traceability links) in a single file with .reqw extension so that you can easily send it by email or upload to the cloud. You can also create a project baseline by saving the current project version as a read-only project file.

Note: ReqView Web Application saves Project Files into the browser download folder because it cannot directly access your file system from security reasons.

Set up Projects

Create Projects

To create a new project, click Project and select Create Project. In the Create Project dialog, select the template and enter properties of the new project.

In the Template section, choose how to populate the initial content of the created project:

• Blank — the project will contain a blank document.
• Document Template — the project will contain a single document created from a selected custom or predefined template to set up the initial hierarchy of document sections and custom attributes definition, see Requirements Specification Templates and Reuse Document Templates.
• Volere Requirements Specification — the project will be based on the Volere Requirements Specification Template.
• Clone Project — the project will copy documents from a selected project file.
• From ReqIF — the project will import documents from a selected ReqIF package, see Import Requirements From ReqIF.

In the Project Properties section, enter the ID and description of the project, see Set Project Properties.

In the Linked Project Group section, optionally select the level and group name of the project, see Linked Projects.

In the Document Properties section, enter the ID and name of the document in the project, see Edit Documents > Set Document Properties.

After the new project is created, you can add more documents, see the next section. You can also adjust configuration of traceability link types, see Configure Project Traceability.

You can also create new projects by clicking on File, selecting Open File and choosing a document or project template file (.reqw).

Note: To ensure project consistency, you cannot change project and document IDs in the application .

Create Documents

To create a new document, click Project and select Add Document. In the New Document dialog, select the template and enter properties of the new document:

In the Template section, choose how to populate the initial content of the new document:

• Blank — the document will be blank without any custom attributes.
• Document Template — the document will be created from a selected custom or predefined template to set up the initial hierarchy of document sections and custom attributes definition, see Requirements Specification Templates and Reuse Document Templates.
• Clone Document — the document will be cloned from an existing document file; note that all document objects will get new IDs, and that document history, discussion and links are not preserved.

In the Properties section, enter the ID and name of the new document, see Edit Documents > Set Document Properties.

After the new document is created, you can adjust the document structure or further customize document attributes, see Custom Document Attributes.

You can also duplicate a document directly from the Project pane, see Copy Documents.

Organize Documents

You can list all documents from the current project in the Project pane. To toggle the Project pane, click View, mouseover Left Panes, and select Project Pane. Or press CtrlAltP.

The Project pane only displays document IDs by default. To also display document names in the pane, click Edit, select Preferences, and check Show document names in Project pane.

To organize documents into groups, click Project and select Group Documents or click the button located in the Project pane toolbar. In the Group Documents dialog, create new groups, drag & drop documents to move them to a group or to reorder them.

Note: If your project was opened from a Project File, then the updated document organization is saved when you save the Project File. However, if your project was opened from a Project Folder, then the new organization is immediately saved into the Project Folder to minimize editing conflicts.

Open and Close Documents

To open a document, click on the desired document in the Project pane. The open document is displayed as a new tab placed at the bottom of the requirements table. You can change the order of document tabs by drag & drop.

Tip: To switch to other open documents quickly, press CtrlShiftPgDn / CtrlShiftPgUp or Ctrl1, Ctrl2, ..., Ctrl9.

To open all documents in the current project, click Project and select Open All Documents or click the Open All Documents button displayed in the center pane under the “No document is open.” message.

To close a document, click on the icon of the corresponding document tab or press CtrlW shortcut.

Copy Documents

You have several options how to copy the whole content of a document:

• Duplicate Document: Click or right-click on the source document in the Project pane and select Duplicate Document. In the Duplicate Document dialog, enter the ID and name of the new document.
• Clone Document: Click Project, select Add Document. In the Add Document dialog choose Clone Document and select an existing Project Folder on your file system and a cloned document stored in that project. Finally, enter the ID and name of the new document.
• Copy and Paste Content: Press CtrlA to select all document objects in the source document. Press CtrlC to copy objects to the clipboard. Switch to the target document and press CtrlV and adjust paste options in the Paste popup menu. Note that only the attributes defined in the target document are copied. See Edit Documents > Copy Objects.
• Save as Document Template: Save the source document as a Document Template and then create a new document from that template. See Reuse Document Templates.

Delete Documents

To delete the current document, click Project and select Delete Document.

Note: All traceability links involving the deleted document are removed from the project.

Set Project Properties

To view properties of the current project, click Project and select Project Properties, or click on the project ID on the left of document name at the top of the application window. To edit properties, click Edit in the Project Properties if the project is open from a project folder.

In the Project Properties dialog you can set the following project properties:

• Project Description — enter a short text description of the project.
• Level — select a level of the project in the V-model.
• Group name — enter a name of the project group.

Note: Setting project level and group can help you to organize projects, see Linked Projects. For instance, you can group linked projects in the Example System Project as follows: Level 1: Stakeholders, Level 2: System, and Level 3: Modules. The level and group of linked projects is displayed in the Linked Projects pane.

Configure Traceability

You can organize traceability links into custom link types to make traceability analysis easier. For more information see Configure Project Traceability.

Link Projects

You can split requirements for complex products into several Linked Projects to reduce the number of documents per project, reuse requirements across the projects, and control versions of linked projects independently. For more information see Manage Linked Projects.

Open Projects

To open a Project Folder, click File and select Open Folder, or press CtrlO. Similarly, to open a Project File, click File and select Open File.

Each open project is displayed in a separate application window. To edit the current project in another application window, click Project and select New Project Window. Place the new window on another monitor or place both application windows side-by-side to review and edit the project conveniently.

The application saves the last position of each application window and restores it after it is restarted.

Note: If the opened Project File is a Project or Document Template then the application opens another window with the Create Project dialog, see Create Project.

Save Projects

All your modifications of an open project are automatically saved to the local application storage and restored when the application is restarted. To save the current project to the file system, click File and select Save, press CtrlS, or click .

To save the current project as a new Project Folder stored on your file system, click File and select Save As Folder. To save the project as a new Project File click File and select Save As File. In the Save Options dialog, enter a new project ID. We recommend leaving the Save History option checked to store the internal history of changes.

However, you may want to uncheck the Save History option if you manage the saved project in Git or Subversion (SVN) version control system storing the external history as commits. If you uncheck this option then the internal history is tracked and displayed in the History pane but it is not saved within the project and the following features will be limited after reopening the project:

• View Object History
• Browse Project History
• Compare Projects
• Manage Suspect Links

Note: ReqView Web Application saves Project Files into the browser download folder because it cannot directly access your file system from security reasons.

Close Projects

To close the current project while leaving the current application window open, click Project and select Close Project. In the Close Project dialog, choose the option for saving changes and releasing project locks. The dialog options depends on the type of project storage (a project file, a project folder on network drive or a project folder in VCS repository). Then, you can open another project in the same window. You can also close the project by closing all application windows of the project.

Note: Closing the last application window will quit the application and the current project will be restored when the application is started next time.

Reuse Document Templates

You can reuse the structure and custom attributes configuration of a document by saving the document as a Document Template file. Document Templates preserve the document hierarchy, section headings, text description of objects, and the value of custom attributes. However, Document Templates do not store IDs, discussion, history, or any traceability links.

To save the current document as a Document Template file, click File, mouseover Save As Template, and select Current Document. Name the file and click OK. Then share the file on a network drive.

To create a new document from a Document Template file, click Project, select Add Document and choose Custom Template option in the New Document dialog. To reuse an existing document file (without the need to save it as a document template), select Clone Document option in New Document dialog.

Note: All document objects stored in Document Templates are assigned new IDs in the cloned document.

Tip: If you define a custom Document Template with an xhtml custom attribute with help flag set to true then you can provide for each document section detailed instructions, which the application displays in the Instructions pane, see Instructions for an example.

You can reuse the whole configuration of a project by saving the project as a Project Template. Project Templates store a collection of Document Templates and a traceability configuration.

To save the current project as a Project Template file, click File, mouseover Save As Template, and select Project. Name the file and click OK.

To create a new project from a Project Template file, click Project, select Create Project and choose Clone Project option in the Create Project dialog.

Demo Project

Browse the example Demo Project illustrating how to manage user needs, software requirements specification, risks, tests and high-level design for a SW product.