Offline Review of DOORS Documents

Copyright © 2014, Eccam s.r.o. All Rights Reserved.

Offline Review of

DOORS Documents

Libor Buš, Eccam

February 2014, version 0.10

Page 2 Eccam s.r.o. Krakovská 9 | 11000 Prague 1 | Czech Republic +420 242441347 | [email protected] | www.eccam.com

IBM Rational DOORS is the most widely used requirements management (RM) tool for complex

system projects in automotive, aerospace and defense industry. It allows managing complex pro-

jects which contain a large number of requirements and their traceability links.

This article explains how offline project stakeholders can review and approve requirements main-

tained by the DOORS server. This use case is needed during collaboration with customers, suppli-

ers or colleagues who do not have access to the DOORS server. Sometimes even online stake-

holders need to work on project requirements offline during a business trip or at a customer's site.

There are several ways to work on DOORS documents without a direct connection to the central

DOORS server:

DOORS CSV import/export

DOORS ReqIF roundtrip synchronization

DOORS Partitioning

DOORS CSV Import / Export

DOORS CSV import/export allows users to export a DOORS module into CSV file which contains

selected requirements and their attributes described by a DOORS view. CSV file can be opened in

any spreadsheet tool such as Microsoft Excel or OpenOffice, user can modify requirement's attrib-

utes, save the changed CSV and import it back into DOORS.

This approach is very simple, however, it has several shortcomings – user does not see the docu-

ment tree structure in the spreadsheet, user cannot add new requirements into a chosen docu-

ment section, RTF object description formatting is lost, data type consistency is not preserved in

CSV, so the user can enter a wrong requirement's status for instance, and there is no history of

changes done outside DOORS. Another important issue is that the original DOORS document can-

not be easily locked, thus online users can change the document in the meantime and those

changes might be overwritten by CSV import of the offline changes.

An advantage of this approach is that reviewers can work in a favorite spreadsheet.

DOORS ReqIF Roundtrip Synchronization

ReqIF (Requirements Interchange Format) is a very promising open industry standard (OMG) for

exchanging requirement documents between RM tools. It is based on a generic XML format and

supports synchronization of complete requirement documents while preserving data types, re-

quirements hierarchy and traceability.

ReqIF is well suited for data migration and roundtrip data synchronization between RM tools. A

disadvantage of this approach is that reviewers need a special offline tool with support for the

quite new ReqIF format. There are some ongoing efforts to implement an open source ReqIF off-

http://www.eccam.com/reqview.php?utm_source=Whitepapers&utm_medium=pdf&utm_campaign=ReqView

http://www.omg.org/spec/ReqIF/


line editor as part of Eclipse Requirements Modeling Framework (RMF) project. This format also

does not preserve history of changes done outside DOORS.

DOORS Partitioning

DOORS Partitioning feature provides native offline editing support without losing any information

by data transformations. The workflow is as follows: at first a project administrator creates a parti-

tion definition on the original DOORS server and includes all desired formal and link modules into

it. A privileged user then can export the partition to a file, lock locally exported data for modifica-

tion and send the partition export file to a reviewer.

The reviewer needs to install both DOORS database server and DOORS client locally, set up the

database and import partition from the file. Then he can modify the desired document and when

he is finished he returns the partition back by sending a file to the privileged user who can syn-

chronize changes back to the original DOORS server.

The main shortcoming of this approach is that reviewers have to install DOORS locally and get a

local DOORS license file.

ReqView - Review Requirements Anywhere In this section we introduce ReqView solution for smooth collaboration with offline DOORS project

stakeholders which allows intuitive browsing through requirement structure, changing require-

ments status, commenting requirements, automatic capturing of changes history and synchroniza-

tion of changes back into DOORS database. ReqView is developed by Eccam and its beta release is

already available for evaluation purposes.


http://www.eclipse.org/rmf/

http://www.reqview.com/?utm_source=Whitepapers&utm_medium=pdf&utm_campaign=ReqView


ReqView consists of two main components:

ReqView Desktop: UI application for desktop PC

ReqView Synchronizer: data synchronization tool

ReqView Desktop is a rich web application allowing users to create requirements documents,

browse through requirement structure, change requirement's attributes, view discussion related

to each requirement and add new comments. ReqView Desktop can be installed as an offline web

application in Google Chrome web browser or deployed as an online web application. It does not

need any external network connection and stores all data locally on user’s computer.

We also plan to develop ReqView Mobile - a mobile web application designed for tablets or smart

phones which will be optimized for smaller screen sizes and touch based user input.

ReqView Synchronizer is a native application for synchronization of changes done in ReqView

documents during a requirements review with the original requirement documents stored in a RM

tool. Synchronizer allows users to import into ReqView from IBM Rational DOORS a structured re-

quirements document by means of CSV or ReqIF format. Advantage of ReqIF format is that it pre-

serves rich formatting of requirements text including embedded images. Users can also synchro-

nize status changes and new comments from ReqView back into the original RM tool document by

means of CSV roundtrip synchronization.

Possible future extension might be ReqIF export and import of requirement documents via stan-

dard OSLC-RM protocol.

The workflow for offline requirement approval process and roundtrip CSV synchronization be-

tween ReqView and DOORS consists of following four steps:

1. A DOORS user exports chosen DOORS module into CSV.

2. The DOORS user then converts CSV into encrypted ReqView document and sends this docu-

ment to an offline reviewer.

3. The offline reviewer modifies ReqView document and optionally shares it with other review-

ers who can modify it as well. The last reviewer sends ReqView document to the DOORS

user.

4. The DOORS user imports changes from ReqView Document into DOORS.

Following text describes these steps in more details.

1. Export DOORS Module into CSV

As the first step you need to define CSV export for a chosen DOORS module, i.e., which require-

ments (rows) and attributes (columns) will be exported to a CSV file.


https://chrome.google.com/webstore/detail/reqview-desktop/cmbnhmeabefpflildnahpbghcejkblin?utm_source=Whitepapers&utm_medium=pdf&utm_campaign=ReqView


http://www.reqview.com/apps/desktop/ReqViewDesktop.html?utm_source=Whitepapers&utm_medium=pdf&utm_campaign=ReqView

http://open-services.net/wiki/requirements-management/


1. Open chosen DOORS module for offline requirements review.

2. Define ‘CSV Export View’ with at least the following columns: Absolute Number, Object

Heading, Object Text and Object Level. Optionally you can also define a filter selecting

only desired rows, e.g., only a given section of the document.

3. Switch to ‘CSV Export View’ view and choose from File / Export / Spreadsheet menu to open

Export Spreadsheet dialog:



Choose Export: Displayed columns, Include: Display set only, check Include attribute names/

column titles in first row and Data separator: Comma options. Then choose file location for

exported CSV file and by Advanced button change Encoding option to UTF-8. Then press Ex-

port button.

2. Convert CSV File into ReqView Document

Before opening a CSV document in ReqView you need to convert it to ReqView data format by

ReqView Synchronizer tool which you can download after login to ReqView Support Portal

from Solutions / Downloads / Download ReqView Synchronizer. The Synchronizer needs a JSON

conversion configuration file and a user defined password as arguments.

1. Prepare configuration file for conversion of DOORS CSV exports into ReqView data for-

mat. Check the following example configuration file:

{ "name": "Test document", "attributes": { "status": { "type": "enum", "values": [ { "key": "draft" }, { "key": "approved" }, { "key": "rejected" } ] } }, "mapping" : [ { "attribute": "id", "external": "Absolute Number"}, { "attribute": "heading", "external": "Object Heading"}, { "attribute": "text", "external": "Object Text"}, { "attribute": "level", "external": "Object Level"}, { "attribute": "discussion", "external": "ReqView_Discussion"}, { "attribute": "history", "external": "ReqView_History"}, { "attribute": "status", "external": "ReqView_Status"} ] }


http://support.reqview.com/solution/categories/51232/folders/83257


Section mapping describes the mapping of CSV columns with DOORS requirement at-

tributes to requirement attributes in ReqView data format. For instance, the DOORS

attribute Absolute Number is treated as ReqView attribute id.

Section attributes describes custom defined values of status attribute. You can use it to

force each ReqView Desktop user to choose a status only from a given set of values, for

instance “draft”, “accepted”, “rejected” and “clarify”. Each status value consists of a

value used for sorting and a label presented in ReqView Desktop.

2. Convert the CSV file into ReqView by running Synchronizer with following command

prompt arguments: $ synchronizer.exe --import -i <input_file> -f csv -o <output_file> -c <cfg_file> -p <password>

For example: $ synchronizer --import –i ReqViewUserNeeds.csv –f csv –o ReqViewUserNeeds.reqw –c config.json –p mypassword

3. Send the created ReqView JSON file to an offline document reviewer and share the

document password with him.

3. Modify ReqView Document

Assuming you now want to review the document, change requirements' statuses and comment

the requirements in ReqView Desktop:

1. Install ReqView Desktop offline web application from the Google Chrome Web Store,

see following link: https://chrome.google.com/webstore/detail/reqview-desktop/

cmbnhmeabefpflildnahpbghcejkblin

2. Run ReqView Desktop:





3. From menu File choose (Ctrl+O) to show Open Requirements Document dia-

log. Choose ReqView file ReqViewUserNeeds.reqw created in the previous section and

enter the right password.

4. After opening the document you should see the same requirement structure as in

DOORS. The Table of Contents is in the left pane, the center pane contains the Require-

ments Table with hierarchy and the right pane contains the Discussion and History re-

lated to the selected requirement in Requirements Table.

5. From menu File / User Settings adjust your contact details – name, email and company.

This information will be automatically attached to new comments and your modifica-

tions to identify you as an author.

6. Review the document - edit requirement status directly in the Requirements Table and

add comments with the Add Comment button (Ctrl+M). You will see a change indi-

cator in the ID column when you change a requirement. You will also notice a discussion

indicator placed to the left of the Description column for each requirement with a com-

ment.

Note: DOORS CSV import is not able to handle modification of document structure -

add, move or delete requirements therefore you can synchronize back into DOORS only

changes in the attributes and new comments.

7. The changes done in the document are automatically saved into application persistency

storage, however, the opened file on your local drive is not changed. You can save the

document into a new ReqView file containing all changes by File / Save As menu item

(Ctrl+S). File is by default encrypted by the same password as the original document.

8. You can distribute the new ReqView file to another reviewer or send it back to the user

who can import it back to DOORS.

4. Export Changes into DOORS

After all offline reviewers have finished modifications of the ReqView document, it can be sent to

the DOORS user who will import it into DOORS. The import is done in two steps, at first the

ReqView document is converted into CSV format suitable for DOORS import, then the CSV file is

imported into DOORS.

1. Convert the CSV file into ReqView by running ReqView Synchronizer with the following

command prompt arguments: $ synchronizer.exe --export -i <input_file> -o <output_file> -p <password>

For example: $ synchronizer --export –i ReqViewUserNeeds.reqw –o ReqViewUserNeeds.csv –p mypassword

2. Open the original requirements module in DOORS and then from menu File / Import /

Spreadsheet open the Import Spreadsheet DOORS dialog:



Choose Import attributes: By column labels option, Import options: Update existing ob-

jects and Update: All Objects options. Then choose the created CSV file and with the Ad-

vanced button change Encoding option to UTF-8. Then press the Import button.

3. When you first import ReqView changes into DOORS you will be asked if DOORS should

create nonexistent attributes with additional ReqView information. The names of these

attributes were specified in ReqView import configuration file. For our example above

confirm creation of the following four DOORS text attributes:

ReqView_Status, ReqView_Discussion and ReqView_History.

4. In the next Select Key dialog choose Absolute Number attribute as the unique identifier

for import.

5. Define a new view ReqView_View containing the new ReqView attributes and check im-

ported changes before saving:



Conclusion In this paper we described three possible ways of reviewing DOORS requirement documents with-

out any connection to a DOORS server – data synchronization by means of CSV and ReqIF file for-

mats and DOORS partitioning feature.

Then we introduced ReqView, our solution for effective collaboration of offline reviewers, and pro-

vided a detailed tutorial describing the workflow for offline requirements approval process with

ReqView. At the moment, ReqView supports import from IBM Rational DOORS 9.4 and IBM Ra-

tional DOORS Next Gen 4.0.1 by means of CSV and ReqIF formats and export of changes from

ReqView to DOORS by means of CSV format. Import of ReqIF file preserves rich formatted text in-

cluding images.


Software

Offline Review of DOORS Documents