How to Analyze Requirements Traceability in Neo4j Graph Database

 May 5, 2022 Libor Buš tips share

Learn how to query, visualize and validate requirements traceability for ReqView projects using free tools based on the Neo4j graph database.

Detailed and consistent requirements traceability increases product quality because it enables requirements verification and validation. For safety-critical products, requirements traceability is the key to compliance with functional safety standards.

When we invest quite a lot of effort in linking requirements across the development cycle and ensuring traceability consistency why not query and analyze traceability effectively?

In ReqView, you can manage and review end-to-end traceability easily. You can customize traceability views for impact and coverage analysis, browse the traceability graph, filter requirements with missing links, export traceability reports to Word, Excel, and other formats. For more information see How to Use Requirements Traceability Matrix (RTM).

Let’s see how you can further extend ReqView by a powerful Neo4j graph database to query and visualize traceability graphs.

Requirements Traceability Graphs

Requirements traceability can be intuitively modeled as a directed graph, in which:

• Nodes represent records storing project artifacts — e.g., requirements, tests, risks, design elements.
• Edges represent relationships between project artifacts — e.g., parent/child links, traceability links, origin/copy links.

Example: The epic "Define Requirements" contains the user story "Requirement Description", which is further decomposed to several functional requirements as depicted by the following traceability view.

The corresponding traceability graph has 7 nodes for the epic NEEDS-8, user story NEEDS-68, and functional requirements SRS-x. The directed edge from the user story to the epic represents the parent/child relationship, and the directed edges from the functional requirements to the user story represent satisfaction links.

Neo4j Graph Database

Neo4j is a popular graph database allowing to store traceability graphs including requirement attributes and types of traceability links. Neo4j can be an effective solution for requirements traceability analysis in large projects.

In Neo4j, you can:

• Query traceability — for instance, find all user stories impacted by a change in a selected SW module.
• Visualize traceability graphs — for instance, create a figure for your Powerpoint presentation displaying a coverage tree view for a selected user story.
• Validate traceability consistency — for instance, detect all satisfaction links with the wrong direction or leading between wrong documents automatically.

You can install and use Neo4j Desktop on your PC for free. It includes a self-managed Neo4j Graph Database with the Neo4j Enterprise Developer license and a few other useful tools explained later.

Cypher Graph Query Language

Neo4j offers favored Cypher graph query language allowing to query and explore complex graphs using an intuitive syntax:

Nodes:

• (n) node referred by variable n used further in the query
• (:Label) node with a given Label corresponding to ReqView document ID, e.g. (:NEEDS)
• (n:Label {property: value}) node n with a given Label having property set to value, e.g. (n:NEEDS {type: "STORY"})

Edges:

• [e] edge referred by variable e used further in the query
• [:Type] edges with a given Type corresponding to ReqView traceability link type, e.g. [:satisfaction]
• (:Label1)-[:Type]->(Label2) edges of type Type from nodes having Label1 to nodes with Label2, e.g. (SRS)-[:satisfaction]->(NEEDS)

The following examples demonstrate a few Cypher queries for the requirements traceability graph of the ReqView Demo project.

Example: For the user story "Requirement Description" (NEEDS-68) shown in the previous example, query the related parent epic and derived software requirements.

MATCH (epic:NEEDS)<-[:parent]-(story {id:"NEEDS-68"})<-[:satisfaction]-(req:SRS)
RETURN epic,story,req

Example: Query IDs of all user stories not satisfied by any software requirement.

MATCH (story:NEEDS {type:"STORY"}) WHERE NOT (story)<-[:satisfaction]-(:SRS)
RETURN story.id

Example: Count all software requirements not verified by any test case.

MATCH (req:SRS {type:"FR"}) WHERE NOT (req)<-[:verification]-(:TESTS {type:"CASE"})
RETURN COUNT(req)

Example: Query all satisfaction links with the wrong source or target document, i.e., the link source is not from the SRS document or it target is not from the NEEDS document.

MATCH (start)-[:satisfaction]->(target) WHERE NOT start:SRS OR NOT target:NEEDS
RETURN start.id, target.id

For more information see Neo4j Cypher Manual.

Import Requirements Traceability

You can import requirements traceability from ReqView into a new Neo4j graph database in two steps. First, export selected documents from your ReqView project into a Neo4j Cypher file. Then, run the Cypher file in Neo4j Desktop.

Export Cypher File From ReqView

1. Download custom export template file ReqView-Neo4jTemplate.cypher.
2. Start ReqView with your requirements project.
3. Open ReqView documents to be exported.
4. Export requirements traceability for the open documents into a Cypher file — click File, mouseover Export, select Custom Export. Then choose the downloaded template file, check Export multiple documents in the current project, and Export into a single file. Finally, press OK and select the location of the exported Cypher file.

Run Cypher File in Neo4j Desktop

1. Start Neo4j Desktop.

   

2. Create a new project and database storing requirements traceability graphs from ReqView:

   • Open Projects pane, click New and select Create project to create a new project. Then set the project name.
   • Click Add, select Local DBMS, enter a database name and a password, and click Create to create a new database.

3. Start the database — click Start in the project view.

4. Add the Cypher file to the project — click Add, select File, and choose the .cypher file exported from ReqView.

5. Open the Neo4j Browser — click Open next to the new database name.

   Note: Do not use Open button next to newly added .cypher file, because it will open the Neo4j Browser without Project Files icon in menu.

6. Create a separate database storing a new version of your requirements traceability graph — run create or replace database v01 command in the Neo4j Browser.

7. Switch to the new database — run :use v01 command in the Neo4j Browser.

8. Run the Cypher file to fill the new database — click the Project Files icon on the left of Neo4j Browser and click Run next to the .cypher file name.

For more information on how to use Neo4j Browser to query the traceability graph see the next section.

Visualize Requirements Traceability Graphs

Neo4j Browser

Neo4j Browser is a basic tool for querying and simple visualization of graphs bundled with Neo4j Desktop. To start the tool, open Graph Apps tab in Neo4j Desktop and click Neo4j Browser.

You can run Cypher queries to display traceability graphs. You can re-arrange graphs interactively by dragging nodes and zooming. You can customize graph appearance by choosing the color, size, or caption of nodes. When you select a node you can see its properties in the right pane. For more information see Neo4j Browser User Interface Guide.

Example: Visualize the traceability graph for the user story "Requirements Description" (NEEDS-68) including its parent epic and linked software requirements. See properties of the user story in the right pane.

Neo4j Bloom

Neo4j Bloom is a more advanced tool for interactive exploration of graphs, which is available with Neo4j Desktop installation. To start the tool, open Graph Apps tab and click Neo4j Bloom.

Neo4j Bloom offers several useful features for exploring traceability graphs, which are not available in Neo4j Browser:

• Multiple Perspectives — Define one or more perspectives to explore the same traceability graph using different views. For instance, create one perspective for exploring the coverage of top-level user stories by software requirements and design elements and another perspective for exploring coverage of software by verification tests.
• Search Bar — Add nodes into the scene interactively without running Cypher queries.
• Expand Nodes — Select one or more nodes and use the context menu to expand nodes linked by a given relation type.
• Map — Understand which part of the whole scene is visible when exploring large traceability graphs.
• Hierarchical Layout — Click the Layout button above the map to switch between a default force-directed layout and a hierarchical layout, which is more suitable for presenting traceability graphs. Click the Rotate Layout button to rotate the scene by 90 degrees.

When you start Neo4j Bloom the first time it creates an empty perspective for the default database. Create a new perspective and explore a traceability graph stored in your custom Neo4j database.

1. Click Perspective button in the top left corner and then click the name of the current perspective in the header of the pane.
2. In the Perspective Gallery choose your Neo4j database, click Create Perspective and then click Generate Perspective.
3. Click Use perspective to explore the database using the new perspective.
4. Click Search graph and enter a node label, relation type or even a complex pattern of nodes and their relations. For instance, enter "NEEDS NEEDS" to see the tree structure of the NEEDS document given by parent links between sections, epics, and stories.
5. Select one or more nodes, open the context menu by right-mouse click, choose Expand and a relation type to expand the displayed traceability graph.
6. Click the Layout button above the map to switch between a default force-directed layout and a hierarchical layout, which is more suitable for presenting traceability graphs. Click the Rotate layout button to rotate the scene by 90 degrees.
7. Click Presentation mode button to hide the search bar, left and right panes.
8. Click Export visualization button in to top right corner and select Export screenshot to share the traceability graph visualization.

For more information see Neo4j Bloom User Interface Guide.

Example: Visualize the traceability graph for user story "Requirements Description" (NEEDS-68) including its parent epic and linked software requirements using a hierarchical layout.

yWorks Data Explorer

yWorks Explorer is a free tool for exploring Neo4j graph databases offered by yWorks. To install the tool into Neo4j Desktop, open Graph Apps tab, enter https://www.yworks.com/neo4j-explorer/ into the File or URL text field, and click Install.

Neo4j Explorer offers the most control on graph styling. You can customize node style including its shape(s), colors, and displayed properties. For more information see yFiles Neo4j Explorer: Advanced Node Styling.

Open Data Explorer from Neo4j Desktop

1. Click the "Open" combo box next to the active database

1. Connect the database

Example: Visualize the traceability graph for user story "Requirements Description" (NEEDS-68) including its parent epic and linked software requirements. See properties of the user story in the right pane.

Validate Consistency of Requirements Traceability

We have demonstrated in the previous sections how to query and explore requirements traceability graphs manually. You can build an automated script, which connects to a Neo4j graph database, runs custom Cypher queries checking the consistency of requirements traceability, and outputs a list of found inconsistencies. There are SDKs for most of the popular languages today (including Javascipt, Python, and Java), see Neo4j Documentation - Drivers and APIs.

Example: Run an HTML report validating requirements traceability for the ReqView Demo project using a Neo4j database.

1. Import the requirements traceability graph for the ReqView Demo project as described in Import Requirements Traceability above.

2. Download example report

3. Unzip the downloaded package to a local folder.

4. Open file Reqview-Neo4jTraceabilityValidation.js in a text editor and set dbUrl, dbName, dbUser and dbPassword constants declared at the beginning of the file to match your local Neo4j database storing the requirements traceability graph.

5. Open file Reqview-Neo4jTraceabilityValidation.html in your browser and see verification results with detailed information about identified traceability inconsistencies. Click a ReqView URL link to open the corresponding requirement in ReqView.

   

6. Open file Reqview-Neo4jTraceabilityValidation-Queries.js in a text editor and customize Cypher queries used by the report.

Summary

We presented how you can enhance ReqView powerful traceability features by exporting requirements traceability into a Neo4j graph database.

We demonstrated several free tools based on the Neo4j database to visualize requirements traceability graphs. Each of the presented tools has its advantages and disadvantages:

• Neo4j Browser is great for exploring results for custom Cypher queries.
• Neo4j Bloom helps with visualization of traceability graphs interactively without running Cypher queries.
• yWorks Data Explorer is the best for visualization of traceability graphs because it provides the most control over graph styling.

Finally, we provided an example HTML report querying a Neo4j graph database to validate consistency of requirements traceability links automatically.

Acknowledgment

We want to thank our customer Günther Weidenholzer from Oberaigner Powertrain, for sharing his ideas and use cases for extending ReqView by Neo4j. Oberaigner develops safety-critical products for automotive OEMs. They need to comply with ISO 26262 functional safety standards and manage traceability between safety goals, stakeholder needs, requirements, verification & validation, and safety risks in ReqView.

Günther found a unique solution to fulfill strict requirements for validating traceability consistency given by the standard. He implemented a Python script exporting requirements traceability from ReqView to Neo4j, querying traceability graphs, and automatically generating Excel sheets with validation reports. Our approach slightly differs, but Günthers' ideas were a great inspiration for this blog post.

Try ReqView

Give us Feedback

Would you like to explore requirements traceability graphs visually directly in ReqView? Please upvote Graphical Traceability View feature request, or contact us and describe your usecase.