offline review of doors documents
DESCRIPTION
IBM Rational DOORS is the most widely used requirements management tool for complex system projects in automotive, aerospace and defense industry. It allows managing complex projects which contain a large number of requirements and their traceability links. This paper explains how offline project stakeholders can review and approve requirements maintained by the DOORS server. This use case is needed during collaboration with customers, suppliers 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. In this paper we describe three possible ways of reviewing DOORS requirement modules without any connection to a DOORS server – data synchronization by means of CSV and ReqIF file formats and DOORS partitioning feature. Then we introduce ReqView, a solution for effective collaboration of offline reviewers, and we provide a detailed tutorial with the workflow for offline requirements approval process with ReqView.TRANSCRIPT
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-
Page 3 Eccam s.r.o. Krakovská 9 | 11000 Prague 1 | Czech Republic +420 242441347 | [email protected] | www.eccam.com
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.
Page 4 Eccam s.r.o. Krakovská 9 | 11000 Prague 1 | Czech Republic +420 242441347 | [email protected] | www.eccam.com
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.
Page 5 Eccam s.r.o. Krakovská 9 | 11000 Prague 1 | Czech Republic +420 242441347 | [email protected] | www.eccam.com
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:
Page 6 Eccam s.r.o. Krakovská 9 | 11000 Prague 1 | Czech Republic +420 242441347 | [email protected] | www.eccam.com
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"} ] }
Page 7 Eccam s.r.o. Krakovská 9 | 11000 Prague 1 | Czech Republic +420 242441347 | [email protected] | www.eccam.com
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:
Page 8 Eccam s.r.o. Krakovská 9 | 11000 Prague 1 | Czech Republic +420 242441347 | [email protected] | www.eccam.com
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:
Page 9 Eccam s.r.o. Krakovská 9 | 11000 Prague 1 | Czech Republic +420 242441347 | [email protected] | www.eccam.com
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:
Page 10 Eccam s.r.o. Krakovská 9 | 11000 Prague 1 | Czech Republic +420 242441347 | [email protected] | www.eccam.com
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.