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.
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.
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)
It is very simple to add custom menus for both the top level database menu (for project wide utilities) or for the module level. However, it is very important to ensure that the utility is added to the correct menu so that the two types of functionality are not mixed.
This is an example of a global type menu:
Example of a Project menu dropdown
This menu can be added in two ways. The first is by the use
of .idx files which are simple textual lists of the menu which are interpreted
by DOORS or secondly by DXL scripts which use the DXL functions createMenu (), createItem
() and separator().
The menus can also be used to directly launch help documents
so that they are readily available to the users. No more searching through the
team SharePoint site hunting for the training manual… It is available at the
click of a menu.
Example Help menu
This is particularly useful for user guides, data models and
training material. Word, PowerPoint and pdf document styles are already
embedded within our generic DXL script – and the list can be readily tailored
for your project. For example, you could add work-flows displayed in Visio.
All of CiGi Technology utilities have additional protection
so that project wide utilities can only be run from the main menu and that only
module level utilities can only be run from within a module. There can also be
protection added so that only authorised groups can use either the complete
utility or specific functions within the utility.
Although it is very easy to see the changes since the last
baseline. Paradoxically one of the hardest things to do in DOORS is to find the
history of changes through all baselines. You have to open all the baselines
manually and then go to the right object and then open the properties. And then
sometimes combine them.
And what if you wanted to easily see what was changed, and
by whom, for specific attributes. DOORS
has all the data but how do we get to it?
This very easy-to-use utility solves this problem. It searches through all the history records for all baselines in the module. Once the data has been gathered, then you can then data-mine the results in many different ways, and where possible show the differences in the standard deleted and added Rich Text formats.
The sophisticated navigation functionality allows you to
rapidly move through objects and even synchronise the viewer to the current
object.
The need to understand the changes between the current
version and the last, or even between any version, is very common. This utility
simplifies this need by displaying all the previous baselines in a module and
allows the user to select a baseline to compare with.
Screen to choose the previous baseline for the comparison
It then produces a view showing the differences to the selected baseline (Note that this image is deliberately fuzzy in order to protect the contents).
Results of comparing the current module with the selected baseline
This
utility will collect metrics from multiple modules rather than just a single
one. The modules within a project are displayed and are then selected manually.
The values collected from the modules are displayed in a text box, separated
with tabs.
The
values can be copied directly into an Excel spreadsheet where they can be analysed
and displayed in a graph or pie chart using Excel tools which are ideal for
management summaries.
The Metrics and Status Tool automatically calculates the traceability,
review and verification status of all the requirements for a specific module.
It’s a great way to direct the user to the work required.
Get Metrics Status Tool
The status is represented as a traffic light system. Each of the view buttons apply a predefined filter to the module to only show the requirements with the specific value. For example, the user can select the View button to display the 315 objects that do not have the necessary traceability in place, so that the links can be added.
The values can also be directly exported to Excel using the Save Metrics button where they can be analysed and displayed in a graph or pie chart using Excel tools which are ideal for management summaries.
