Science and Technology:

Software engineering, Agile,

UML, MODELING and more . . .

Tuesday, November 1, 2011

Automatic requirements numbering



Some time ago I was working for Airbus as Product Leader Deputy.

Among all my duties, I was responsible for writing the high level requirement specification; link it to the stakeholders’ requirements and to the technical specification.

Quality constraints in Airbus are very strict concerning the traceability, the coverage and the impact analysis.

A correct link between all the documents allows us to evaluate the progress of our project, the remaining work and impact of evolutions or bug correction.

Fortunately, there are many tools allowing us to manage these issues.

Reqtify is a very useful software used in order to create, manage and visualize the relationships between artifacts in different documents, in other words, traceability. In a previous post I have explained the "Benefits of requirements traceability"; in that post I describe how to link all the documents into a coherent structure by using a tool called Reqtify.

However, this powerful traceability requires the specification document to be written by following strict naming rules so they can be correctly traced.

Indeed, non-unique or non-homogeneous requirements IDs prevent the traceability software to find a requirement.

Under these circumstances, an automatic numbering tool perfectly prevents human errors.

Such numbering tool shall allow the writer to call it in a very easy and non-intrusive way; i.e. no pop-up or any other kind of external windows.

Airbus provided a MS Word macro called “CARE.dot”. This macro provides an automatic requirement numbering. However, the code of this macro is private, then I decided to create my own macro for requirement numbering.

Word Macro for a Functional requirements template

The configuration of this macro is very simple and its utilization very comfortable.

Hereafter the code explained


Sub AutomaticReqNumbering()
'David GARDUNO
'24/08/2011
'This macro insert automatic requirements number based on document's properties
'Define a doc property "REQ-ID", for example CMPNY-PRJ-REQ-A-
'Define a doc property "REQ-Nmbr", for example 1
'The macro will generate requirement numbers as follows
'CMPNY-PRJ-REQ-A-001-1
'CMPNY-PRJ-REQ-A-003-1
'CMPNY-PRJ-REQ-A-004-1
'CMPNY-PRJ-REQ-A-005-1

'reqnb stores the value of the reqNbrProperty property
Dim reqnb As Integer
'reqID stores the value of the reqIDProperty property
Dim reqID As String
'reqNbrProperty stores the "REQ-Nmbr" document's property
Dim reqNbrProperty  As DocumentProperty
'reqIDProperty stores the "REQ-ID" document's property
Dim reqIDProperty  As DocumentProperty

    'get the "REQ-Nmbr" document's property
    Set reNbrProperty = ActiveDocument.CustomDocumentProperties("REQ-Nmbr")
    ' get the value of the reqNbrProperty property
    reqnb = reqNbrProperty.Value
    'get the value of "REQ-ID" document's property
    reqID = ActiveDocument.CustomDocumentProperties("REQ-ID")

    'go to the beginning of the line
    Selection.HomeKey Unit:=wdLine
    'type the reqID (for example CMPNY-PRJ-REQ-A-)
    Selection.TypeText reqID
    'start typing the ID number
    If reqnb < 10 Then
        'Type one 0
        Selection.TypeText "0"
    End If

    If reqnb < 100 Then
        type a second 0
Selection.TypeText "0"
    End If

    'Type the reference number
    Selection.TypeText reqnb
    'Type the version number
    Selection.TypeText "-1 "

    'Set the last blank space as bold = false
    Selection.Font.Bold = False
    Selection.MoveLeft Unit:=wdCharacter, Count:=1

    'Select the reference number
    Selection.HomeKey Unit:=wdLine, Extend:=wdExtend
    'Set the text as bold
    Selection.Font.Bold = True
    'Go to the begining of the line
    Selection.HomeKey Unit:=wdLine

    'increment the reference document's property
    reqNbrProperty.Value = reqnb + 1



End Sub


Sub AutomaticReferenceNbr()
'David GARDUNO
'24/08/2011
'This macro insert automatic reference number based on document's properties
'Define a doc property "REF-ID", for example CMPNY-PRJ-REF-A-
'Define a doc property "REF-Nmbr", for example 1
'The macro will generate reference numbers as follows
'CMPNY-PRJ-REF-A-001-1
'CMPNY-PRJ-REF-A-003-1
'CMPNY-PRJ-REF-A-004-1
'CMPNY-PRJ-REF-A-005-1

    'refnb stores the value of the refnbProperty property
    Dim refnb As Integer
    'refID stores the value of the refIDProperty property
    Dim refID As String
    'refnbProperty stores the "REF-Nmbr" document's property
    Dim refnbProperty  As DocumentProperty
    'refIDProperty stores the "REF-ID" document's property
    Dim refIDProperty  As DocumentProperty

     'get the "REF-Nmbr" document's property
    Set refnbProperty = ActiveDocument.CustomDocumentProperties("REF-Nmbr")
    ' get the value of the refnbProperty property
    refnb = refnbProperty.Value
    'get the value of "REF-ID" document's property
    refID = ActiveDocument.CustomDocumentProperties("REF-ID")


    'go to the beginning of the line
    Selection.HomeKey Unit:=wdLine
     'type the refID (eg. CMPNY-PRJ-REF-A-)
    Selection.TypeText refID
    'start typing the ID number
    If refnb < 10 Then
        'Type one 0
        Selection.TypeText "0"
    End If

    If refnb < 100 Then
        'Type a second 0
        Selection.TypeText "0"
    End If

    'Type the reference number
    Selection.TypeText refnb
    'Type the version number
    Selection.TypeText "-1 "

    'Set the last blank space as bold = false
    Selection.Font.Bold = False
    Selection.MoveLeft Unit:=wdCharacter, Count:=1

    'Select the reference number
    Selection.HomeKey Unit:=wdLine, Extend:=wdExtend
    'Set the text as bold
    Selection.Font.Bold = True
    'Go to the begining of the line
    Selection.HomeKey Unit:=wdLine

    'increment the reference document's property
    refnbProperty.Value = refnb + 1


End Sub





I have also created a template in the form of a .dot MS-Word file.



The file is named "automatic numbering.dot" . You can download the template in Zip here  or Word format here.



How to add a macro to word 

In order to activate it in Word 2003:
  • Save the attached file
  • Open a word document
  • Menu: Outils > Modèles et compléments (Eng: Tools > Models and complements)
  • Tab "Modèles", click on "Ajouter" (Eng: Tab "Models", click on "Add"
  • Select the .dot file then accept
  • Define a doc properrty "REF-ID", for example "CMPNY-PRJ-REF-A-" (menu Fichier > proprietés > personalisation)(Eng: menu File > properties > personalisation)
  • Define a doc property "REF-Nmbr", for example 1
  • Define a doc property "REQ-ID", for example "CMPNY-PRJ-REQ-A-"
  • Define a doc property "REQ-Nmbr", for example 1

Observe that the .dot added a new menu "Auto Req Number"



In order to use the macro you need to put the prompt in the line concerning the ne menu, then select the "New req" or "New ref" options in the "Auto Req Number" menu


This macro will generate ID's as follows
  • CMPNY-PRJ-REF-A-001
  • CMPNY-PRJ-REF-A-002
  • CMPNY-PRJ-REF-A-003
  • CMPNY-PRJ-REF-A-004
  • CMPNY-PRJ-REQ-A-001
  • CMPNY-PRJ-REQ-A-002
  • CMPNY-PRJ-REQ-A-003
  • CMPNY-PRJ-REQ-A-004

How to easily access the macro in word

You can also create a shortkey

  • Menu: Outils -> Personalisation ->Commandes (Eng: menu Tools > Personalization > commands)
  • Click on "clavier" (Eng: keyboard)
  • In the window "categories" select "macro"
  • In the window "macros" select one of the numbering macros, for example "req numbering"
  • In the line "enregistrer dans" (Eng: "Save in") select your working document
  • In the line "nouvelle touche de raccourci" (Eng: "New shortkey") type your shortkey, for example Ctrl+shift+Q for requirements and Ctrl+shift+F for references

Observe that the .dot has also added a "Coller comme hyperlien" (Eng: "Paste as hyperlink") button in the toolbar.



This button will allow you to easily create links to your requirements. Fro example, there  are two requirements (007 and 010).

C264CT-BoardsConf-REQ-007 Blah blah blah

C264CT-BoardsConf-REQ-010 Blah blah blah

Now, you want to create a reference to requirement 010 in requirement 007.

  • Copy the entire requirement C264CT-BoardsConf-REQ-010, then go to requirement 007 and type "See ", then click on the button "Paste as a link". Your new requirement will look like

C264CT-BoardsConf-REQ-007 Blah blah blah. See C264CT-BoardsConf-REQ-010

Now, you can navigate within your document: Ctrl+click on the new link


Finally observe that two navigation buttons were also added by the .dot to the toolbar. These buttons allow you to easily go forward and backward your links as in any regular web page.



Enjoy and comment !


***Note. It seams that the “Paste as hyperlink” option is deactivated for some Word versions


Thursday, April 21, 2011

Communicating Systems with UML 2

Modeling and Analysis of Network Protocols



I am very happy to present my book issue of all the work that I have done during my PhD. It deals with the application of a modeling language to a very specific domain: Communication Systems. Some applications of this work can be seen in "Modeling Network Protocols With UML"


David Garduno Barrera, Consultant 

Michel Diaz, LAAS/CNRS, Toulouse, France 

ISBN: 9781848212992 
Publication Date: June 2011   Hardback   320 pp. 
See book description on Editor site: ISTE; John Wiley & Sons

David GARDUNO, PhD. He has worked as consultant for many aeronautical companies such as Airbus and Thalès Avionics. His main duties concerned system modeling and product leading. He has also worked as trainer on system modeling (SysML), Business Process Modeling (BPM), OO Analysis and Design for the European Commission and Astrium, amongst others. He currently works for an intrnational company on electrical systems.

Michel DIAZ, Director of Research at CNRS, editor of twelve books, and 200 publications, Silver Core of IFIP, Senior Member of IEEE, member New York Academy of Sciences, listed in the Who'sWho in Science and Engineering.

Most of the current bibliography on the subject is in the form of scientific papers available in very specialized scientific publications; therefore, they use a complex language and highly technical explanations.

The rest of the literature on the subject is either specialized on teaching UML or on presenting network mechanisms together with the layers of communications protocols.

On the contrary, this book exposes a set of practical examples which can be used either for teaching UML by using protocol examples or for teaching network protocols using UML, leading to a more understandable, and simulation-based approach.

This book gives a practical approach for modeling and analyzing communication protocols using UML 2. It shows how to describe and validate the main protocols issues (as synchronization problems, client-server interactions, layer organization and behavior, etc) in an easy and understandable way. For doing so, the book considers and presents the main traditional network examples (e.g., unidirectional flows, full-duplex communication, error recovering, alternating bit). Finally, it shows the outputs resulting from a few simulations of these UML models.


David GARDUNO