Tag: DOORS Administration

Identify Attributes and Types

The biggest problems with DOORS Classic is that, even with a rigorous template and careful administration, modules in large projects can end up with different attributes with similar functions and names and worst of all, the same name but different enumeration types for the same attribute. It is almost impossible to detect these anomalies using manual means. One example could be where an attribute in two modules has a slightly different spelling or has a space on the end of the name. Another real life example, which is in the IBM Rational DOORS Car Project, is that the module ‘Architectural Design’ contains an attribute named ‘Design risk’ which has a type of name ‘Design risk’ and enumerations [High | Low | Medium ], whereas in the module ‘Stakeholder Requirements’ the type is ‘Text’.

This is of particular importance if a project is migrating to DOORS Next, where these sorts of differences can lead to huge rectification efforts.

There is not a function within DOORS Classic to identify all attributes and types. And a script that identifies just attributes or just types is of limited value because of the effort needed to compare the results. What is needed is an alphabetic list of attributes for all modules within the project or database together with the associated type and the enumerations. Any slight differences can then be easily detected and rectified.

This utility is either run from the database DXL interaction window or from the main menu.  The utility detects if it has been run with an open current project.

It begins by opening and displaying some information messages in the DXL interaction window and a popup to determine some options from the user. The export to Excel function is only active if a project has been selected, as a database is likely to contain more than 252 modules which is a limiting factor in the number of Excel columns.

Identify Attributes and Types – Option screen

Depending on the option selected, the DXL will run through each item in the database or a specific project building a skip list. Each module is opened in read only mode, background with standard view. It always ignores DXL attributes (this can be analysed using a different script). Depending on the options selected, certain other attributes are also ignored.

The output to the DXL interaction window consists of 2 items, the name of the attribute and its type combination and in which module(s) this can be found.

Identify Attributes and Types – DXL Interaction window output
Typical example of the output to the DXL Interaction Window

If the option to export to Excel is selected, then Excel is automatically opened and a table with the modules across the top as columns and the attributes and type combination in the rows. In order to make it easier to analyse, the modules are grouped by folder and the top bar is colour coded for each folder.

Identify Attributes and Types – Excel output

Because there can be thousands of modules and attributes in a database, then the script displays a progress bar based on the number of modules in the database/project to be analysed.

Update all Views in a Database

One of the problems with DOORS Classic. is that a user can create a private view and there is no way of knowing this. Even the users that normally run the administration of the database will be unable to see or manage these views. Only the database administrator user who set up the database has access to all views.

This utility is either run from the database DXL interaction window or from the main menu. It loops through all projects in the database and then all items within each project and builds a skip list of modules. It then loops through all items in the skip list – we are not using recursion to search through the database in this method. Because there can be thousands of modules in a database the script displays a progress bar based on the number of modules in the database.

Each module is opened in read only mode, background with standard view. The script runs through all the views in the module ignoring the standard view and any views with inherited access as these cannot be private or custom views. The script then sets view permissions to ‘RMCDA’ for the named group (usually the group responsible for the administration of the database) that is set as a constant in the DXL script.

Update all views in database – DXL Script checks
Update all views in database DXL Script
Update all views in database DXL Script – Output

Global Metric Counts

This utility counts the number of projects, modules and objects in the entire database. It is a simple script that is either run from a menu or loaded into the database DXL interaction window

There is a Boolean constant in the code that, if set, will print out the names of the folders and modules being searched. This is useful for debugging and for looking to see where any DXL attribute errors are located (if present, then these will be made visible when the module is opened by the script).

It doesn’t use recursion to delve down through the database structure but uses the itemRef in a ‘for’ loop through each project. This means that the order will be different to the hierarchy but since we are only interested in counts then that’s not a problem.

It will exclude deleted objects, deleted modules and deleted projects. The results are displayed in the DXL interaction window.

Global Metric Count Tool – DXL Interaction window output

The script opens up every module in the database so it can take a long time. A progress bar is therefore used to display the current position in searching through the database.

Gblobal Metric Count tool – Progress Bar

But perhaps the most significant aspect of this tool is that it can be easily adapted to collect other information as it parses its way through the projects and modules.

Module Compare

When two companies are using DOORS and need to exchange information then the requirements are often provided from one company to another by means of DOORS module archives (.dma). This means that the version that you have been working with your own changes is now superseded by a new module.

You may also have used modules as separate baselines or as variants whilst trying out combinations of requirements.

So how do you identify the differences between the versions before you update your module? A comparison of 2 modules is part of classic DOORS but it works by comparing text, attempting to match similar text. Unfortunately, if you have a lot of commonality in the requirements, then it will match, (apparently at random) completely different requirements and give totally incorrect results.

This wizard based utility solves this problem by using the DOORS Id (which is constant between versions) as the key. Note that it can be adapted to work with other data models which use other attributes as a key by simple DXL changes.

Module Compare Wizard – start screen

The start screen introduces the utility. Notice that it has been designed more or less along the same lines as a DOORS wizard.  Some introduction text on how to use the utility is displayed. The script automatically checks that the user is part of a group that can run the utility. This allows the utility to be placed on a generic DOORS menu.

Module Compare Wizard – Identification screen

The second ‘Identify’ step allows the user to identify the two different versions of a module. A log file is always created, and the user will also determine where this log file will be saved. This log file will contain the result of the comparison and can be examined by any text editor. This is very useful when the comparison is of modules that contain thousands of requirements

As well as the comparison matching the requirements, authorised users will have the ability to permanently create links between the matched objects so the associated link module can be optionally added in this screen. Normally this is set to ‘compares’ and links will be automatically created via this link module to link matched requirements.

The ‘Next’ step performs the comparison and shows the changes between the 2 modules.

Module Compare Wizard – results screen

Selecting a specific ID will show the Old text, the New text and the difference using the standard colours and fonts. Objects that contain graphics and pictures are ignored. If the right attributes are present in the new module, then comments can also be added.

For modules that contain a lot of requirements, then filters can be applied.

Metrics such as the  number of requirements are also displayed for both versions of the module.

If a user has the necessary privileges, and if the link module has been defined, then once all the objects have been examined and checked then permanent links between the matched objects can be established.

Full Listing

The Software Application IBM® Rational® DOORS® embodies a capability for customising the default tool-set using an adaptation of the C++ language called DOORS eXtension Language or DXL.

This language is a powerful tool when used correctly, as it can automate repetitive tasks, customise the look and feel of DOORS to meet specific needs, and process and manipulate large amounts of data within the DOORS database with little or no user interaction.

CiGi Technology have a vast library of functions and utilities that will reduce the administration burden of Users and DOORS database administrators and that streamlines the development of bespoke DXL scripts for DOORS 9.x.

All code produced is extremely robust, vigorously tested and checked to conform to our own exacting high standard as defined in the CiGi Technology DXL style guide . The code is always transportable and guaranteed to be database independent. The functionality has been checked for applicability up to DOORS version 9.6.1.10.

As well as standard DXL Attributes and a wealth of utilities, CiGi Technology welcome the opportunity to develop tailor made solutions. Please contact us for more information.

DOORS Administration
Example of a Project Menu
Simple Scripts – DXL Attributes
Simple Scripts – Identifying all DXL attributes in a database
Project Wide Information Structures
Using common modules
Global Search
Managing Users and Groups
Module Administration
Managing Links
Parse Login History
Update all Views in a Database
Identify Attributes and Types

Requirement Quality Analysis Utilities
Display Banned Words in Requirements
Display Requirements containing TBD or TBC
Display Requirements not set to ‘Requirement’
Display Oversize Requirements
Quick Spell Check

Metrics Collection
Quick Global Metrics
Metrics and Status Graphical Utility
Text Box Metrics collection
Percentage Bar Metrics
RAG Value Metrics

Progressive Assurance
Customer Acceptance Tool (CAT)
Manage, Review, Interact and Accept (MaRIA)
Adding Review Comments
Requirement Editor and Traceability Viewer
 Document Manager
GSN Hazard Log Editor and Viewer

Configuration Control
Module Compare
Module Merger
History Viewer
Compare with Baseline Viewer

DXL Utilities Manual

To view the complete manual in pdf click here (please note that this is still work in progress and some sections that are not yet posted will not be complete). It will take a few seconds to load but its worth the wait:

DXL Style Guide

No one should be editing DXL without this unique publication built on decades of experience. To view an example of the DXL style guide in pdf click here. It will take a few seconds to load but its worth the wait:

To purchase your own complete copy then please contact us.

Managing Links

Once again, we come up against a failing of DOORS Classic. How do you manage links?

As an example, the database administrator decides at the start of the project to have a single link set for all ‘satisfies’ links. Later the decision is made to have separate link modules for each sub project. The original ‘satisfies’ module has to be split into multiple link modules and the links from each requirement placed into one of the new link modules. To do this using classic DOORS is very labour intensive (and error prone).

This utility does this splitting for you. It is very simple. It copies or moves the links from any module pair to another other set of modules though any link module. In the above use case, the administrator will need to open up each module in turn and move the links into the correct link module.

Link Manager utility

It is run from within the source module and has 2 mutually exclusive options:

  • Move the links OR
  • Copy the links

It also has 2 toggle modes:

  • The ‘Dry Run’ mode (default) where it analyses the links and displays a list of proposed changes. This enables a review to be made before the links are actually made. If this mode is switched off, then the links are created.
  • The log results mode that displays the results in the DOORS interaction window.

Rather than browsing every time, each link, source or target module cut and paste directly into the relevant box.

Note that it assumes that the link set pairings have already been created for the new links although future enhancements of the tool could build these automatically. It could also be adapted to be run from the main DOORS window and perhaps select groups of modules for the same action.

Document Manager

In almost every project I have worked on there is a need to export the requirement set into Word as a requirement specification and get it reviewed, approved and distributed. And in a lot of cases that is how the requirements arrive; as a requirement specification that has to be imported into DOORS.

When importing or exporting then the front pages of the Word document are not part of the requirements – or at least they should not be. The requirements module should only contain the requirements and not the front matter. Where does all that information go? You also need to correlate the document versions with the module/project baselines. So how is this done?

The contents/index can be easily generated in Word but maintaining the version history, the reviewer and the distribution data is not so easy. Yes, you could put this in as ‘Information’ in embedded tables at the front of the requirements, but this is messy to edit. You could even have a separate module for the data and link it in on the build. But this makes life more complicated.

By far the simplest way is to store this information as module attributes. Clearly a DXL utility to extract, display and edit these module attributes is going to be extremely useful.

Document Manager DXL utility

This DXL Utility is extremely comprehensive and has been designed to manage all aspects of document management from within DOORS ranging from document issue, performing baselines and export to PDF.

Firstly, you select the document number- as this tool allows different documents to be exported from the same requirement module – so you could export a requirement specification, a VVRM matrix ( pulling in linked data from the test cases and even test results) and an interface specification ( filtered on interface requirements). Then select the version or issue of the document (as matched with the module baselines). What is then displayed is the document title, additional document information (which can be tailored for your company), the names of the document signatories and the document distribution record. Often this information is the same for each document and version, but it can be modified for any combination.

Depending on the user group access then these fields can be either read only or editable (in the former case the Edit button is disabled). They can also be locked down if a document is published.

What is also displayed in the lower part of the screen is the document change history and a series of buttons.

The buttons allow the creation of a new document (which is how the module can used for multiple documents as described above), creation of a new issue by execution of a new baseline (major or minor), or the generation of a pdf. This latter operation is an export using LaTex functionality and it will use all of the information above, plus a predefined company/document template containing the company headers and footers to build the complete document. As an alternative this could be linked to Rational Publishing Engine.

Before the document is produced the user can also enter the pdf file name and location and whether change bars are required.

The Working Copy entry is for when a document is needed to be exported for review but not as a formal issue. In which case the document is water marked as Draft or For Information Only.

Document Manager export options

Module Administration

The management of modules, copying of views and attributes are all essential tasks for a database administrator and yet there is no in built functionality in DOORS Classic that lets you do these simple tasks.

This utility brings together all administration type functions. It works both at the project level – allowing you to manipulate modules – and at the module level which provides access to attributes and views.

Project Level:

The utility is opened via the DOORS main menu. It automatically determines the current project folder based on what is open and/or selected but the user can navigate to any other folder.

It then lists the module names within the project. Selecting a row will display the description and the prefix. The attributes or views in the selected module are also automatically listed. There is a further filter for attributes into normal, DXL or Module attributes.

Double click on the row and the module is opened but you don’t have to open the module in order to work on it. All operations take place in Read only mode unless a save is required in which case the utility takes care of this, checking for locks etc.

The box at the top displays a running display of the success or failure of any operation.

There are a number of operations that the user can perform such as loading up a standard set of attributes from an XML file which is great for pre-populating a module.

The user can also delete attributes or views for a selection of one or more modules at the same time which is extremely useful for making changes to all modules across a project.

The Project Report button produces an Excel report of the views and attributes for all modules in the project.

A DXL utility to manage modules within a project in DOORS 9.x
Module Administration – Project Level

Module Level:

The same utility also works at the module level where the user has access to shareable edit, and can manipulate attributes and views. For example, delete one or more attributes, convert all ticked DXL attributes for the current module into text or delete one or more views.

Attributes can be copied to other modules (with the relevant checks that they do not already exist in the target module) but perhaps the most useful is the copy view function where a selected view can be copied to one or more modules. This functionality is not easily performed in DOORS Classic.

There is also a button to reset all private views in a selected module into global access views.

A DXL utility to manage modules attributes and views in DOORS 9.x
Module Administration – Module Level

Managing Users and Groups

Although DOORS permits the database administrator to set up groups, unfortunately there are no in built report functions that let you understand, for example, which users are in what group, or the permissions a particular user has in a module.

This utility provides the DOORS database administrator with a series of very comprehensive reports. Most of the reports are simple text lists, displayed in the text console, with the data separated by tabs so that it can be directly copied into Excel.

A few of the reports ( marked with an (E) ) are very sophisticated and will export directly into an Excel worksheet including coloured backgrounds for specific functionality. Some of the more important uses are as follows:

  • Provide a list of the Users for ‘cut and paste’ into excel;
  • Provide a list of each group and the members in Excel;
  • If emails have been entered then provide a mailing list;
  • Extract the RMCDA access permissions for Users, Groups in each Module.
A utility to provide a listing of all Users and Groups within a DOORS database

The Excel listing of the groups and the members is worthy of specific mention as it is extremely useful in large projects where there are hundreds of users and groups. Here is an example listing:

An Excel output generated from all Users and Groups within a DOORS database
An Excel output generated from all Users and Groups within a DOORS database. Groups are listed across the top and there is a row for each user. Details of the user are listed and ‘X’ identifies whenever a user is in a group.