Tips and Tricks for Importing from MS Word

On many occassions, users receive specifications in an MS Word format that need to be imported into Spec-TRACER. This document provides some hints on how to import some challenging documents.

Introduction

To import a MS Word file, Spec-TRACER makes use of the Import Tool. Users may access this tool directly from the Tools menu of the Spec-TRACER Client, Tools | Import. The Import Tool is capable of importing from different file formats, including MS Excel, MS Word and XRI. This document will focus on the MS Word format because of the wide range of possiblities when getting to formats.

The import tool imports different information of the requirements including code, name, description, and attributes.

The import tool may import elements in MS Word based on three different criteria:

• Tables

• Styles

• Tags

Basic Import Based on Tables

If requirements in the MS Word document are included in a table like in the following format, the import tool will be able to import it straight away:

CODE	NAME	DESCRIPTION	ATTRIBUTE 1 - Criticality
RQ_001	Safety protection	The user shall be able to have maximum safety protection against any malfunction of equipment.	High

Users will only need to select Table at the beginning of the import process:

Figure 1 Spec-TRACER Import Tool: Import Tables

In the Capture Configuration window, select the table in the Sheets containing requirements field, and map the columns to the fields as shown below:

Figure 2 Spec-TRACER Import Tool: Capture Configuration

Basic Import Based on Styles

If each one of the fields of the requirements are identified with different styles in the MS Word document like in the following example:

RQ_001 Safety protection The user shall be able to have maximum safety protection against any malfunction of equipment. High

The import tool will be able to capture all of the information by selecting Import Text at the beginning of the import process:

Figure 3 Spec-TRACER Import Tool: Import Text

After selecting Import Text, users need to map each style to its corresponding field in Spec-TRACER including Code, Name, Description, and Attributes:

Figure 4 Spec-TRACER Import Tool: Code

Figure 5 Spec-TRACER Import Tool: Name

Figure 6 Spec-TRACER Import Tool: Description

Figure 7 Spec-TRACER Import Tool: Attributes

Basic Import Based on Tags

If each one of the fields of the requirements, except for the attributes, are delimited by different start and end paragraph tags like in the following example, users may configure the import tool to identify the fields based on these tags:

::start_code:: RQ_001 ::end_code:: ::start_name:: Safety protection ::end_name:: ::start_description:: The user shall be able to have maximum safety protection against any malfunction of equipment. ::end_description::

Figure 8 Spec-TRACER Import Tool: Import Tags

Combining Criteria in Text Mode

If users are using text to capture an element’s code, name, and description; users may use a combination of styles and tags, as described above. The attributes may only be imported using styles.

Import Elements That Do Not Have Consistent Formatting

In most cases, Requirement Specifications will provide some kind of formatting, even though this may not be consistent or structured throughout the document. For example:

RQ_001 Safety protection The user shall be able to have maximum safety protection against any malfunction of equipment. High

As long as each field has been identified with some distinguishing format characteristic, users may take advantage of it to rename it as a style. In this example, the code may be a Normal + bold substyle, and the name, a normal + italic + indentation substyle. If this is the case, open the styles panein MS Word, and select the Select All x Instance(s) from the combo box in the style:

Figure 9 Import Style: Select All X Instances in Word

This action will select all instances of that specific style throughout the document, and will allow users to give a specific style, either existing by selecting it from the list or new, by clicking on the styles icon . Repeat this action for each one of the different styles each field may display in the document. This will unify and structure the document format.

Using macros to import tables

Some requirement specifications may contain elements in the following way:

Code	RQ_001
Name	Safety protection
Description	The user shall be able to have maximum safety protection against any malfunction of equipment.
Attribute 1 - Criticality	High

In order to import these type of tables, users need to covert each table to a format which can be imported by the Import Tool.

For this example, use a Macro that will help format the complete document. Macros may be used to convert any type of table to a format which may be imported afterwards.

The macro performs several steps to format the complete document:

1. Find all the tables in the document.

   Macro:

   Dim tableWithRequirements As Table

   For Each tableWithRequirements In ActiveDocument.Tables

   ‘ Include the table conversion process here

   Next

2. Identify the tables that contain requirements from those that don’t. In this example, the first cell contains a “Code” text. Users may identify the table by any other means

   Macro:

   Dim firstCellText As String

   firstCellText = tableWithRequirements.Cell(1, 1).Range

   ' Remove table cell markers from the text.

   firstCellText = Left$(firstCellText, Len(firstCellText) - 2)

   If firstCellText = "Code" Then

   ‘ Include the converstion process here

   End If

3. Delete the first column with the tags Code, Name, Description, and Attribute name. The table will look like:

   RQ_001

   Safety protection

   The user shall be able to have maximum safety protection against any malfunction of equipment.

   High

   Macro:

   tableWithRequirements.Columns.First.Delete

4. In case each field does not have a distinguishing style, we will need to give each row a different style which can be used to import the table afterwards. In order to avoid conflict with other styles throughout the document, we suggest to create new ones for the import, such as styles Code, Name, and Attribute 1.

   NOTE: Typically, descriptions do have a specific style, so it may not be necessary to give it one.

   The table would end up looking like:

   RQ_001

   Safety protection

   The user shall be able to have maximum safety protection against any malfunction of equipment.

   High

   Macro:

   ‘code formatting

   tableWithRequirements.Rows.First.Select

   Selection.Style = ActiveDocument.Styles("Heading 1")

   ‘name formatting

   tableWithRequirements.Rows.First.Next.Select

   Selection.Style = ActiveDocument.Styles("Heading 2")

   ‘ attribute formatting

   tableWithRequirements.Rows.First.Next.Next.Next.Select

   Selection.Style = ActiveDocument.Styles("Heading 3")

5. Once the styles are arranged, users need to convert the table into text. This capability is provided by MS Office:

   Manually converting a table to text

   1. Select the table that to convert to paragraphs.

   2. Under Table Tools, in the Layout tab, in the Data group, click Convert to Text.

      

      Figure 10 Convert to Text

   3. Under Separate text with, select the Paragraph marks option, and click on OK.

      

      Figure 11: Paragraph Marks

After the conversion, the requirement will look like this:

RQ_001 Safety protection The user shall be able to have maximum safety protection against any malfunction of equipment. High

This requirement can now be imported directly by the import tool. Users now need to do the same with the rest of the tables.

Macro:

tableWithRequirements.Rows.ConvertToText

Separator:=wdSeparateByParagraphs, NestedTables:=True

The document is now ready to import.

Macro Sample– Converting tables

Sub Table2Text()
'
' The following macro converts the sample tables into
' text ready to be imported
'
Dim tableWithRequirements As Table
Dim firstCellText As String
Dim mySearchString As String
Dim codeStyle As String
Dim nameStyle As String
Dim attStyle As String

' Prompts the user to enter keyword

mySearchString = InputBox("The following script will look for tables containing requirements and convert them into a format that may be imported afterwards. The script will perform the following steps" & _
vbCr & vbCr & vbTab & "1. Look for a keyword in the first cell" & _
vbCr & vbTab & "2. Delete the first column" & _
vbCr & vbTab & "3. Give styles to the code, name and attribute" & _
vbCr & vbTab & "4. Convert the table to text" & _
vbCr & vbTab & vbCr & vbCr & "Enter a keyword to identify the table: ")
If mySearchString = "" Then End

' Prompts the user to enter a style for the code
codeStyle = InputBox("Enter the style of the code:")
If codeStyle = "" Then End

' Prompts the user to enter a style for the name
nameStyle = InputBox("Enter the style of the name:")
If nameStyle = "" Then End

' Prompts the user to enter a style for the attribute
attStyle = InputBox("Enter the style of the attribute:")
If attStyle = "" Then End

For Each tableWithRequirements In ActiveDocument.Tables
    firstCellText = tableWithRequirements.Cell(1, 1).Range
    firstCellText = Left$(firstCellText, Len(firstCellText) - 2)
    
    If firstCellText = "Code" Then
        tableWithRequirements.Columns.First.Delete

        tableWithRequirements.Rows.First.Select
        Selection.Style = ActiveDocument.Styles(codeStyle)
        tableWithRequirements.Rows.First.Next.Select
        Selection.Style = ActiveDocument.Styles(nameStyle)
        tableWithRequirements.Rows.First.Next.Next.Next.Select
        Selection.Style = ActiveDocument.Styles(attStyle)
        tableWithRequirements.Rows.ConvertToText Separator:=wdSeparateByParagraphs, NestedTables:=True
    End If
Next
End Sub