ReqHeap

Manual 1.0

Version Project URL Project WIKI Author Manual Author Program

1.0 http://www.sourceforge.net/projects/reqheap Urs Krebs, Matthias Gnter, Serjoscha Gartmeier

Content
Installation............................................................................................................................3 Prerequisites ....................................................................................................................3 Automatic Install ...............................................................................................................3 Manual Installation ...........................................................................................................3 Update from version 0.8 up to 1.0 ....................................................................................4 Checking the installation ..................................................................................................4 Backup .............................................................................................................................4 First Steps............................................................................................................................5 Guest view .......................................................................................................................5 View a project...................................................................................................................5 View a requirement ..........................................................................................................5 Setting up a project/projects ................................................................................................6 Setting up a project ..........................................................................................................6 Using a template to create a project.................................................................................7 Setting up users ...............................................................................................................7 Releases ..........................................................................................................................9 Components.....................................................................................................................9 Stakeholders ....................................................................................................................9 Glossary .........................................................................................................................10 Users and Roles ................................................................................................................11 Administrator ..................................................................................................................11 Project Leader ................................................................................................................11 Supervisor IT..................................................................................................................11 Supervisor User .............................................................................................................11 Requirements ....................................................................................................................11 Filter view .......................................................................................................................12 Tree view........................................................................................................................13 Detail view explained......................................................................................................15 Rich Text Editor..............................................................................................................16 Form Functions ..............................................................................................................17 Parent requirements.......................................................................................................18 Workflow/Life Cylce of requirements ..............................................................................18 Associating requirements to Releases ...........................................................................18 Email Notification ...............................................................................................................19 Import.................................................................................................................................19 Keywords ...........................................................................................................................19 Test Cases.........................................................................................................................20 Exporting Data ...................................................................................................................20 PDF ................................................................................................................................20 Offer list..........................................................................................................................21 XML................................................................................................................................21 Export UTF-8 encoded CVS File....................................................................................22 The Administration page ....................................................................................................22 Configuration..................................................................................................................22 Languages .....................................................................................................................22 Define a completely new language .............................................................................22 Drop Down Texts ...........................................................................................................23 User Defined Fields in Requirements.............................................................................24 Templates ......................................................................................................................25 2

Installation
Prerequisites
Linux / Windows MySQL Version >= 4 PHP Version >= 5 for dompdf-0.5.1 creating PDFs and PHPExcel for Excel generation PHP libraries for dompdf-0.5.1: php-xml php-xmlrpc Apache HTTP Webserver

Automatic Install
1. Copy all the files from the zip. 2. Set the rights of admin, FCKeditor, img, install and ini folder to 777 (Windows: ownership to Anyone) 3. Install using the file install.php in the ReqHeap install folder. 4. Login to the main site and Admin page using username:admin password:adminreqheap

Manual Installation
1. Copy all the files from the archive. If missing, create the following folders in folder where you unpacked ReqHeap and give them read and write permissions:

img (image folder/FCKEditor should save into) img/File (image folder/FCKEditor should save files into) img/Flash (image folder/FCKEditor should save flash into) img/Image (image folder/FCKEditor should save images into) ini (configuration files) ini/bkp (for backuping the configuration files) ini/lng (language files) ini/lng/bkp (for backuping of the language files) ini/txts (dropdown files) ini/txts/bkp (for backuping of the dropdown files) RSS (for creation of RSS feeds

2. Create a DB with the name reqheap and utf8_general_ci as collation. 3

3. Import the 'reqheap.sql' file into the reqheap DB. 4. Set the connection to the DB in the file 'admin/inc/conn.php': $db="<db_name>"; $link=mysql_connect("localhost","<db_user>","<password>"); For the <> a value is needed. E.g.: $db="reqheap"; 5. Set the parameters in /ini/params.php 6. Set the correct permissions : 7. Set the rights of admin, FCKeditor, img, install and ini folder to 777 (Windows: ownership to Anyone) 8. Login to the main site and Admin page using username:admin password:adminreqheap

Update from version 0.8 up to 1.0

Run the file install/ install_modifyDBfrom0.8to1.0.php within the browser. This will update the database structure of the version 0.8 to version 1.0.

Checking the installation

In the /install folder there exists a diagnostics.php file.

Backup
database the following folders: img/ & ini/

First Steps
Guest view
It is possible to log on as a guest. Just use guest as username and password. The guest permissions allow viewing the requirements of public projects only.

View a project
The standard view is the 'Home' view. You see the requirements which are assigned to you, which requirements are not yet accepted and what is modified recently. If you want the same information for a specific project, it is possible to select it from the drop-down menu in the top-left corner.

View a requirement
To view a requirement, click in the 'Home' view on the number in front of the requirement title. In this view you see all the details the requirement contains. Depending on the permissions you have, you can edit the requirement, have a look on the history of it, export it as a PDF document or write a comment. The meaning of the fields is described below.

Setting up a project/projects
To set up a project it is required to be an administrator with the corresponding permissions!

Setting up a project
Click on Projects.

Click on 'Create new project'.

Now the following fields can be filled: Name Load Template Description Choose a template. This transfers all the properties from the template to the current project. Don't forget to change the name of the project if you want to create a new project. Name of the project. Shows the state of the project. The values are: development, released, validation evolution or finished. Status Represents the status of the project. Description Public The requirements of the project can be viewed without login. But no changes can be made. Private The requirements of the project are only accessible if you are assigned to the project with a role. Depending on the permissions contributions to the project are possible. Retired Retired projects are marked red on all pages. It is not 6

Project name Phase Status

possible to update requirements of retired projects but to clone selected requirements to other projects. Project leader Description Template? Choose the project leader. The description of the project which can be edited with a rich text editor. Check this box if you want to save all settings as a template. You can use it afterwards for the creation of a new project with exactly the same settings.

Using a template to create a project

Choose from the drop-down menu a template. You need to save an earlier project as a template, otherwise this menu is empty. The template includes the assigned users, releases, stakeholders and glossaries.

Setting up users
With the login mask you can register as a consumer. But an administrator has to change your role or assign you to a project. In the following form you have to provide your credentials including a valid email address where the password will be send to afterwards.

The administrator has a similar form but is able to assign roles and projects to each user. The roles and their permissions are described later.

Add the new user to a project.

Releases
A project can have several releases. It indicates a certain level of progress. The release has a label which is commonly a version number in association with software. The other important parameters of a release are the 'Projected date', where the project should be released and the effective 'Released date'. The release date can be empty. In the table are all releases of the projects visible but only the project names where you are assigned to. It can also be the case that different projects are in the same release.

To assign releases to a project change to the Projects-view where you can add the releases to the project.

Components
The components are used as elements for a structured project where we can define different sections and assign the requirements to the components. They may be created or modified via the administration page which is explained here.

Stakeholders
A stakeholder is a party who affects, or can be affected by the project. Each project can have several stakeholders and each stakeholder can participate on multiple projects. You need administrator permissions to create a stakeholder.

For a new stakeholder click on Add new stakeholder, fill out the form and confirm with Add stakeholder. 9

Change to the Projects-view where you can add the stakeholders to the projects.

The stakeholders may be selected per requirement within the requirement itself. You can choose between the stakeholders which are assigned to the project the requirement belongs to.

Glossary
A glossary contains a unique Identification number which is not editable, a term, an abbreviation and a description. Each project may have several glossaries which are needed for the explanation of specific and project related terms or abbreviations. You need administration permissions to create a glossary.

For a new glossary, fill out the form and confirm with Add glossary. It is possible to modify the glossary at every time you want.

10

Change to the Projects-view where you can add the glossaries to the projects.

Users and Roles

Users can be defined by the administrators or be self-sign in. Roles and association to projects are limited to administrators and project leaders.

Administrator
With the administrator role you are able to create projects, subprojects, glossaries, stakeholders, users and releases. With this comes the possibility to associate these to the projects. You have access to every project and everything that belongs to them.

Project Leader
As a project leader it is possible to access the assigned projects and everything that belongs to them. The permissions allow creating releases and test cases but the modification of a requirement state is restricted. Only the values created, specified, validated, analysed and released are permitted.

Supervisor IT
As a Supervisor IT it is possible to access the assigned projects and everything that belongs to them. The permissions allow creating releases and test cases. It is possible to change the state of a requirement without restrictions.

Supervisor User
The same permissions as the Supervisor IT but different department.

Requirements
The first decision before you create a requirement is to select what type of requirement you are intended to create.

After clicking on Add Requirement a form with many attributes appears. This is the form of a normal requirement. Other possibilities are stub and heading. A stub contains only very few information. A title, a project and/or test cases but no detailed description. All this information will be provided later on and will change the stub to a normal requirement. A heading is not really a requirement. It contains a project, a description and so forth but there is no need to add additional information as it is the case for a stub. 11

E.g.: 1. Technical Requirements This section is dedicated to technical requirements 1.1. Basic infrastructure 1.1.1 The system must work on Wind 3.1 to Vista 1.1.2 The system must work on Mac Only 1.1.1 and 1.1.2 are real requirements. 1. and 1.1 are headings. They are not stubs, as there is no need to add information later on.

Filter view
Click on View all. This view has every user, it doesnt matter what kind of permissions the user owns.

What you get is a view with every requirement contained in the selected project. The main purpose is to filter the requirements and only requirements with selected attributes are displayed.

The filter attributes are:

Attribute Author

Description Filter by an author of a requirement. Every registered user is in this drop-down menu available. Filter requirements by state. Possible values are: created, specified, validated, analysed, accepted, tested, released, rejected. Filter by Priority degree. Filter by user who is assigned to requirements. Every registered user is in 12

State

Priority Assigned to

this drop-down menu available. Release Component Stub/heading Filter by releases. Filter by component. A stub requirement contains only a few attributes. The most important is the title. You need to add the missing information later. Shows every requirement which has open questions. Full text search within the title of the requirement. Filter by Keywords which are assigned to a requirement. You can choose between an OR and an AND relation. This is because it is possible to assign multiple keywords to a requirement. You can restrict the search or you can display every requirement who has assigned at least one of the selected keywords. Filter requirements by empty fields. Could be useful to determine which requirement has a field which isnt filled. Filter by the author of comments. Shows the requirements with the given requirement identification number. It is possible to declare a range of ids or an exact id. The Requirements can be selected by Test cases. When the result only shall have Requirements who do have a single Test case this filter should be used.

Open questions Text Keywords

Empty Fields

Comments author Req ID

Test cases

Tree view
From the Filter view you have two different representations. The first and referred to above, is the Normal view. With the button Tree view you are able to see the hierarchy as a tree.

13

On the left side, it is possible to change the hierarchy of the requirements via drag and drop. Simply move them around by clicking on the icon of the requirement. But it is not possible to change the positions on the same hierarchical level. For this purpose is right hand side. When clicking on change positions you will see every requirement which is on the same level as the clicked requirement. On the right side you can move the positions of the requirements. As soon as you think the positions are as you like, hit the change position button again and the changes will be applied. With the buttons Undo and Redo changes may be reverted or rebuilt. The search with the filter view work the same way as with the normal view. The only difference contains the representation of the search result. The matches of a search will be displayed with the red font of a requirement. Not the whole tree is displayed but every branch which contains a match down to the level of the lowest match.

14

Detail view explained

Field Title Project Stakeholders State Priority Component Weight

Description Title of the requirement. The name of the project the requirement belongs to. The stakeholders of the project. There may be several. Represents the state of the requirement. Possible values are: created, specified, validated, analysed, accepted, tested, released, rejected. The priority of the requirement. The component the requirement belongs to. This is a structural element and can be created individually. This number defines the weight of a requirement. It is used in calculations in the exported excel sheet. Only numbers which are > 0 are allowed. Indicates how satisfied it would be if the feature is going to be realised. Indicates how dissatisfied it would be if the feature is not going to be realised. The author of the requirement. The description of the requirement. The date the requirement has been created. The date the requirement was modified the last time. The date the requirement has been accepted. The subproject in which the current requirement should be realised. Is a Term with an abbreviation and a description which can be added to projects. There can be multiple terms for a project. Choose between a functional and a non-functional requirement. The user to whom the requirement is assigned to. Reference to where the requirement comes from. Things those are not clear until now. Location of the requirement or another ressource. Indicates in which releases the requirement exists. 15

Satisfaction Dissatisfaction Author Description Creation date Last Change Accepted Date Subproject Glossary Requirement type Assign to Source Open points URL Releases

Req ID Risk level Depends on Parent Internal Version Complexity Conflicts Tree position Accepted User Testing level Keywords

The unique Identification Number. One per requirement. Indicates the risk level of the requirement. Possible values are: low, medium, high. Choose a requirement on which the current requirement is depending on. Choose a parent requirement. This is the revision number and cannot be modified. How complex it would be to realise the requirement. Possible values are: low, medium, high. Choose a requirement where conflicts occur. The position as a number in a hierarchical tree view. Shows which user accepted the requirement. Several levels of testing exist which, should be defined. This is an instrument to categorize a requirement with words who describe the section, function or other things related to the requirement. This makes it easier to find it later on. The list represents all added test cases.

Test cases

Rich Text Editor

Toolbar Element Function View or edit the document source code (for advanced users). See Source Editor. Removes all contentes, creating a new blank page. Saves the page you were editing. Preview what the HTML page will look like for users. Select a layout template. See Templates Cut the highlighted text to the clipboard. See Cut, Copy and Paste. Copy the highlighted text to the clipboard. See Cut, Copy and Paste. Paste the data copied to the clipboard (with or without formatting). See Cut, Copy and Paste. Paste content copied from Microsoft Word or similar applications. See Cut, Copy and Paste. Print the current document. See Printing. Spell check the text in the document. See Spell Checking. Undo or redo the most recent action taken. See Undo and Redo. Find a word or phrase within the document. See Find and Replace. Find and replace a word or phrase within the document. See Find and Replace. 16

Select the entire text in the document. Remove the formatting from the highlighted text. Applies bold, italic, underscore or strikethrough formatting to the highlighted text.See Text Formatting. Superscript or subscript the highlighted text.See Superscript and subscript in Text Formatting. Creates numbered or bulleted lists. See Creating Lists. Increase or decrease the text indentation. Format a block of text to identify quotations (text provenient from other sources). Sets the text alignment (left, centered, right or justified). See Text layout and format in Text Formatting. Converts or removes the text in hyperlinks. It may also by used to manage file uploads and links to files on the web server. See Links, EMails and Anchors. Inserts or modifies a link anchor. See Links, E-Mails and Anchors Inserts images into the document. See Inserting Images. Inserts a Adobe Flash element into the page. Creates a table with the defined number of columns and rows. See Tables. Inserts a divider line (horizontal rule). Inserts an emoticons image (smiley faces, email icon, lightbulb, etc.). Inserts symbols & special characters (accented characters, trademark, currency symbol, etc.). Inserts a printing page break. Only impacts printed version. Styles & formatting determine the appearance and semantic value of your document. You may use the drop down boxes to apply styles, set the font, its size, etc. To remove the applied style select the style name again. See Text Formatting. Changes the color of the text. See Size and color in Text Formatting. Changes the background color of the text. See Size and color in Text Formatting. Maximizes the editor size inside the browser. Shows where the block elements boundaries in the text. Shows information about the FCKeditor.

Form Functions
Toolbar Element Function Creates a new form block into the page. 17

Inserts a checkbox to the page. Inserts a radio button to the page. Inserts a text field into the page. Inserts a multi-line text area into the page. Inserts a selection field into the page. Inserts a form button into the page. Inserts an image into the page, which behaves much like form button used to submit forms. Do not use it to insert plain images into the document. Inserts a hidden field into the page.

Parent requirements
This is a hierarchical relationship of requirements. A parent may have several child requirements but a child requirement can have only one parent requirement. This could be a structural instrument for a better development and understanding the requirement. The parent requirement may only be released if the child requirements are ready to release.

Workflow/Life Cylce of requirements

A possible Life Cycle could be: 1. The requirement is created. 2. The requirement is accepted by one or several authorized persons (Supervisor IT, Supervisor User). 3. Now, there are several possibilities: The requirement could be cancelled or implemented 4. If the requirement is implemented it should be tested 5. The requirement may be released 6. It may reach an end of the life cycle

Associating requirements to Releases

Right now it is possible to add releases to projects but not the requirements itself. This will be possible in version 1.0.

18

Email Notification
The only email notifications are going to the administrator when a new user has registered and to the user itself with its credentials. Feature requests would be needed if email notification shall be a part of the process support.

Import
The import function is able to import CSV files that correspond to a defined Structure. This may be very comfortable if requirements already exist in documents like spreadsheet files.

The CSV file may contain maximum 3 Keywords per requirement and has one row as a header at the top of the file. The values are separated by a semicolon. Before the import, the project(s) contained in the CSV files, have to be created. The author needs the Name from ReqHeap otherwise the user gets created with some default values which can be modified manually afterwards. This is also the case for the requirements where the details have to be set manually afterwards. Attention!!!! The imported file must be UTF-8 encoded!

Keywords
Keywords may be used to classify a requirement. It is possible to add several keywords to a requirement. A keyword has no other attribute than its name but it has a simple reason why this is very useful. You can search after these keywords (in the View all view) and see every requirement from a desired section. Choose if you want to see every requirement that contains at least one of the selected keywords or restrict the search to those who contains every selected keyword.

19

Test Cases
Test cases are an instrument to test a requirement with a given scheme. A requirement can have several test cases and a test case can have several requirements. The users guest and consumer have restricted permissions and can only view and export the test cases. Test cases can be created, edited, deleted and added to a requirement by all the rest of the user roles. Exporting the test cases as a PDF is permitted for every user. The attributes of a test case are: Field ID Name Description Desired result Description Unique Identification number Name of the test case Description of the test case. Rich text, so it is possible to add pictures. Description of the desired result of the test case. Rich text, so it is possible to add pictures. The values active or inactive are available.

Status

In addition there are reference fields to the projects and releases where the test case is assigned to. To create a test case click on Test cases.

In the following window choose Add new test case at the bottom of the existing test cases. Fill in the form and dont forget to assign the corresponding projects and releases! Confirm with the save button to create the test case.

Exporting Data
It is important to have the opportunity to export data for a better development and documentation cycle. The export is possible from different sites within ReqHeap.

PDF
Change to the View All-view.

Click on the PDF landscape- or PDF portrait-Button and the selected requirements within the filtered view will be exported with the corresponding format as a PDF document.

20

The PDF can also be generated within the Projects page.

Offer list
The idea was to create a list where the offers of different suppliers could be analyzed and rated. This export is available for the two file formats .xls and .csv.

The requirements which are selected within the filtered view will be exported. The Excel and CSV can also be generated within the Projects page. Before you generate a PDF or Excel file, you can select which of the fields should be exported. Check/Uncheck the fields and generate the file by clicking on Create xls or Create pdf. The selected fields may be saved as a template with the corresponding button. When saved, it is possible to load the selection in the future. The templates are stored per user. When loading a template, it is also possible to delete it with the Delete button.

XML
The project data may be exported as an xml file. Change to the Projects-view.

Click on the Export in xml button behind the project you want to export and store it where you want.

21

The exported xml file contains only information about the project but not the requirements it contains. The exported fields are: Name Description of the project Phase Status Project leader Creation date Releases Assigned users

Export UTF-8 encoded CVS File

There is an ability to export Requirements already in a already UTF-8 encoded CSV File.

Therefore you have to select the project which does include the requirements you like to export and import later. Make sure you go on the Requirement View also called View all section. Then press the Export CVS (allows import) button. Select the Requirements you want to export. Now you can select what you want to export.

The Administration page

Configuration
The configuration is built up with files to provide an easy to extend solution.

Languages
You can check for missing translation elements (after a new version was installed). Define a completely new language

Create the file in the directory Copy the EN version into it Translate it It would be appreciated if you could send a copy to the tracker on sourceforge for inclusion in the next version of reqheap. 22

Drop Down Texts

The drop down texts may be modified within a configuration file.

The configuration file is written in PHP. The only two files where HTML is allowed are the _about and news sections. File type state risk component _about complexity news Description Contains the type of the requirement. The states of a requirement and its representation colour. The risk level of a requirement. Custom components can be created where requirements may be added to. The text in here is displayed in the About section of ReqHeap. HTML is allowed. The complexity of a requirement. News which are displayed on the front page of ReqHeap.

23

User Defined Fields in Requirements

It is possible to create additional fields for requirements. The added field will be displayed in every requirement. Enter the name and if wanted the translation of it in another language. The most important part is the type of the field. Choose text to provide a simple text field or dropdown. The values (words, characters or numbers) can be added comma separated in the Values field. Click on the save button on the bottom of the page to generate the field. If the field should be removed, just clear the field with the English name inside and click on save again.

24

Templates
It is possible to create via a template a whole structure for an IT project. At this point, a general IT project is included. When loading the template, the structure is created with a default project name and requirements from the type heading,

In future releases, more templates will follow.

25