Abstract
This document describes why requirements need to be tracked and also explains how tracking can be setup and managed.
Content
The IBM Rational System Architect DOORS integration helps users create abstract views in System Architect based on the user requirements in IBM Rational DOORS. Having this integration will enable users to synchronize the model with the ever changing requirements. This document can be used as a reference for users who would like to map their requirements captured in DOORS to a modeling tool Rational System Architect. Also, there would be an information flow between DOORS to System Architect and vice-versa.
Using the document provided, users can map the requirements in DOORS to the System Architect project encyclopedia and vice versa. As a summary, this document can prove effective as a start point for new users who are in the process of exploring this integration and its benefits.
Managing requirements across Analysis and Design phases using System Architect & DOORS
1. Page 1 of 20 “Rational Support Whitepaper”
Managing requirements across
Analysis and Design phases using
IBM Rational System Architect & IBM Rational
DOORS
Rajesh Avanthi and Praveen Sreenivasan
November 15, 2010
2. Page 2 of 20 “Rational Support Whitepaper”
PREFACE .................................................................................................................................................3
INTRODUCTION .................................................................................................................................4
BASIC CONCEPTS OF SYSTEM ARCHITECT-DOORS INTEGRATION...................5
PRE-REQUISITES FOR SETTING UP SYSTEM ARCHITECT-DOORS
INTEGRATION .....................................................................................................................................6
INSTALLATIONS.......................................................................................................................................6
VERIFYING THE INTEGRATION SETUP...................................................................................................6
SYSTEM ARCHITECT-DOORS VERSION COMPATIBILITY CHART .....................................................6
TRANSFERRING ARTIFACTS FROM SYSTEM ARCHITECT TO DOORS................7
SYSTEM ARCHITECT DOORS INTEGRATION WITH DOORS AS THE START
POINT.....................................................................................................................................................14
CONCLUSION .....................................................................................................................................19
REFERENCES.......................................................................................................................................20
3. Page 3 of 20 “Rational Support Whitepaper”
Preface
Requirement Analysts and Architecture Analysts tend to work separately from
each other, while the work performed by each role directly impacts the other. In
other words, traceability across the work groups is typically minimal, if existent at
all.
Management of the architecture development process is very difficult if the
organizations can not trace back to the requirement(s) that explain the “why” of
their implementation efforts, regardless of whether it is enterprise architecture,
application architecture, or technology architecture.
Requirements Management becomes difficult when focus is lost on what the
original drivers were for their implementation decisions, like business objectives
and goals
Business requirements are the organization drivers for the project. They include
business rules, standards, regulatory requirements, legal constraints, etcetera.
User requirements capture the information that the end users wants from the
defined system.
System requirements move from the outside-in perspective of the business and
the user requirements move from the inside-out perspective of what a system
would need to do to meet the business and user requirements.
In a general scenario, you would gather some requirements and manage them in
DOORS. Once done, these requirements would be passed on to the modeling
phase. In the modeling phase, you would then check and validate these
requirements with reference to the intended model and see if the business needs
are fulfilled with the requirements provided.
Also, it’s not a surprising scenario that the requirements change during the
project development.
To retain the focus and to handle the changing requirements efficiently, the
requirements management and design tools/products must be integrated well.
Rational offers DOORS to manage requirements and System Architect for
subsequent design. Thus, having a two way integration between System
Architect and DOORS serves to be a very effective aid.
4. Page 4 of 20 “Rational Support Whitepaper”
Introduction
This document will be useful for users who would like to manage their
requirements in Rational DOORS and build the model in Rational System
Architect. It also covers the step by step procedure of bringing in the
requirements and building a model with these requirements.
This document describes both starting points of the integration:
• System Architect as the starting point
The document describes how you can transfer the artifacts from Rational
System Architect to DOORS, link these artifacts to some requirements
within DOORS and send it back to Rational System Architect.
• DOORS as the starting point
The current System Architect DOORS integration available with the
product does not allow integration from DOORS as a starting point. This
document describes how this can be overcome using CSV import/export
facility.
The document also outlines how to take all the requirements from an existing
DOORS module into one Rational System Architect definition and vice-versa.
You can be selective and take a section of the existing requirements to various
definitions that the user creates in Rational System Architect. As this would be
very specific to modeling strategy and depends on the scenario, it’s beyond the
scope of the attached document.
If you are not familiar with System Architect-DOORS integration concepts, this
document is the pick for you. It starts with the basic concepts involved in the
integration then moves on to describe the actual integrations. If you are looking
at setting up the integration, the prerequisites are also covered here.
5. Page 5 of 20 “Rational Support Whitepaper”
Basic Concepts of the System Architect-DOORS
Integration
System Architect encyclopedia objects that are sent, or to be sent, to DOORS are
associated with one or more DOORS Transfer Unit definition in System Architect.
A DOORS Transfer Unit can be thought of as an envelop holding System Architect
Encyclopedia Objects. The DOORS Transfer Unit is a definition type in System
Architect created by the users.
System Architect encyclopedia objects are sent to one or more Formal Modules
(surrogate modules) in DOORS, where they can be linked with requirements.
All linking is done in DOORS! System Architect reflects the links, but no links can
be done in System Architect.
When you send System Architect artifacts to DOORS, you will need to specify
what DOORS Formal module is to be created to hold this information. As this
module is updated by System Architect, it is also referred to as a the DOORS
surrogate module
There is a one-to-one relationship between a DOORS Transfer Unit definition and
a DOORS surrogate module.
6. Page 6 of 20 “Rational Support Whitepaper”
Pre-requisites for setting up System Architect-
DOORS integration
Installations
1. Install Rational System Architect, Rational DOORS client and Server.
2. Install the System Architect-DOORS interface
Verifying the Integration Setup
The DOORS menu options seen in Rational System Architect and System Architect
menu options in DOORS will appear after installing the System Architect-DOORS
interface.
System Architect-DOORS Version Compatibility Chart
Please refer to the compatibility chart below before setting up the System
Architect-DOORS integration.
System
Architect
DOORS Version Compatibility
10.3-10.4.23 7.0, 7.1, 8.0 System Architect version 10.3 and
10.4.23 were tested with DOORS 7.0, 7.1
and 8.0
10.6.11 HF1
and HF2
7.0, 7.1,8.0,8.1 System Architect10.6.11 is even
compatible DOORS 8.1, however it threw
errors when tested with DOORS 8.2
10.7.16 7.0, 7.1, 8.0, 8.1, 8.2 System Architect10.7 was tested to be
compatible with DOORS 8.2 but has
reported issues with 8.3
10.8.4 8.0,8.1,8.2,8.3 System Architect10.8 is compatible only
with DOORS 8.0 and above
11.0.37 8.0,8.1,8.2,8.3 System Architect11.0.37 is compatible
only with DOORS 8.0 and above.
11.1 8.0,8.1,8.2,8.3 and 9.0 System Architect11.1 is compatible only
with DOORS 8.0 and above.
11.2.25 9.0 and above System Architect11.2.25 is compatible
only with DOORS 9.0 and above.
11.3 9.0,9.1 System Architect11.3 is compatible only
with DOORS 9.0 and above.
11.3.1 9.0, 9.1 and 9.2 System Architect v11.3.1 is compatible
only with DOORS 9.0 and above.
11.4 9.0,9.1,9.2 and 9.3 System Architect11.3 is compatible only
with DOORS 9.0 and above.
7. Page 7 of 20 “Rational Support Whitepaper”
Transferring artifacts from System Architect to
DOORS
The following screenshots describe the general steps that need to be followed in
order to send the existing artifacts from Rational System Architect to the
requirement management tool “DOORS”
1. Create a new encyclopedia (example: DOORS capture)
2. Configure the encyclopedia accordingly.
3. In the new encyclopedia create a definition. In this example the “Use
Case” definition was used
4. Give the definition an appropriate name and associate an existing package
or define a new package (example: define a new “SRS” package)
8. Page 8 of 20 “Rational Support Whitepaper”
5. Leave the defaults and Click OK in the Dictionary Object dialog
6. Launch DOORS and open the project where you existing requirements
module exists.
7. Now right-click on the new definition that you created and select DOORS -
> Stage for DOORS…
9. Page 9 of 20 “Rational Support Whitepaper”
8. Create a new Transfer Unit in the project where your existing DOORS
requirements are located. By default System Architect will populate the
project that is currently open, shown in Step 6.
9. Select the newly create Transfer Unit and click OK
10. You will now see that the definition in System Architect has a “door” icon
beside it. This represents that it is ready to be sent to DOORS.
10. Page 10 of 20 “Rational Support Whitepaper”
11. Highlight the definition in the System Architect explorer and then navigate
to the Tools -> DOORS menu and select the “Send to DOORS…” menu
option.
12. Select the Transfer Unit again and click OK
13. You will notice some activity and dialog box indicator appear. Once
completed you will notice a status log window towards the right hand side
of System Architect letting you know the transfer information.
14. At the same time a “Surrogate” module will have been created in your
project with the same name as the Transfer Unit that you created. In
addition you will see in the Description column “System Architect
Integration Proxy - do not edit” which is also an indicator that this is a
surrogate module.
11. Page 11 of 20 “Rational Support Whitepaper”
15. Open the surrogate module in DOORS and you should see an object
created that is associated with System Architect.
16. Right-click on the object that was created (in this example it is called
“SRS.SRSreqs”) and select Link –> Start Link
17. You will notice that the object/requirement in DOORS now changes color
to a darker shade of pink, indicating that it’s been selected as a source
object to be linked.
18. Now open your existing requirements module that you want to transfer
over to System Architect. In this example project, there is a module that
the requirements engineers created called “System requirements”. You will
want to now take these over to System Architect so that you have visibility
of these requirements in System Architect as definitions.
12. Page 12 of 20 “Rational Support Whitepaper”
19. In the existing module, highlight the first requirement and with the “shift”
button depressed scroll to the bottom to locate the last requirement and
then click the last requirement with the “shift” key still depressed. This will
select all the requirements in the module and change the color to a shade
of pink
20. Either go to the Link menu option or right-click on one of the selected
“pink” requirements and select “Make Link from Start”
21. In the dialog that appears click the “Selected objects” button
22. In DOORS you should now see that all your system requirements from
your existing DOORS module have been linked to a particular requirement
in the System Architect surrogate module (or Transfer Unit). This is
depicted by “see link” indicators:
13. Page 13 of 20 “Rational Support Whitepaper”
23. In System Architect, navigate to the use case definition that we created in
Step 4. Highlight it and go to Tools -> DOORS -> Update from DOORS…
24. Depending on the size of your existing requirements module the
integration will create dictionary objects under the definition that you
selected. Once the update has completed you will see the following:
25. System Architect has now been populated with the requirements
information from your existing requirements module.
14. Page 14 of 20 “Rational Support Whitepaper”
System Architect DOORS integration with DOORS as
the start point
Now, lets assume that the we already have the requirements defined in our
requirement management tool (for example: DOORS) and would like to bring this
into System Architect. In order to achieve this, the following describes a way by
which users can have the requirements in DOORS exported to a CSV file and then
have this CSV file imported into System Architect.
NOTE: Currently, System Architect-DOORS integration does not allow a user to
do this in a straight forward way. The method described below may be very
cumbersome if there are many objects/requirements defined in the DOORS
module/CSV files which need to be brought into System Architect. The steps
explained below have been described as an example to demonstrate how a
requirement written in DOORS can be mapped to System Architect via a CSV file.
1. Start by writing a requirement in the DOORS module. In this case, you have
this requirement created in the DOORS module with the name “Object
Definition”. Your objective would be to have this “Object Definition” created in
DOORS and then have this mapped to System Architect and vice-versa.
2. You will now export this requirement out to a CSV file from DOORS.
15. Page 15 of 20 “Rational Support Whitepaper”
3. The CSV file exported from DOORS
4. In order for System Architect to understand this requirement on import, you
would need to create this requirement as a definition such that on doing a
CSV import, System Architect would be able to understand in which object the
columns in the CSV file need to be placed. Hence, write a USRPROPS file as
below:
NOTE: In the above screenshot, “Object Definition” would be a user defined
definition type in System Architect. Hence, to be able for System Architect to
create this user defined definition, you need to declare it in the syntax as shown
in the code above. Also, there are 150 user defined definitions that can be
created in System Architect which is denoted by “User 1”, “User 2”, ….. , “User
150”.
If there exists multiple requirements (say 3 requirements) which need to be
imported into System Architect, then the above code would be written as:
For more information on how to write the usrprops.txt code, please refer to the
System Architect online help section.
16. Page 16 of 20 “Rational Support Whitepaper”
5. Have this USRPROPS file imported into the System Architect encyclopedia so
that the meta-model understands the new object. In this case, the new object
is the “Object Definition” which in turn is a requirement in the DOORS module.
6. Once the USRPROPS file has been imported, reopen the encyclopedia in
System Architect. Now go to the menu Dictionary -> Import Definitions.
NOTE: In the Path below, specify the path to the CSV file which was exported
from DOORS. In the definitions list, select the definition which was newly
created which will in turn be mapped as a requirement in DOORS.
17. Page 17 of 20 “Rational Support Whitepaper”
Click on “Ok” to Import the CSV file into System Architect.
Notice that a new entry was added into System Architect.
7. Expand the definition node to find the newly created “Object Definition”.
8. Now, map this definition to a new DOORS module.
9. Create a new Transfer Unit
18. Page 18 of 20 “Rational Support Whitepaper”
10. Select the New Transfer Unit name to complete the staging.
11. Notice that icon is seen in System Architect which shows the object to be
staged to DOORS.
12. Now send this Object to the DOORS module.
13. Select the new transfer unit name created above to complete the Send to
DOORS operation.
13. Observe that this object was successfully transferred to the DOORS module.
19. Page 19 of 20 “Rational Support Whitepaper”
Conclusion
The System Architect DOORS integration helps users create abstract views in
System Architect based on the user requirements in DOORS. Having this
integration will enable users to synchronize the model with the ever changing
requirements. This document can be used as a reference for users who would like
to map their requirements captured in DOORS to a modeling tool Rational System
Architect. Also, there would be an information flow between DOORS to System
Architect and vice-versa.
Managing changes to the requirements and mapping it to the equivalent model
sometimes becomes very challenging if there are too many objects or artifacts
present within the requirements module. As a result, for effective results and to
manage dynamic requirements, System Architect DOORS integration would be
the effective solution.
Using the document provided, users can have the requirements in DOORS
mapped to the System Architect project encyclopedia and vice versa. As a
summary, this document can prove effective as a start point for new users who
are in the process of exploring this wonderful integration and its benefits.
20. Page 20 of 20 “Rational Support Whitepaper”
References
The following were used in references or as other sources of information:
• http://publib.boulder.ibm.com/infocenter/rsdp/v1r0m0/index.jsp?topic=/com.ibm.help.downl
oad.sa.doc/helpindex_sa.html
• http://publib.boulder.ibm.com/infocenter/rsdp/v1r0m0/index.jsp?topic=/com.ibm.help.downl
oad.sa.doc/helpindex_sa.html