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 outputTypical 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.
The Requirement Editor and Viewer utility is designed to show the relationship between 2 levels of Requirement (Level N and Level N-1). Depending on the client set up, the links can be customised so that the order of the N-1 requirements can be changed so that they follow a logical progression, or a particular scenario. This tool has proved to be of immense value in presenting requirements to a review panel or the client for formal endorsement.
DOORS is particularly valuable for Progressive Assurance and for demonstrating that a requirement has been fully verified and validated. As well as showing the relationship between requirements at different levels, it is possible to link Test Results and other forms of verification evidence to all level of requirements via ‘Verification Goals’. A Verification Goal is essentially how you are going to prove that the requirement has been met. Typical outputs from the Verification Goal modules will include the Verification and Qualification Plans and Verification Cross Reference Matrices (VCRM). Note different companies will use different terminology but the principles will be the same.
The tool has been designed as both an editor (and therefore only presenting to the user those fields that can be modified) and as a viewer. These are fully integrated so that it is possible to navigate to a particular requirement in the current module using the tool, then view and/or edit attributes and then switch to the viewer to see the impact of making any changes. Either the lower level requirement or the verification attributes can be shown by a click of a button.
Requirement Editor utility
The user will be able to add or remove links from lower level requirements by the use of a search popup that interrogates the lower level module structure.
Another feature lacking in classic DOORS is to show the interrelationships between levels of requirements.
Working in conjunction with the requirement editor, CiGi Technology have produced this viewer that shows how requirements at a lower level satisfy the upper level requirement which is the subject of interest. The user can easily switch from Editor to Viewer and back again.
Example of a Requirement Traceability view
The lower level requirements are shown together with the type of relationship in the traceability from the lower level. Also displayed is the requirement ID and the heading above each requirement. This view is particularly useful for navigation around the requirements.
Either the lower level requirement or the verification goals can be viewed by a click of a button.
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 checksUpdate all views in database DXL ScriptUpdate all views in database DXL Script – Output
One of the little known facts is that DOORS keeps a record of login and logouts of each user. The file is a text file and is readable by any text editor, but it is much more useful if the entries can be parsed and analysed in order to provide the last login for each user.
When the data is merged with the user list it then becomes clear, as an example, who has had a licence but hasn’t used DOORS in a while. This utility is therefore great for tidying up users who are effectively dormant and can be ‘disabled’ (using DOORS terminology).
The first task is to locate the ‘login_history.txt’ file which is embedded deep within the DOORS file structures. Because the location can depend on the DOORS version the user will browse using the standard mini explorer and the guidance provided.
Once the file is identified and opened, then the utility will automatically parse the login history file.
Parse Login History
There are options to merge with the User List which will include users that are defined but who have never logged on since the search criteria date). Other options are to show disable users only and to select the ‘date from’ (which will reduce the parse time on large projects). If any of the options are selected, then there is a ‘Get Login Data’ button to redo the parse.
If required, then the resulting list displayed in the main window can be exported to a csv file. The file location for this output file can be either browsed or typed directly into the file location area.
Goal Structuring Notation (GSN) is used in a hazard analysis
or during the production of a safety case for systems that can cause hazards.
This could be in those industries where safety assurance is critical such as defence, automotive, rail or nuclear
sectors.
It is a graphical notation for representing the structure of
safety arguments. It is effectively a pyramid structure with a bottom layer of
evidence. The higher levels are built upon the lower levels until the argument demonstrates how
the set of evidence items combine together to demonstrate the top claim (e.g.
that the system is acceptably safe to operate in a particular operating
environment).
Although the safety case is built bottom up, in reality the
argument is a top down approach. The principal purpose of a goal structure is to show how goals (claims
about the system) are successively broken down into (“solved by”) sub-goals
until a point is reached where claims can be supported by direct reference to
available evidence (solutions).
By
using GSN in developing a safety or environmental case, you will be introducing
a confidence in the stated claims that is hard to establish by other means.
What is GSN?
Goal Structuring Notation is a graphical argumentation notation that can be used to explicitly represent the individual elements of any complex argument, based on visualization of evidence. Because it is graphical it provides a clear way of forming, and navigating, often complex arguments. The GSN diagrams are often supported by the inclusion of further textual narrative to find the right balance between brevity in the diagrams and a fuller explanation provided by the additional narrative.
The argument is levelled with a top level claim about the level
of risk (Goal 1).
Through use of an organised argument using GSN notation, the
top level claim is decomposed into lower level claims and strategies
(constituting the argument). e.g. Goals G.1.1, G1.1.1 …, Strategy S.3 etc.
The low level claims are ultimately satisfied by references
to evidence, in this example through a reference to an appropriate set of
functional requirements, safety cases and test evidence e.g. E1, E2, E3.
In simple terms, the process to produce the safety argument can be summarised in a number of steps as (this is a guide and is not mandated):
Clearly define the objective and scope of the safety argument being presented;
Define the basis for the goals – e.g. context information;
Identify strategy- i.e. how to substantiate the stated goal;
Define the basis for the strategy – as for a goal, identify any relevant contextual information;
Elaborate the strategy, defining the sub goals;
Identify solutions; and
Review and assess the GSN against qualitative review criteria such as completeness, correctness, adequacy.
GSN Symbols
Example of a GSN diagram created using Visio
Example of a GSN diagram using colours to represent maturity
In this example, the following colours have been assigned to demonstrate maturity: Blue Unassigned Red Basis has been agreed Amber Work in progress Green Work complete
The maturity is inherited from the lower level elements
according to a series of predefined rules taking into account the worst case.
For each symbol there is a ‘traffic light’ system to convey maturity. Once engineers become familiar with the GSN notation, then this aids a speedy assessment of the overall safety argument goals and strategies and their maturity and should also identify where any additional effort should be focused to resolve any specific issues identified.
Although GSN diagrams can be produced with drawing tools such as Visio or even PowerPoint the amount of information is unfortunately fixed to what is in the diagram and this may not be sufficient for a safety case.
DOORS will provide an elegant and rich GSN.
Example of how it can be done in DOORS
The user could edit the values directly in DOORS. But the aim of this tool is to present the safety argument in a clear and concise manner without the need to have any knowledge of how DOORS works or is modified.
The following two examples provide an extract of Goal Structuring Notation (GSN) relating to:
The safety argument around Hazardous RF Emissions for an aircraft.
The Automotive Safety Integrity Level (ASIL) which is a risk classification scheme defined by the ISO 26262 – Functional Safety for Road Vehicles standard.
In both examples, the GSN Hazard Log Editor and Viewer are built from a series of editors which combine together to inform the GSN display itself. The display and the editors are intrinsically linked so that edits are immediately reflected in the display. The edits are only permanent if the user saves to the underlying DOORS module(s).
The Hazard Editor for an Aerospace Project
Selection of an Aerospace Hazard
This is the main page and is used to add, delete, view, and edit an aerospace hazard. There can be any number of hazards within a project and each hazard is in its own module. The hazard editor searches through the current project identifying the hazard modules. Attributes such as the description and overall status are displayed to identify the hazard if the names are similar.
Once the hazard is selected then the user can either edit more
of the hazard attributes such as operating states or the Hazard Inherent Risk
matrix values.
Top level aerospace hazard editor
Each hazard is allocated a classification according to a
severity and probability matrix which is then used to automatically calculate
the inherent and residual risk.
Frequency (likelihood) and Severity (consequence) hazard table with Risk rating
The table used in the example is a 4 * 6 matrix, but the software can be modified to any table size. The software could also be further expanded to provide ALARP statements, links to cause and consequence mitigations, or provide links to Safety requirements to form a progressive assurance regime.
Alternatively, the user can go directly to the GSN display.
The Hazard Editor for an ASIL Project
Selection of an ASIL Hazard
This is the main page for an automotive project hazard and is used to add, delete, view, and edit an ASIL hazard. As with the aerospace format, there can be any number of hazards within a project and each hazard is in its own module. The hazard editor searches through the current project identifying the hazard modules. Attributes such as the description and overall status are displayed to identify the hazard if the names are similar.
Once the hazard is selected then the user can either edit more of the hazard attributes such as ASIL level and inherited ASIL level.
Top level ASIL hazard editor
The Display
Both editor formats use the same GSN display. The GSN symbols are displayed according to the type, location, relationship and maturity. As the levels zoom in (using the GSN display control panel) then the amount of information displayed is automatically decreased. Vertical and horizontal scroll bars can be used to move the centre of interest.
As the user zooms out then the information level increases.
The scroll bars are automatically resized with the level of the zoom.
Symbols can be selected using the right hand button. Multiple
symbols can be added to the selection using cntrl + right hand mouse button
click. Element(s) can be moved by selecting the element(s) and then pointing to
the desired location using the left hand mouse button click. A popup is used to
confirm the move.
The GSN display has its own dedicated control panel which can define automatic or manual placement of each element and a zoom factor. Because we are using the DOORS canvas then, unfortunately, we don’t have the luxury of drag and drop that you would expect with modern editors. However, by using the mouse buttons then a user can select a target location and then move one or more objects. This is a quick way of moving blocks of elements. Then each element (or a group if required) can be moved a small distance using the nudge features. Groups of elements can also be aligned horizontally or vertically. The traceability relationships are automatically moved along with the elements. The user also has access to the x, y co-ordinates in the element editor for very fine granularity changes.
When zooming then the amount of text displayed in each
symbol is truncated to remain within the symbol. By swapping between the
display and the editor, further textual narrative to support the GSN diagrams can
be added to find the right balance between brevity (in the diagrams) and a
fuller explanation (provided by additional narrative in the editor).
The display can be cut and pasted using traditional snipping tools or via Paint but the tool also provide the ability to export to xml or html.
Display controller
Both manual and automatic placement options are available. It is recommended to use the automatic placement and then swap to manual placement for fine tuning and aesthetic preferences. Also provided are buttons to centralize the display and fit the diagram on the page (by automatically calculating the zoom factor). There are buttons to align horizontally and vertically, or nudge in any direction a selection of elements. The buttons are enabled and disabled depending on the elements selected.
If an object is selected, then the element editor can be called via the Edit button.
The Element Editor
The editor is used to create or modify an existing element. If the selected object is a hazard, then the maturity and location is based on the underlying Goal. The maturity is normally assigned according to the child objects although it is possible to override. Assumptions, justifications and context elements can be added. The element editor is context sensitive and will display the appropriate editor for the element being modified. The element editor also provides the manual selection of the x, y coordinates.
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.
It is common to use colours to highlight specific values. This can be undertaken using the inbuilt features of DOORS to colour the text or the background based on the colour of an attribute enumeration. However, this has limitation in that it is sometimes difficult to read the text when in read only, and that only one colour can be used at a time.
The RAG metrics technique (and it is not limited to just Red, Amber and Green) can be used to set the colour of a layout DXL column based on keywords that are contained within the target text attribute. Any number of columns can be set up that will reflect any combination. It is a simple matter of editing the script.
This is a more sophisticated display of a percentage bar for multiple metrics for multiple modules. It uses a specific module that can be located anywhere in a project and that has just two views. There are two DXL scripts associated with this module. One is an attribute DXL script which contains functions to locate the target modules of interest, calculate the metrics and write the values back to the module; the second script contains layout DXL functions to read and parse the value entries and display the results as a list column and as a percentage bar.
Metric View: This view consists of four columns. The first column is a free format description of the metric. It takes no part in the metric determination. The second column displays a box, the percentage value, the actual count and the name for each enumeration to be counted. Note that the percentage total value may not be 100% as the individual values are rounded to the nearest integer and then totalled. The third column displays the same information but as a percentage bar. If the width of this column is changed then the percentage bar is automatically resized. The name of the attribute enumeration is only displayed within the bar if there is sufficient room to show the whole name. The final column displays the date and time when the DXL used to calculate the metrics was last run.
Metrics View
Metric Values: The entries within the columns within this view determine the metric itself. The first column is simply the Object Identifier. The second column, as in the Metric View, is the free format metric description from the Metric View. The next column determines whether the metric should be based on enumeration values in the target module or as a filtered count. The next column contains the full path of the module to be searched. If a project name (rather than a module name) is used, then the script will search all the modules in the project. If this option is selected, then the modules will need to have the same attribute enumerations. If a view name is added into the next column (it is optional and can be left blank), then this view is loaded and if the view has a filter then this constrains the values of the enumerations.
The attribute name column contains the name of the attribute that the enumeration values will be derived from. This is automatically extracted from the target module. The next column identifies the colours to be used for each enumeration. These can be set to any colour from the standard list of real colours. If there are insufficient colours defined, then the enumeration will be displayed as pale blue (which has an integer value of 0).
The next column displays the values from the DXL script that performs the search and calculations. The format is described below. The final column, as the metric view has the date and time of when the script is run.
Metric Values
These are the metrics as run on the Stakeholder Requirements module in the Car Project, with a filtered view “Requirements” applied and the System Requirements module with no view applied.
Note that the values in the Value column have a specific format and should not be changed as the entries are all calculated by the DXL script:
value,colour,B|W:count
value : name of the enumeration colour : the integer value of the colour in the colour map B|W : text colour (Black or White) count : the actual number of counts of the enumeration in the target module(s)
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.
This utility searches through all the one or more modules for keywords which are specified by the user.
The user first selects the modules to be searched based on the current project. The current project can be changed by browsing, using a mini explorer, to a new project.
Global Search utility
Up to 4 keywords can be identified at any one time and the user can select if the case is to be matched in the keywords or not. All textual attributes are searched so that includes Object Heading and Object Text, the Object Short Text, Last Modified By and any other attributes. These are automatically detected by the utility.
The user can decide if the results of the search are to be also sent to an Excel spreadsheet for later analysis. The Excel file is therefore not closed at the end of the search.
Global Search Tool-Excel output
Although DOORS Next already has a similar project search functionality, it is more akin to the typical search functionality and does not export to Excel.
