Introduction
In some projects, project teams work with textual requirements instead of model-based requirements, as we normally do in BriefBuilder.
In particular in the civil engineering and energy sector, the use of requirement texts is still widespread and it is not always possible to transform these texts into model-based requirements – for either legal or practical reasons.
Therefore, we have created a dedicated requirement text module in BriefBuilder.
This module allows you to capture requirement texts in a breakdown structure and link these texts to the project parts to which they apply (e.g. particular systems, spaces, processes). This enables project teams to work systematically with requirements even though these are captured in a traditional text format.
The central idea: document parts are captured as “requirement text objects” in BriefBuilder, where they can be linked to verification plans, verification outcomes, RFCs, and to the specific systems to which they apply.
In this article, we will explain how this works, covering the following topics:
- Capturing requirement texts
- Adding pictures or files to requirement texts
- Adding attributes to requirement texts (e.g. external ID, source, …)
- Adding labels to requirement texts (e.g. requirement categories)
- Linking requirement texts to objects (e.g. systems or locations)
- Analysing requirement texts
- Verifying requirement texts
- Managing changes
- Importing requirement text from other tools
Important: to be able to use this module, you must activate it in the modules menu, unless you already did that when creating your project model.
Please note: When using this module, requirements remain textual, which means that these requirements are not very useful from a BIM perspective. Therefore, our general recommendation is to go for model-based requirements if possible.
Capturing requirement texts
In BriefBuilder, requirement texts can be captured in a dedicated requirement text tree, which is essentially a hierarchical list of all individual requirements. In systems engineering literature, this tree structure is often referred to as a requirements breakdown structure, or RBS.
In the tree, you can create two kinds of objects:
- Folders (): these are entities that can be used to structure the tree. They don’t have a requirement status, but you can add classification or numbering (see below) to them in keeping with the classification / numbering of the requirement text objects.
- Requirement text objects (): these are the actual requirements, consisting of a short name/title and a description field for the text.
To create these objects, you have to do the following:
- Click on the + button at the tree header or in the action menu behind an object’s name.
- Next, you can select what kind of object it should be: a folder or a requirement text.
- If you have created a requirement text object, you will get a detail view on the right hand side, with an entry field called Description. That is where you can place the actual text when you click in the field.
Capturing images or files
It can be that requirement texts are accompanied by images. These can be captured in the supporting file field, which can be found next to the description field.
Please note: when working from an existing document, you will first have to save the image that you want to use (click on the right mouse button when standing on the image and then select “save image as”). Once you have saved it, you can select it as supporting file in BriefBuilder.
Good to know: you can add any file type as a supporting file, but images (with extensions such as .PNG or .JPEG) will actually show a preview image once uploaded. Image files will also be added as actual images to generated Word reports.
Tree structure
The structure of the tree depends on where the texts come from.
If your starting point is another requirements tool (e.g. IBM DOORS, Relatics, Polarion), there is probably a already a tree structure, which you can import in BriefBuilder.
If your starting point is a classic PDF or Word document, the tree typically follows the document’s structure. Chapters and paragraph headers become folders. Paragraphs and sentences or combinations of sentences become requirement text objects. See the example below.
In the latter case, you will have to think about how to name your requirements. If a paragraph contains multiple requirements, you can either simply repeat the paragraph’s name for each requirement while adding a letter (a, b, c, etc). Or, you could take a closer look at the content of the requirement and add one or two words about that.
TIP: when there are images or diagrams in a text, these can be added via the supporting file field. Please note however that you can only add one image or diagram per requirement.
TIP: when working with texts, you may want add line breaks (‘enters’) in the text. This can be done by using the key combination Shift-ENTER.
Adding attributes
It can be that you do not only want to capture the requirement itself, but also additional attributes such as:
- External requirement ID (note: all requirements automatically get a BriefBuilder ID as well)
- Status (e.g. required vs desired)
Such attributes can be added via BriefBuilder’s classifications/numbering settings. For this, you have to do the following:
- In the navigation menu, go to: Settings > Requirements > Classification/numbering.
- Select Requirement texts as tree.
- Add the relevant attributes by using the + Add classification/numbering button.
- Choose picklist as input type if you wish to add a drop-down picklist. You will also be able to add a description for every individual picklist option (which can be especially useful when using a pre-existing classification system, such as Uniclass or NL-SfB).
- If relevant, you can change the table header (Classifications/numberings) into something else by clicking on the edit button next to the header name.
TIP: you can choose to include classification/number properties as an (automatic) prefix for the requirement text object’s name. This can be useful when working with external requirement IDs.
Example: say that a requirement text has Topsoil as a name, and it has BB.0007.A as an external ID. In that case, the requirement’s name will be shown as BB.0007.A │ Topsoil
Adding labels
In case you want to add requirement categories (e.g. stakeholder requirement, system requirement, design requirement, …), you may want to use BriefBuilder’s label feature.
Labels are flexible categorizations that can be added to any kind of object in BriefBuilder. You can create them on the detail view of a requirement text in the table General.
To create a label, you can just start typing in the Label field. If there are already labels in use, these will pop up as suggestions.
The advantage of labels is that you can use them for filtering and (pre)selections in various tables. Another advantage is that labels are visible in the tree structure. See below.
Note that labels are by default shown in the tree structure. If you prefer not to see them there, you must click on the icon in the tree’s header.
Linking requirement texts to objects
Once you have captured the requirement texts in a tree structure, you may want to link these to the specific project parts to which they apply.
In BriefBuilder you can link requirement texts to the following kinds of decompositions:
- Systems and elements: this is a decomposition of all the ‘technical’ parts of your project (e.g. climate systems, distribution systems, foundations, walls etc.).
- Spaces and locations: this a geometric or geographical decomposition of your project (e.g. locations, connections, spaces).
- Processes and activities: this is a decomposition of the processes and activities that the contractor or design team has execute in the project.
To relate a requirement text to an object, you have to do the following:
- Click on +Select in the relevant Applies to table.
- Check the box(es) for the objects to which the requirement text applies
This exercise may—in some cases—feel somewhat redundant. For example, if you have a chapter called Footbridge in your source document, and thus also in your requirements tree, it feels redundant to link all the requirement texts from that chapter to an object called Footbridge in your systems and elements tree.
This is different, however, if you have multiple Footbridge objects in your systems and elements decomposition (e.g. Footbridge A, Footbridge B, as in the example above). In that case, it makes good sense to link the requirements to each of them because then they can be individually be verified and managed.
The creation of relations may also relate to how the project is organized. It can be that it is the construction client who provides the requirements tree, and that it is the contractor that creates the other decompositions based on their design or tender bid. In that case, creating relations is an essential activity for the contractor, specifying which of the client’s requirements have to be applied in the different project parts.
TIP: To check whether the right requirements are related to the right objects, you may want use the Cross table – relations, in which you can select the tree Requirement texts and another tree (e.g., Systems & elements) to get an overview of all the relations you have created.
Interlinking requirement texts
When you have a large number of requirement texts, it is quite likely that different requirement texts are related to one another and you may wish to make these relations explicit in your model.
In particular in systems engineering (SE) models, this tends to be a big thing with ‘higher-level’ requirements being linked to ‘lower-level’ requirements.
In BriefBuilder, such relations can be created in the table Related requirement texts.
Depending on what types of relations there have been defined in the settings menu, you’ll be able to choose from different types of relations.
You can define the different options for this relations in the settings menu. You have to go to:
Settings > Requirements > Picklists for relations
Analysing requirement texts
A requirements analysis is a systematic review or assessment of all the requirements in the model. It is an exercise that it is typically done by the design/delivery team at an early stage of the project.
Read here for a comprehensive explanation of how you can work with analysis in BriefBuilder.
Of particular relevance for requirement texts is the notion that there are two levels of analysis.
- The first level concerns the requirement text itself: is the formulated clear, feasible and relevant? Does it represent any risks? Is there a need to reformulate?
- The second analysis level concerns the relations to other objects. There, the question is whether the requirement is relevant for the particular project parts to which it is linked. Is the requirement feasible and relevant for that particular project part?
Both levels of analysis can be facilitated by BriefBuilder’s analysis feature. See here for more info on how to set this feature up. A total overview of all analysis outcomes can be found in the analysis table and the analysis dashboard.
Verifying requirement texts
Verification is the process of checking whether the proposed, designed or built solutions meet the set requirements.
Just like with analysis, the verification of requirement texts can be done at two levels:
- The requirement text itself: Has this requirement been met, in the project as a whole?
- The relations between requirements and objects/project parts: Is a particular object (e.g. a space or system) compliant with the requirements that apply to it?
Our general recommendation is to focus on the relations because verifications are, almost by definition, related to a specific object: you are verifying whether a particular design/ engineering solution is compliant with the formulated requirements.
Having said that, it can also be that a requirement is so general in nature that it cannot be linked to a particular object. In that case, you can only verify the text itself, or create a generic object (e.g. Project), to which you link the requirement.
Note: you can view en execute your verifications at three places in the model:
1) at the detail view of the requirement text
2) at the detail view of the related object
3) in the verification table.
Example of verification on relation level. Note that you have to click on the yellow verification button in the upper right corner of the detail view to see these fields.
Read here for a more elaborate explanation of how you can work with verification in BriefBuilder.
Managing changes
Just like with model-based requirements, you create requests for change (RFCs) for requirement texts. See here for a full explanation of this feature.
Note: when linking a requirement text to an object, the requirement text is shown in italics on the object’s detail view. The italics indicate that you cannot edit or change the text there, as it may be linked to other objects as well. So, changes to requirement text always have to made in the requirement text tree itself.
Importing from other tools
If requirement texts come from another application (e.g. DOORS, Polarion or Relatics), requirement texts can often easily be imported via Excel.
To do so, you have to do the following:
- Get an Excel export with all requirements from the system in question.
- Adjust the Excel file according to our format to make it suitable for an import into BriefBuilder.
- Predefine any requirement attributes/classifications that you would like to include in your import (as explained earlier in this article). E.g. if you want to import a requirement number, you first have to create requirement number as a classification/numbering property in BriefBuilder.
- Import the file via the import button () at the top of the requirement text tree.
Import format
The import templates can be found here.
Note that you have to use an import file with the right language. For English project models, you need the English template; for German models, the German template; etc.
As you will notice, the import template has three sheets: objects, properties, and relations.
If you want to import requirement texts, only the first two are relevant. The sheet relation is relevant when you want import links to objects in other trees.
See below for how to fill out the different columns in the import template.
Worksheet objects
This is the sheet where you place the requirements names and the texts. See below for which columns are relevant.
| Column | Content |
| A (Object type) | The type of object you want to create. In this case either a folder or a requirement text |
| B (Object ID) | Not relevant, unless you need to distinguish between requirement texts that have the same name (in column C) |
| C (Object name) | The name or title of the requirement |
| D (Parent object ID) | Not relevant, unless the parent object has a specific ID (in column B) |
| E (Parent object name) | The name of the object (in this case: folder or requirement text) under which an object should be positioned in the tree |
| F (Description) | The actual requirement text |
| G (Labels) | Possible labels, if relevant (e.g. system requirement, stakeholder requirement) |
In this example, you are importing two folders and two requirement texts.
Important: make sure that all requirement names are unique. If not, you can add a number or other kind of identifier in column B (Object ID), to distinguish between requirement texts that share the same name.
Worksheet properties
This is the sheet that you can use to import attributes such a requirement ID or a reference to a source.
Assuming that these attributes are relevant for all objects in the tree, you should first create them as classification/numbering items via the settings menu, as explained earlier.
| A (Object ID) | Not relevant, unless you have used IDs on the object sheet |
| B (Object name) | The title or name of the object (i.e. requirement text or folder) for which you want to add the attribute) |
| C (Property name) | The name of the attribute that you want to import (e.g. external requirement ID) |
| D (Comparator) | Not relevant in this case |
| E (Value) | The value or content of the attribute (e.g. AA.B3 or something like that) |
| F (Note) | Not relevant in this case |
In this example, all four objects (2 x folder, 2 x requirement text) get an an external ID
Worksheet relations
This sheet is only relevant if you want import relations between the requirement texts and objects in other trees (e.g. systems and elements).
| A (Object ID 1) | Not relevant, unless you have used IDs on the object sheet |
| B (Object name 1) | The name of the requirement text that you want to create the relation for |
| C (Object type 2) | The type of object that you want to relate to (e.g. system, element, space, process, …) |
| D (Object ID 2) | Not relevant, unless you need to distinguish between objects with the same name |
| E (Object name 2) | The name of the object that you want to relate a specific requirement text to (e.g. footbridge, platform etc.) |
| F (Value) | Not relevant in this case |
| G (Note) | A possible Note (e.g. additional explanation about why this requirement is relevant for this particular object). |
In this example, there are two requirement texts (concerning durability and maintenance) that will be related to an spatial element called ‘Floor office spaces’
Sounds complex? Don’t hesitate to reach out if you need help!