RMF/User Guide/Tutorial

From Eclipsepedia

Jump to: navigation, search


Basic ReqIF Concepts

A ReqIF model is a structured collection of natural language requirements. However, it comes with its own terminology. For instance, a "Requirement" is called "SpecObject" in ReqIF:

A ReqIF model has some similarities to a Excel Spreadsheet, although there are some notable differences. It's simply meant as a starting point to get a feel for ReqIF.

The following table compares a Spreadsheet model with a ReqIF model, introduces the terminology and explains it:

ReqIF Term (RIF Term) Excel Analog Traditional RM&E Term Description
Specification (SpecHierarchyRoot) Sheet Document A ReqIF model consists of an arbitrary number of Specifications. The Specification is the "Container" for the Requirements. Think of an Excel Document, that allows you to create an arbitrary number of Sheets. There are two differences to Excel: (1) The requirements in the Specification are references (which means that the same requirement can appear in multiple places); (2) The content of Specification is hierarchical.
SpecObject Row Requirement A SpecObject represents the actual Requirement. A requirement typically has a number Attributes. Again compared with Excel, each row in a Sheet represents a requirement. In contrast to Excel, the ReqIF model may contain SpecObjects that do not appear in any Specification (whether this is useful is a different question).
Attribute Cell Attribute Besides the actual text of the requirement, typical Attributes include ID, Status, etc. Note that there are no "standard" Attributes. The ReqIF model contains the definitions of the Attributes. Here the Excel analogy starts to break down. In Excel, each row has the same columns. Different SpecObjects may have different sets of Attributes.
SpecObjectType (SpecType) n/a Requirements Type Each SpecObject has a SpecObjectType. The SpecObjectType contains a list of Attributes for the SpecObject. For instance, the SpecObjecType "Headline" may have only one Attribute "HeadlineText". Another SpecObjectType "Requirement" may have three Attributes, "ID", "Description" and "Status". A Specification may then contain a mixture of SpecObjects with different types.

There are many more concepts, but this is enough to get us started.

Let's look at a concrete example to understand this. Here is a sniplet of a Specification:

The table shows the first four SpecObects, as visualized in a Specification. The tree-like structure is recognizable: INF-1 is a node with three children, REQ-1, REQ-2 and REQ-3 (this can be seen by the indentation). Let's look at INF-1 and REQ-1. If they would be selected in the GUI, the Property pane would show their Attributes, as it is shown to the right.

INF-1 has two attributes, "Description" and "ID". The SpecObjectType is "Information Type" (shown as the root in the properties view).

REQ-1 has three attributes, "Description", "ID" and "Status". The SpecObjectType is callse "Requirements Type". Let's have a closer look at that one.

The "Requirements Type" SpecObjectType is shown in the picture, with arrows indicating how the Attributes relate to the SpecObjectType (a simple one-to-one relationship). A SpecObjectType has one entry for each Attribute, consisting of a name and a Datatype. For instance, the first entry has the name "ID" and the datatype "T_ID_REQ". Note that multiple Attributes may have the same Datatype: "Description" and "Status" both have the Datatype "T_String32k".

Last, The Datatypes must be defined as well. In this example, there are two Datatypes, "T_String32" and "T_ID_REQ". These are finally based on a number of standard types that ReqIF supports.

NOTE: As of this writing, we only implemented the simple and the enumeration ReqIF types. This leaves out the complex ones (rich text, attachements, embedded files, etc.) for now.

Tutorial 1: Creating a basic ReqIF Model

In this Section, we will build a ReqIF model from scratch, step by step.

Install ProR

You can download ProR from the Download page. Alternatively, you can install ProR in any Eclipse-Installation via its update site (also listed on the Download page). Using the update site allows you to use the Eclipse Update mechanism, something that is currently not yet enabled for the standalone version.

Create the Model

  • Make sure that you have at least one Project in the Workspace
  • Select File > New > Reqif10 Model
  • Select a Project and name the file (ending in .reqif), then click "Finish"

After this, your window should look more or less as follows:


You will see your ReqIF file in the (1) Rodin Project Explorer or the regular Navigator.

The Editor (2) shows your Specifications. There will be a tab at the bottom of the editor for every Specification (Currently, there is only one, called "Specification Document").

In the Editor, you see the SpecObjects that exist in this Specification. There is currently only one, with the description "Start Editing".

The Outline (3) has three folders:

  • "Specifications" shows the Specifications in the ReqIF. You can expand the tree to expose the hierarchy of SpecObjects in the Specification.
  • "SpecObjects" shows all SpecObjects in the ReqIF as a flat list. Keep in mind that SpecObjects in Specifications are references. In contracst, this folder shows all SpecObjects in the ReqIF model, no matter whether they appear in any Specification.
  • "SpecRelations" shows all SpecRelations in the ReqIF as a flat list. For now, we will ignore SpecRelations.

The properties of a selected Element are shown in the Properties view (4). As the only Requirement in the model is selected, we see its SpecObjectTpye ("Requirements Type") and its only Attribute ("Description") with the value "Start editing here.".

When a ReqIF Editor is active, there are also additional tool bar items (5) and an additional menu (6).

Customizing the SpecType

To get familiar with the system, next we will:

  • Add two more attributes to the SpecObjectType called "ID" and "Owner"
  • We will show those Attributes in the Specification

To add new attributes, we open the Datatype Configuration dialog with ProR > Datatype Configuration.

The resulting Dialog has a folder for SpecTypes and Datatypes. Currently, there is only one Datatype (T_String32k) and one SpecType called "Requirements Type" with one Attribute "Description".

We add more Attributes to "Requirements Type" by right-clicking "Requirements Type" and selecting "New Child > Attribute Definition String". This will create a new element. Upon selecting, we can rename it in the lower pane. We do this twice for "ID" and "Owner". We assign both Attributes the same Datatype, "String32k". In the end, the dialog should look as follows:

Pror datatype configuration.jpg

Upon closing the dialog, little will have changed - the Specification still shows just two columns, Description and Link. However, if you select the requirement, you will see the new Properties (ID and Owner) in the Property view.

Showing the new Attributes in the Specification

To show the new Attributes in the Specification, we have to configure the Specification columns. We do this by selecting ProR > Column Configuration.

The resulting Dialog shows one entry for the one and only Column of the Specification. By clicking on the "Add Column" icon at the top of the dialog, we can add two more columns. We do this and name them "ID" and "Description" (in the lower pane). Feel free to rearrange the order with drag and drop, as you see fit. When all is done, the dialog should look as follows:

Pror column configuration.jpg

Note that you have to provide Strings for the columns for the same reason that we used Strings for the Labels earlier: This way we can easily match multiple SpecObjects of different types.

You can actually adjust the width of the columns simply by dragging the column headers.

Adding new SpecObjects

Now we can finally add SpecObjects by right-clicking on a row in the Specification. In the context-menu, there are two submenus: "New Child" and "New Sibling". "New Child" is the only way to produce a hierarchical structure.

In both menus, there are three entries "Spec Hierarchy", "Adding SpecObjects" and "SpecObject (Requirement Type)". Some background is needed here:

We said before that Specifications contain references to SpecObjects. A SpecHierarchy is the "Wrapper" that allows the hierarchical structure and that points to the referred SpecObject. Usually, we don't have to be concerned with them. Therefore the second option: If selected, a new SpecHierarchy is created and associated with a new SpecObject, which in turn is set immediately to the given SpecObjectType. If we had more than just one SpecObjectType (besides "Requirements Type"), there would be an entry for each type in the context menu.

To continue the exercise, select the child "SpecObject (Requirement Type)". Now we have two SpecObjects. Create a few more values and enter some values. You can edit directly in the Specification, as you would in Excel. Play around with Hierarchies.

Please note that drag and drop (for now) only creates siblings, never children (we may provide that in the future, but it's a little tricky). There are two options for creating children: (1) Simply create a new child element, or cut and paste. cut and paste will create children.

After some playing around, our Specification may look like this:

Pror speceditor 2.jpg


Quite an achievement - but also quite a bit of work to get started. Also, entering information requires a lot of clicking, and some of the descriptions are not completely visible. In the next part of the tutorial, we will address these issues.

Tutorial 2: Use Presentations

We will continue where we left off with Tutorial 1 and we assume that you have ProR in front of you with a similar model.

In this tutorial we will introduce Presentations. Presentations are Eclipse Plug-Ins that extend the functionality of ProR. Specifically:

  • Presentations can change the way how Attributes are rendered in the Specification
  • Presentations can change the way how Attributes are edited in the Specification
  • Presentations can perform tasks in the background.

ProR comes with a number of standard presentations that we will introduce in this tutorial.

Linewrap Presentation

By default, text is not wrapped in cells. We will enable the Linewrap Presentation for the Description column.

To do this, we select ProR > Presentation Configuration.

The dialog shown has no entries. The dropdown menu "Select Action..." at the top allows us to create new Presentations. We select the "Linewrap" Presentation. This will create a new entry in the upper pane. Upon selecting it, we can configure it in the lower pane.

A Linewrap Presentation has only one configuration element, the Datatype. We select "T_String32k". This means that from now on, all Attributes of this type will be rendered with the Linewrap Presentation. Upon completion, the dialog should look like this:

Pror presentation configuration.jpg

Upon closing the dialog, the lines that are too long should be wrapped automatically. Also, upon clicking on a cell, the content is now wrapped in the editor.

ID Presentation

It would be nice if every SpecObject had its own unique ID. Actually, it does (it is shown in the Property View, if a SpecObject is selected in the Outline View). But that ID is meant for machines and is not practical.

The ID Presentation allows the automatic creation of IDs. Let's create one.

Remember that Presentations are associated with Datatypes, not Attributes. Thus, we first have to create a new Datatype. We then associate that Datatype with the Attribute "ID". We described this process in the first tutorial. Here is a screenshot of the configuration dialog, when all is done:

Pror id configuration.jpg

The last step is, like before, to associate that Datatype with the Presentation.

We open the Presentation Configuration and create a new Presentation from the dropdown menu "Select Action...", this time of type "Id" Presentation. We associate it with the newly created Datatype. After configuration, the dialog should look as follows:

Pror id presentation.jpg

Note that you could adjust the prefix and the Count.

NOTE: At this point, the Presentation doesn't check yet for duplicates. It simply grabs a new value from count, increments it and uses it. Also, existing values are not overwritten.

Tutorial 3: Advanced SpecTypes

So far, we have a model with only one SpecObjectType. In this tutorial, we will show how we can work with multiple SpecTypes, and we will introduce other SpecTypes.

Multiple SpecTypes

The first entry in our Specification ("A ProR Tutorial") isn't really a requirement. Thus, it doesn't need an ID or an owner, and it would be nice to Highlight it somehow. For Highlighting, we have the Headline Presentation. We will:

  • Create a new "Headline" SpecObjectType
  • Create a new Datatype that will be used for the Headline content
  • Associate that Datatype with the Headline Presentation

With ProR > Datatype Configuration we get the Dialog where we can create new SpecTypes and Datatypes. For the first time, we create a new SpecObjectType by right-clicking on "SpecTypes". One of the entries in the child menu is "SpecObject Type".

Once created, we select it and rename to "Headline Type" it in the properties.

Then we give it a new Attribute called "Description".

NOTE: It is important that we call it description. This matches the Attribute from "Requirement Type". By using the same name, we ensure that the Attributes appear in the same column, even though they are different Attributes.

We do not set the type yet, as we need to create a new one. We do this by right-clicking on "Datatypes". There we create a new "Datatype Definition String" and call it "T_Headline". Now we can go back to the Description Attribute and set the type to T_Headline.

When all this is done, the configuration should look like this:

Pror datatype headline1.jpg

Currently, there is no way to change a SpecObject's type when it is selected in the Specification. We have to find the SpecObject in the Outline View (in the SpecObjects Folder). Once selected there, we can change the SpecObjectType in the Properties view.

Also note that currently all existing values are lost when changing the type.

After the changes, the GUI should look as follows (note that the SpecObject is selected in the Outline, not in the Specification):

Pror gui with headline.jpg

Note the following:

  • The columns "ID" and "Owner" are now empty and cannot be edited for the Headline
  • Note how the Property View changes, as you select SpecObjects of different types
  • Right-clicking on a row now shows one more option for child/sibling creation: A new entry of type "Headline Type"

Last, we will use the Headline Presentation for the type T_Headline. This is done via the Presentation Configuration, and should result in the following. In addition, you can change the font size of the headline in the "Size" Attribute:

Pror datatype headline2.jpg

Other SpecTypes

You may have noticed in the Datatype Configuration Dialog, that right-clicking on "SpecTypes" offered more options, besides "Spec Object Type". A number of ReqIF-Elements can have Attributes.

We will now create a "Specification Type" and assign it to our Specification.

Try to create a "Specification Type" and configure it as shown in the screenshot:

Pror new spectype.jpg

Next, we will assign this type to the one Specification that we have. To do this we select the Specification in the Outline View. That will show the Specification's Properties in the Properties View. The "Type" Property is empty. We select "Specification Type" from the drop down. As soon as it is selected, the Attribute "Description" will appear in the properties view.

Tutorial 4: Links between SpecObjects (SpecRelations)

The implementation of SpecRelations is not complete yet. Still here are a few pointers to show what is planned.

Creating SpecRelations

SpecRelations are created by "Link-Dragging". This is platform specific:

  • Linux: Dragging with Ctrl-Shift
  • Mac: ???
  • Windows: ???

Showing links as children can be switched on or off with the little triangle icon in the toolbar:

Pror toggle links.jpg

After creating a link:

  • The "Link" column shows incoming and outgoing links
  • The SpecRelations are shown as children in the Specification view

NOTE: We plan on implementing a filter, so that showing links as children can be switched on or off. SpecRelationTypes

SpecRelations can have their own Types. Once a type is set, the corresponding columns in the Specification are rendered using Presentations, etc. However. the Type has to be set explicitly (a link created with dragging has currently no Type).

Here is a Screenshot of a Specification with some Links and a SpecRelationType that includes a "Description" Attribute:

Pror gui with links.jpg

Note the following:

  • The right column shows incoming and outgoing links
  • The number to the left of the triangle is incoming links, the other outgoing links
  • The outgoing link from REQ-2 is shown
  • The outgoing link from REQ-8 is hidden
  • The link from REQ-2 has a description, and it shows the destination name in the "Link" column

Outline View

Note that the Outline shows a folder with all SpecRelations.