Managing Requirements for Fault-Tolerant Fuel Control System (Microsoft Office 2007)
Requirements Management Interface (RMI) provides tools for creating and reviewing links between Simulink objects and requirements documents. This example illustrates linking model objects to Microsoft Office Documents, navigation of these links, generating requirements report and maintaining consistency of links. See Linking with DOORS example for features specific to linking with requirements stored in IBM Rational DOORS.
The included example model is linked to documents in Microsoft Office 2007 format. If only an earlier version of Microsoft Office is available to you, jump to Updating all links when documents are moved or renamed for an example of how to adjust the example model to work with included earlier versions of documents.
- Open Example Model
- Viewing Existing Requirements
- Navigate to Document
- Requirements Links in Stateflow Charts
- Navigate from Requirements Document to Model Objects
- Creating New Links
- Requirements Links in Signal Builder Blocks
- Generating Requirements Report
- Requirements Consistency Checking
- Filtering Requirements on User Tag Property
- Updating All Links When Requirements Documents Are Moved or Renamed
- Insert Navigation Controls into Documents to Match One-way Links
- Remove All Simulink Reference Buttons from the Document
- Repair Links from Documents to Simulink
Open Example Model
Requirements management features are demonstrated using an example model of a fault-tolerant fuel control system. You can open this model by running the following command:
Viewing Existing Requirements
This example starts with the model that only has a few requirements links. Use Analysis > Requirements Traceability > Highlight model to highlight requirements. Orange highlighting corresponds to objects with linked requirements. Empty-fill highlighting is for subsystems whose children have links to requirements. Double-click the fuel rate controller block to open the subsystem and review child objects with requirements.
open_system('slvnvdemo_fuelsys_officereq/fuel rate controller'); rmi('highlightModel', 'slvnvdemo_fuelsys_officereq');
Navigate to Document
This opens the linked document and selects the target content.
Requirements Links in Stateflow Charts
Double-click the control logic chart block in the fuel rate controller subsystem to open the chart. States and transitions linked to requirements are highlighted. Right-click the Rich Mixture state, select Requirements Traceability and follow the link at the top to view related documentation.
Navigate from Requirements Document to Model Objects
In the slvnvdemo_FuelSys_DesignDescription.docx from the previous step, make sure ActiveX controls are enabled: if you see Security Alert bar at the top of the document window, click Options to open ActiveX control settings, select Enable this content, press OK.
Now find section 3.3 Manifold pressure failure mode in the document and double-click the Simulink icon at the end of subheader. This displays a relevant Simulink subsystem diagram with the target object highlighted. Close all model windows and repeat navigation from the document. Diagrams or charts are opened as necessary as long as model file can be located.
Creating New Links
To avoid unintended modification to requirements documents, the default setting is to not insert ActiveX icons into documents. Created links allow navigation from Simulink to documents, but not in the other direction. To configure your settings for creating bidirectional links, do the following:
- Select Analysis > Requirements Traceability > Settings.
- Ensure that Modify destination for bidirectional linking checkbox is selected.
Now create new links similar to the ones you've just navigated. Note: Microsoft Word will not allow you to create the link when the document is ReadOnly. For the next step of this example, consider saving your own local copy of the document and using it instead of the installed document.
Right-click Pumping Constant block again. You should now see the newly created link at the top of the context menu. Click it to navigate to the target in section 2.2 of slvnvdemo_FuelSys_DesignDescription.docx.
Requirements Links in Signal Builder Blocks
Signal links are attached to individual groups of signals, not to the Signal Builder block as a whole. Use this sort of links for test cases that are defined as Signal Builder groups.
- Double-click the Test inputs Signal Builder block to see configured groups of signals. Normal operation signals are periodically depressed accelerator pedal and constant engine RPM.
- Click the Show verification settings button at the end of toolbar to display the Verification panel.
- If you do not see the Requirements panel below the Verification block settings, click the Requirements display button at the top of the panel.
- Right-click the link label under Requirements and select View to open the related requirements data, this time in a Microsoft Excel document. The Simulink icon in the linked cell allows navigation back to this signal group.
- A transient RPM instability is modeled by a rectangular pulse on Engine speed data in the second group of signals.
- Suppose you need to link RPM sensor failure signal group to a different cell range in your Excel file. Select this signal group in the drop-down list, right-click in the empty Requirements and select Link Editor, to open a dialog box. You can either enter new link information manually, or use the Excel button to link to the current selection. Press OK to save the new link.
- Right-click the new label under Requirements area and select View to navigate to the target cell in TestScenarios file.
Generating Requirements Report
Select Analysis > Requirements Traceability > Generate report to automatically generate a report on all requirements links in the model. The default report is generated according to the template that is included with the product.
The Report Generator interface provides total control over the content of generated reports, including the creation of entirely new templates.
A subset of options is also accessed via the Report tab of Analysis > Requirements Traceability > Settings dialog box. For example, you may want to disable Highlight the model before generating report checkbox if the resulting report will be printed in black-and-white or viewed via projector, or you may want to include lists of objects that have no links to requirements.
Requirements Consistency Checking
Use Model Advisor to automatically detect and fix inconsistencies in requirements links data. Click Analysis > Requirements Traceability > Check Consistency... menu item to bring up Model Advisor with only the RMI check points activated. The links are checked for missing documents, unmatched locations in documents, unmatched labels for selection-based links, and inconsistent path information.
Click Run Selected Checks button to verify the consistency of links in your model. RMI will automatically open linked documents and check for consistency of stored data. When done, click individual check items to view the results in the right-side panel. In this example, one of the links points to invalid location in a document:
Another link has a label that does not match the original selection when the link was created:
Click Fix or Update in Model Advisor report to automatically resolve reported inconsistencies. Rerun the checks to ensure reported problem is resolved.
Filtering Requirements on User Tag Property
Requirements links in Simulink support an optional User Tag property that can store any comma-separated string values. Use these tags to distinguish between different types of links, for example, functional requirements links, design description links or testing details links. You can specify the tags when creating new links, or later via Link Editor dialog box.
You can later use these tags to focus your work on a subset of links, or to automatically strip a subset of links from the model. This is controlled via Filters tab of Analysis > Requirements Traceability > Settings dialog box.
When model requirements are "highlighted", modifying the filter setting updates the view to only show the matching requirements links. Requirements links in this example model are tagged with one of the following: "design", "requirement", "test". The view adjusts accordingly when you modify filter settings. For example, Highlight requirements that are tagged "design".
If you generate a report with User Tag filters enabled, your report content is filtered accordingly. This may be useful to focus your report on a particular subset of links.
If you run consistency checking with User Tag filters enabled, only links that match the given filter settings are checked. Use this to target your consistency checking to a required subset of links.
Updating All Links When Requirements Documents Are Moved or Renamed
It happens sometimes that the documents need to be renamed or moved after links were created. For example, if Microsoft Word 2007 is not available when trying out this example, you have to use ".doc" versions of requirements documents that are also included with this installation. However, all links in the example model point to ".docx" versions of requirements documents. Use rmidocrename command-line utility to simultaneously adjust all links in the model.
- Create a writable copy of the example model. For example, open the original system and save as 'slvnvdemo_fuelsys_officereq_copy'.
- Highlight requirements that are tagged "requirement". These links point to slvnvdemo_FuelSys_RequirementsSpecification.docx, and you need them to point to corresponding locations in MS Word 2003 version of the same document.
- Run rmidocrename(gcs,'Specification.docx','Specification.doc'). Partial matching in document name is performed; you do not need to specify the full name for the document, as long as the given pattern is specific enough to avoid unwanted changes. For example, replacing .doc with .docx would go wrong because .docx becomes .docxx. RMI responds with the following message: "Processed 6 objects with requirements, 6 out of 6 links were modified". Only objects with matching requirements were processed due to the current User Tag filter setting.
- Try navigating the highlighted links. For example, navigate from Relational Operator under Airflow calculation. Microsoft Word 2003 version of the document opens to a correct location.
Insert Navigation Controls into Documents to Match One-way Links
If you previously created one-way links from Simulink objects to documents, and later need to enable navigation from locations in documents back to the corresponding objects in Simulink, use the rmiref.insertRefs utility to insert matching "return" links into the requirements document.
One of the documents included with this example, slvnvdemo_FuelSys_DesignDescription.doc does not have Simulink navigation controls. It does have the bookmarks in locations that correspond to links tagged design in the example model.
- Reuse the writable copy of the model from the previous step.
- Run rmidocrename('slvnvdemo_fuelsys_officereq_copy','Description.docx','Description.doc') to redirect matching links from slvnvdemo_FuelSys_DesignDescription.docx to slvnvdemo_FuelSys_DesignDescription.doc. The following message appears in the command window: Processed 16 objects with requirements, 8 out of 16 links were modified.
- Navigate one of the links. For example, right-click the Airflow calculation subsystem block and navigate the Mass airflow calculation link at the top of the Requirements Traceability context menu. This brings up slvnvdemo_FuelSys_DesignDescription.doc, which does not have Simulink navigation controls.
- Run rmiref.insertRefs('slvnvdemo_fuelsys_officereq_copy','word') to insert document-to-model navigation controls into slvnvdemo_FuelSys_DesignDescription.doc. You see the Simulink navigation icons inserted into the document. You can now use these icons to navigate to Simulink objects in the slvnvdemo_fuelsys_officereq_copy model.
It is not possible to insert navigation controls if the specified location bookmark is missing in the document. In this example the document was not saved after the last link was created. The following warning appears in the command window: The named item "Simulink_requirement_item_7" could not be located in the bookmarks or section headings.
When the link in the model does not specify a location, the navigation control is inserted at the top of the document.
Remove All Simulink Reference Buttons from the Document
When Simulink navigation controls are inserted into an Microsoft Office Document, you do not necessarily have to save the document before navigating to Simulink. This allows you to temporarily insert navigation objects when needed. If you saved the document with navigation buttons inserted and now need to go back to a clean document, use the rmiref.removeRefs utility to remove the buttons. For example, perform the following steps to remove the buttons inserted in the previous step of this example:
Repair Links from Documents to Simulink
Simulink navigation controls embedded in requirements documents may get outdated when Simulink models are modified or moved. This results in broken links. Use the rmiref.checkDoc utility to detect and repair links from external documents to Simulink. In this example you we will fix one broken link in slvnvdemo_FuelSys_DesignDescription.docx document.
- Run rmiref.checkDoc(fullfile(matlabroot,'toolbox/slrequirements/slrequirementsdemos/fuelsys_req_docs/slvnvdemo_FuelSys_DesignDescription.docx')) to check the document for broken links. RMI highlights detected problems in the document and displays an HTML report.
All functional links are listed at the bottom of the report. You can navigate from this report to linked objects in Simulink (Target in Simulink column) and to the target locations in the document (Document content column).
Red font in the report highlights problems that require attention. In this case there is one broken link that references an unresolved model name.
- Click the linked text in the Document content column to locate the item in the document. Notice the changed appearance of the navigation control.
- Click to activate the control. You can fix the broken link or restore to the original (unchecked) state.
- Click Fix. You are asked to select the correct target model.
- Select slvnvdemo_fuelsys_officereq.mdl file and click OK. RMI updates the document; the normal button appearance is restored.
- Navigate the repaired link. An object in the slvnvdemo_fuelsys_officereq model is highlighted.
- Regenerate the report. All links are now functional.