ReqXChanger Closing the Gap between Requirements and Modelling

ReqXChanger Closing the Gap between Requirements and Modelling Index: Features Principles Usage Example The Gearwheel between Requirements and Modelling Time- and cost pressure, increasing competition, demand for flexibility these are all causes for our quest for more efficiency. Efficiency is a very important determining factor for our engineering processes. An efficient process uses his resources almost optimal and that is always the goal. Today, no company can afford wasting resources in their projects. There are obviously many ways to optimise engineering processes. Starting with a qualified technical staff, optimal team size, using correct engineering tools, methods and so on. An often untapped opportunity to increase the efficiency is to avoid or to close gaps between different engineering tools. Such a gap has always many disadvantages. First of all, there is a broken information chain. Therefore, somebody is needed to maintain data consistency in different tools. A thankless, time-consuming and error-prone task for a human being. Moreover, there is always uncertainty about: is this data up to date? What we need is an interface between different engineering tools. An interface that provides easy data synchronisation. An interface that draws attention to synchronised changes. Willert Software Tools has now created such an interface between common requirements management tools and the leading UML / SysML modelling solution IBM Rational Rhapsody. DatBl - ReqXChanger - V 1.1.4en - 2014.pages! Page 1 / 16

Merging Requirements and Modelling Modern products consist of a variety of hardware and software components. This mixture and the abundance of functions are mainly responsible for the increasing complexity in our projects. Handling and managing this complexity is one of our biggest challenges in the future. One step to decrease this complexity was done by software developers, just after the turn of the millennium. Text-oriented programming languages from the 3rd generation ( C, C++, Java, etc.) reach their limits. Ok, not really their limits, but the time has come to reduce the effort with another abstraction layer. This was realised by the 4.th generation of programming languages. The UML is such a programming language. A graphical notation with a set of 14 different diagram types, perfectly suited to describe complex issues in an easy way. Today, the UML is gladly taken for documenting software. But that s like programming in Assembler and documenting the same code in ANSI C. Normally, a code generator is responsible to translate the graphical UML artefacts into lines of code. This code generator is doing his job as a fully automated compiler. Only the usage of a code generator ensures that a UML model and code corresponds always to 100%. Another milestone was already taken in the early 80 s, when requirements engineering tools became state of the art in aerospace and other safety critical projects. The magic words were Linking and Tracing which enable new possibilities of analysing and managing artefacts like requirements, specifications, test cases, etc. Before this step has been taken, link relations were only stored in the minds of the project members. But the human brain has unfortunately a volatile memory characteristic. Therefore, information gets lost RM Tool and birthplaces for failures are created. Fortunately, in the meantime RM tools are well established in nearly all industry sectors. Today it s time for another big step it s time to close the gap between requirements management and modelling tools. Instead of creating another new interface for data exchanging, Willert Software Tools has taken the existing and standardised ReqIF (Requirements Interchange Format). This format was created by HIS (Hersteller Initiative Software), a group of five big german automotive companies. Primarily focused to exchange requirements between different RM tools, it s also a well suited interface format to synchronise requirements to any other software tool. By combining these two powerful engineering discipline, we have created a continuous workflow, which starts with high level requirements and goes down to the generated lines of code. Every artefact that belongs to this toolchain is linked and fully traceable. This is the key for efficiency. UML Tool ReqXChanger Product-Features Import ReqIF to ReqXChanger Explore and analyse your imported ReqIF model Export requirements to IBM Rational Rhapsody Integrate representations of software artefacts to your Requirements Management Tool UML Dependencies are also integrated to your Requirements Management Tool and represented as link Full traceability down to your software artefacts Impact analysis Coverage analysis Create dependencies between your software and requirements artefacts Import, export, synchronisation based on standardised ReqIF format Save / Load configuration Deleted or changed requirements are highlighted in Rhapsody (suspect link functionality) Customise the mapping of requirements attributes to Rhapsody Specify a target package for each DOORS Module or Polarion Document DatBl - ReqXChanger - V 1.1.4en - 2014.pages! Page 2 / 16

Principles Workflow Inside a requirements Management Tool, you will usually create requirements on different levels. These levels are for User Requirements, Design Requirements and Module Specifications. The connection between these levels is realised by creating links from requirements on a lower level to requirements on the level above. A requirement on a lower level satisfies the linked requirement above. So, Module Specifications satisfy Design Requirements and Design Requirements satisfy User Requirements. Module Specifications are the only requirements which are directly satisfied by Software Artefacts, which you create inside a modelling tool e.g. Rhapsody. Therefore, only these have to be transferred to it. After exporting a ReqIF file from a Requirements Management Tool with Module Specifications, you can use the ReqXChanger to create representations for the requirements inside Rhapsody. The Requirements Management Tool is considered to be the master of these requirements. This means, that this is the tool for modifying the requirements and to create new requirements. In Rhapsody, there are only representations of these requirements, which are not expected to be modified. While developing a software with Rhapsody, you will create several model based software artefacts. For creating a connection between these artefacts and the Module Specification requirements, Dependencies are used. A Dependency has the software artefact as source and the requirement as target. Furthermore, the Stereotype trace is assigned to the Dependency to define its kind. Then, the ReqXChanger can be used to export representations of software artefacts, which have a Dependency to a requirement. For the export, the same ReqIF file is used as for transferring the requirements to Rhapsody. Afterwards, the ReqIF file can be used to import the representations of the software artefacts into the Requirements Management Tool. Furthermore, Links are created as representations for the Dependencies. As a Requirements Management Tool is the master for the requirements, Rhapsody is considered to be the master for software artefacts and Dependencies. Now you can make a complete traceability analysis inside your Requirements Management Tool. Re-use Requirements Since Rhapsody has a different model structure than Requirements Management Tools, the requirements with their information have to be mapped to other elements. Therefore, the presented table shows the mapping of requirements and other elements from a Requirements Management Tool to Rhapsody. As an example for a Requirements Management Tool, Polarion is used in this handout. The ReqXChanger creates a Package for a Document. Package names can be configured inside the options of the ReqXChanger. For a Work Item, requirements are created and Tags are used to store attribute values. Stereotypes are created for Work Item Types and assigned to requirements. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 3 / 16

As an example, a graphic shows how a requirement from a document inside Polarion is transferred to Rhapsody. The document contains requirements of the Realtime Execution Framework (RXF) from Willert Software Tools. For each ordinary attribute value, a tag is created which contains the value. Furthermore, there are some comments, which also contain attribute values. The difference is that the comments are used for attributes, which directly exist for requirements inside ReqIF files. As an example, there is a unique identifier, which is not the same as the identifier inside Polarion. The name and the description of requirements inside Rhapsody can be mapped to any attribute value. This can be configured inside the export options of the ReqXChanger. ATTENTION: The names of requirements in Rhapsody can not contain some special characters like ( and :. If such characters occur, the ReqXChanger will remove them. Traceability and Suspect Links In order to make a traceability analysis inside your Requirements Management Tool, representations of modelled software artefacts are transferred back to the RM Tool. Therefore, a new Requirements Type (Work Item Type) is created with attributes for the name, type, path in packages and a unique identifier. The representations of the software artefacts are created as requirements (Work Items) of this type and links are created to requirements, corresponding to the trace Dependencies inside Rhapsody. When requirements are changed inside your RM Tool, you can update their representations inside Rhapsody by re-transferring them. If a requirement has changed or was deleted since the last transfer, the stereotype Changed or Deleted is assigned to the requirement. You can use the Model Browser of Rhapsody to filter for these requirements and investigate suspect links. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 4 / 16

Usage Example The following pages present an example for importing requirements from a ReqIF file into a Rhapsody model. In this example, Polarion is used as source for the requirements and to export them into the ReqIF file. But of course, any other tool, which allows to export their requirements into ReqIF files, could also be used. During the exchange of the requirements, several options can be set inside the ReqXChanger. These options and other great features of the ReqXChanger are discussed. Finally, the requirements and all of their attribute values are transferred to Rhapsody. Then, the attribute values can be inspected and the requirements can be linked with UML (and other) elements from Rhapsody. You will see, that it is very easy to keep track of your requirements! Export Requirements from Polarion Here you can see a small part of a document with requirements of our Realtime Execution Framework (RXF) in Polarion. The document contains two different kinds of requirements: Module Specification and Operation Specification. All requirements have the attributes status and priorty. Furthermore, there are headings to structure the document. In order to export the requirements, you have to select the gear-wheel in the upper left corner of the document. Afterwards, select ReqIF-Round-trip and Export Document. Then, a new dialog will appear. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 5 / 16

Inside the new dialog, select to Create a new ReqIF document and enter a file name. The document is exported as a *.reqifz file, which is a zip file that contains ReqIF documents. Confirm your selection by pressing the Start button. Now you have to select a Spec Object type for each requirements type. Spec Object types are basically the types of requirements inside a ReqIF document. Just select the Spec Object type for each requirements type, which has the same name. Afterwards, you have to select which attributes are exported. There are some commonly used attributes in ReqIF documents, like ReqIF.ChapterName, which are automatically mapped to attributes of your requirements types. Further attributes can be added for export by using the Add Attribute functionality. This is used to add the Using the ReqXChanger Now it is time to start the ReqXChanger. Before the ReqXChanger can establish a connection to Rhapsody, some configuration has to be made. Open the Global Options and select the options for Rhapsody. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 6 / 16

+--- You need to select the path of the Java API of your current Rhapsody installation. If you have more than one version of Rhapsody installed, you have to select the API of the version you want to use with the ReqXChanger. After you selected the jar file for the API, the ReqXChanger needs to restart. Info Usually, there is a directory for Rhapsody inside your Windows user directory. Then you will find the Java API inside a directory, which is structured like the following: C:\Users\$user $\IBM\Rational\Rhapsody\ $Version$\Share\JavaAPI \rhapsody.jar. If you have selected to use only one directory for Rhapsody during its installation, you will find the Java API in a similar sub-directory of your Rhapsody program directory. Polarion exported your requirements into a *.reqifz file. As mentioned above, this is a zip file, which contains ReqIF documents. As for now, the ReqXChanger expects to import requirements from uncompressed ReqIF files. Therefore, you have to unzip the *.reqifz file, before you you can import the contained ReqIF file with the ReqXChanger. Import the Requirements into the ReqXChanger Inside the ReqXChanger, select to import requirements from a ReqIF file. Afterwards, select the Options for this import mechanism. A new dialog will appear in which the ReqIF document for the import has to be specified. You can do this by either browsing through your file system or by manually entering a path. Select the unzipped ReqIF document, which was exported by Polarion. Confirm the dialog by pressing OK. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 7 / 16

After finishing the ReqXChanger import configuration, press the Import button. The Log view will show if everything was successful. The ReqXChanger also allows to inspect the imported requirements. Therefore, select the Imported Model tab. You will see all the imported data as it is structured inside the ReqIF file. Inside the Imported Model tab, you will see Specifications for each document type SpecTypes for each requirements type Datatypes for attribute datatypes SpecObjects for each requirement SpecRelations for each link SpecRelationGroups for each link type Export the Requirements into Rhapsody At first, you have to select IBM Rational Rhapsody as export mechanism. Afterwards, open the Options for the export process. In contrast to the ReqIF import, there are several options, which can be set. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 8 / 16

Inside the Changes tab, you can set options for updating existing requirements. There are two different options for marking requirements with a certain stereotype. One option is for applying a stereotype Changed to requirements, which already exist in Rhapsody and changed since the last export. The other one is for applying a stereotype Deleted to requirements, which do already exist in Rhapsody, but do not exist inside an updated ReqIF file anymore. The last option affects, how existing requirements in Rhapsody are compared to updated requirements inside a ReqIF file. It is recommended to only compare the lastchanged attribute for this purpose. Inside the Mapping tab you will find options for mapping certain attributes of requirements in Rhapsody to attributes of your requirements in ReqIF. You can use the Drop Down Combo to select an attribute of your imported ReqIF file. Furthermore, you have the possibility to combine different attributes. For instance, you can enter the following string to get the Polarion ID as prefix and the chapter name as postfix: $ReqIF.ForeignID$_$ReqIF.ChapterName$ The characters $... $ indicate a child attribute of a ReqIF element while $<... >$ indicate a property of a ReqIF element itself. You do not have to set a Type Name Mapping since by default the longname of a requirements type is used and Polarion has exported a suitable name for it. The Packages tab can be used to specify in which Rhapsody Packages the ReqXChanger exports the requirements. You can set a Root Package for the export by entering a name in the provided text area. Furthermore, you can specify a (sub-) package name for each document type. Therefore, select a document type on the left side of the table by using a Drop Down menu. On the right side of the table, enter a package name for the selected document type. ATTENTION: In Rhapsody the names of requirements must be unique inside the same hierarchy level. Therefore, it is recommended, to include an identifier in your Name Mapping. If a name is not unique inside a hierarchy level, the ReqXChanger is trying to make it unique by adding a postfix to the name. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 9 / 16

Now it is time for executing the export. At first, you have to make sure that Rhapsody is started and a project is opened. Close the Active Code View in Rhapsody to dramatically increase the speed of the export. Afterwards, press the Export button inside the ReqXChanger and take a look at the progress inside the Log view. Best Practice Tip We recommend to import a ReqIF file before you set the options for the export process. By doing this, the ReqXChanger can provide possible elements for export options inside Drop Down lists. Manage your Requirements in Rhapsody In Rhapsody, you can investigate the requirements inside the Model Browser. They are exported into the specified packages and have the same hierarchy as they had inside Polarion. Each requirement has a stereotype which stands for a requirements type and may have different attributes. The attributes of requirements are exported as Tags. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 10 / 16

You can take a look at the attribute values of requirements by opening the Features Dialog of Rhapsody and selecting the tab Tags. The description of the requirement is mapped to the attribute value as it was specified in the export options. Of course, you want to link software artefacts with requirements inside Rhapsody. Therefore, you can use Drag & Drop to place any of your requirements from the Model Browser inside a diagram. By default, the requirement will be displayed with its description. Then, you can create a Dependency from a software artefact to a requirement. Inside the Features Dialog select the Stereotype trace to specify the kind of this Dependency. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 11 / 16

Impact Analysis in Rhapsody Of course, you can update your representations of requirements in Rhapsody by repeating the previous steps. If a requirement changed since the last transfer, it will be marked as Changed by assigning a Stereotype to it. This feature can be configured inside the Export Options of the ReqXChanger. In order to make an Impact Analysis inside Rhapsody, a filter for changed requirements can be used. Therefore, a Query can be created inside any Package in your Rhapsody Project. Open the context menu of a Package and select Add New -> Query. Use the Features Dialog of the Query to configure its search criteria. Inside the dialog, select to filter for elements which have the Stereotype Changed, as it is illustrated inside the screenshot. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 12 / 16

A Query can be executed by making a double click on it or by changing the View of the Rhapsody Model Browser. Afterwards, all changed requirements will be shown in their correct hierarchy. Open the Features Dialog for a changed requirement to investigate which Rhapsody elements are related to it. Roundtrip Model Elements to Polarion Press the button in the lower left corner of the ReqXChanger to switch to the Roundtrip Mode. Afterwards, buttons for executing the roundtrip will appear. The selected Importer / Exporter have to be the same as they were used for transferring representations of requirements to Rhapsody. In order to roundtrip linked Rhapsody elements, press the Roundtrip Export and Import button. Then, the ReqXChanger will analyze which Rhapsody model elements are linked to requirements and will create and write representations of linked model elements into a ReqIF file, which is located inside the same folder as the source ReqIF file. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 13 / 16

Inside Polarion, you can import the representations of the Rhapsody model elements from the newly created ReqIF file. Therefore, select Documents & Wiki on the left side and afterwards Import Document -> ReqIF Document in the upper area. Best Practice Tip We recommend to create a new Work Item Type in Polarion for importing representations of Model Elements and naming it RXC Software Artefact Type. For this type, create the attributes Artefact_Path, Artefact_Type, Artefact_ID with String as data type to be able to store all the available information in Polarion. Furthermore, you can already create a document in Polarion for importing the Rhapsody elements. How you create Work Item Types and Polarion Documents can be read in the Polarion documentation and is out of the scope of this datasheet. Inside the Polarion Wizard for importing a ReqIF file, at first the target documents have to be selected. For the Specification Rhapsody Elements, select the target document in which you want to store the representations of the Model elements. For all the other Specifications, select the document(s) from which the requirements were originally exported from Polarion. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 14 / 16

The next step of the wizard is for mapping requirement types and attributes of ReqIF elements to Polarion Work Item Types and attributes. If the original requirements did not change inside the ReqIF file, just select to let Polarion ignore their attributes. Scroll down until you see an area for mapping elements inside the ReqIF Specification Rhapsody Elements. Here, locate the mapping of the requirements type RXC Software Artefact Type and select a suitable Polarion Work Item Type for it. The attribute ReqIF.ChapterName should be mapped to Title and ReqIF.Text to Description. For the other attributes, select a suitable attribute of your target Work Item Type. The attribute Artefact_Path contains the absolute Path of an element inside Rhapsody and the attribute Artefact_Type contains the name of its Rhapsody type. The document UML_Elements now contains representations of all Rhapsody model elements which have a Dependency to a requirement. These representations of model elements also have Polarion Links to the related requirements. This enables you to make a traceability analysis and other analyses by using great features of Polarion. DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 15 / 16

Product: ReqXChanger Author: ARNE NOYER MARCO MATUSCHEK Editor: WILLERT SOFTWARE TOOLS GMBH Hannoversche Straße 21 31675 Bückeburg www.willert.de info@willert.de Tel.: +49 5722 9678-60 IBM is a registered trademark of International Machines Corporation Rational is a registered trademark owned byibm DOORS is a registered trademark owned by IBM Rhapsody is a registered trademark owned by IBM MS Word is a registered trademark of Microsoft Corporation Polarion is a registered trademark of Polarion Software DatBl - ReqXChanger - V 1.1.4en - 2014.pages!! Page 16 / 16