Document View for Requirements

What is a Document View?

Document View is a special type of view of issues. In Document View you can overview your issues as if they were the paragraphs of a single document: a numbered paragraph is created for each issue (paragraph numbers mirror the hierarchy of the items). You can both read or edit these paragraphs.

Document View is available only on Requirement and Test Case trackers. When you navigate to a tracker where this type of view is supported you will find the document view icon on the breadcrumb.

Clicking this open will open the view for you. On the trackers that support it the document view is the default view. To return to table view you can use the first icon on the figure.

Please note that there is more than just the default document view, which shows you all issues in the tracker. You can easily create a custom view of this type, for which you can specify a detailed filter to decide which issues to include in the document. To do this, click "New View" in the menu of the corresponding tracker (the menu can be accessed by clicking on the menu icon which is the last icon on the above picture).

Here you can specify the filter conditions, the name of the view etc. Make sure to select "Document" from the "Layout" selector.

After the view was created it will show up in the view list of the tracker:

Document View will help you in many ways. Most importantly it will make the navigation and the reorganization of the issues much easier.

Navigating in Document Views

The layout of a Document View looks like the following:

There are three panes: the left-side one containing the requirement tree, the middle one containing the generated document itself and the right pane containing the test plan (if there's a test case tracker configured), releases and properties tab. All issues in the tracker (or the ones that match the filter conditions of the view) appear in the requirement tree and in the document also. In the requirement tree they are shown in a parent-child hierarchy, with the root node containing the name of the tracker. The navigation is easy: when you click a node in the tree the document will automatically "scroll" to the corresponding paragraph and the properties tab on the right side will show its properties.

The splits between the three panes can be resized by moving the gray bar between them. Or, if not needed, the requirement tree and the right side panel can be hidden by clicking the white triangle icon on the top of them.

Organizing the issues

Beside simply navigating between the issues you can also re-organize them in document view.

You can easily move elements in the requirement tree. Just grab a node and move it. You can easily change the order of the issues under the same parent or you can move an issue under an other parent. You can move multiple issues at the same time. The requirement tree will suggest you (using meaningful icons) whether a move is possible:

The requirement tree will also allow you to add new issues, to delete existing ones and to use the copy-paste functionality of codeBeamer. You can access these options in the context menu (see the section about context menus) of the tree. Just right-click on a node and the menu will pop up:

You can also add folders for better organizing your issues. To do this just right click on a folder or the root node and select the New Folder item from the context menu.

Note, that you can copy and paste items in the same tracker and between different trackers, too. If the source and the target trackers have different fields you have to map them to each other manually:

That is, you can tell codeBeamer where to store the field values for which there's no matching field in the target tracker. You have to do this only once even when pasting multiple issues.

The same context menu is available on the middle pane of the view: just click on the arrow icon after each section's name.

One other way of adding new issues: click the plus icon in the header of the tree:

This will add a new node to the requirement tree which you can rename and the new issue is created. The new node will be added as the last child of the currently selected item.

Link requirements with test cases

On requirement document view you can easily link requirements with the test cases that verify them. The first tab of the right side panel contains a tree of test cases. These test cases come from those trackers in which the Verifies field points to this requirement tracker.

If you want to remove the reference between a requirement and a test case just right click the test case in the requirement tree and select the Remove menu item.

To link a test case with a requirement just drag the test case from the right side panel to the target requirement in the left tree and drop it. This will set the Verifies field of the test case to the target requirement and will create an association of type Depends between the two items. This means that when the requirement changes the suspected flag is triggered on the association and you'll see an indication on the test case issue.

Generating test cases

You can also generate a test case for a requirement. To do this just right click the requirement in the left side tree and select Generate Test Case. This will generate a new item in the default test case tracker with the Verifies field set to the requirement (and a association is created also in this case).

You can generate test cases even for a whole subtree. In this case the generated structure will be the same as the structure of the requirements. If you start geenrating on a requirement that has children codebeamer will ask if you'd like to generate recursively (for all children).

You can easily check which requirements has test cases. To see this information click on the gear icon above the requirement tree, check the Show test cases option and click save:

After that the tree will be refreshed and the test cases for each requirement will be shown. If a requirement has no test cases then it will be marked with an exclamation mark icon in the tree:

Working with releases

The right panel of the requirement document view has a Releases tab. Here you can do several things:

• create new releases: Just right click a node in the release tree and click the New Sprint menu item.
• set the target version of an issue: To do this just drop a requirement from the requirement tree to the release tree. This will set the target version to the selected one. The requirements associated with a given version are also shown in the release tree. If you want to change the target version of a requirement you can just move it directly inside the release tree from one release to an other.
• remove an issue from a release: right click on an issue in the release tree and click Remove from release in the context menu
• check the coverage of a release: right click a release in the tree and click the Show in coverage browser menu item

Working with issues

Document view is the right place for working with issues because you won't lose context: you don't have to leave the page when you edit an issue or add a comment.

Editing issues

Editing an issue in document view is extremely easy. Just double-click an issue summary to modify it, and it becomes editable.

Double-clicking an issue's description will show the inline editor, too:

By default, the WYSIWYG editor is selected, but this can be changed on user and system level. You can easily attach files to the issue using the "Attach files..." link in the top right corner of the editor box. You can click on the link or just drop a file over it from your local file system.

When in WYSIWYG mode, the attached images are automatically pasted to the location where the cursor is currently positioned. Of course you can attach any type of files, not just images.

The wiki help can be accessed by clicking on the question mark icon in the top right corner of the editor box.

Creating related issue from selection

Sometimes you may want to create an issue from a part of a requirement description. For instance, you may work on a set of requirements and want to create tests directly from the description of a certain requirement.

This can be easily done with codeBeamer's WYSIWYG editor. Just select a part of the description text, then choose a tracker from the "Add Issue..." dropdown on the editor toolbar:

A similar editor will show up where you can edit the details of the new issue. If everything is fine, just click the "Create issue" button.

The related issue is created in the selected tracker and the editor replaces the originally selected part of the description with the interwiki link of the newly created issue.

Adding comments

Adding comments to issues in document view is simple. Just click on the Add comment link on the properties panel. If there are already comments you can find them in the comment box under the link.

Issue details

You can easily check the details of an issue (submitter, date etc.). Just select an issue in the left tree or click into a paragraph in the document then select the Properties tab on the right panel:

Here you can see the associations and the children of an issue, too. By clicking on the summary of the issue you will get to the issue page. If workflow transitions are enabled on the tracker the Transition drop down is available.

You can even edit some basic properties of the issue without leaving the page. Change the properties then click Save.

Associations

There are multiple ways to add associations to issues in document view. If you want to associate two issues in the same tracker just drop an issue from the tree over an issue on the right side:

This will create an association from the dragged issue to the target. Using the above example: from "Battery" to "Project Goal". The type of the association is "related".

An other way of creating associations is clicking the "Add Association" item in the context menu of a tree node or an issue on the right side. This will show you an overlay window where you can select an issue from the history or from a search.

Suspected links

On the traceability matrix (see the traceability matrix documentation) you can define dependencies between tracker items. If you check the "Trigger suspected links" that means, that when issue A changes in the dependency A <- B, then B is marked as suspected.

You can also check this box when creating an association from the issue details page:

This information is displayed in document view in two forms.

First, when you open the properties (see issue details) of either A or B, you will see a red tablet and a small icon indicating the type of the association:

Here you can also the suspected links: when you made sure that the change in the issue that this one depends one doesn't affect the depending issue or you made the updates needed just click on the small "x" on the tablet. This will clear the suspected link (of course it can become suspected again when A changes next time).

The other place where you can check if there are suspected links is the tree. The issues with suspected links gets a small S icon:

For this to be shown, you may have to modifiy your tree settings (see tree settings).

Context menus

Regular context menu

The complete list of menu items look like this:

The items in details:

• Collapse Node, Expand Node: available only in the tree. Collapses or expands (respectively) the given node. It works recursively, that is, collapses/expands all descendant nodes of the selected one.
• New Child: creates a new node under the selected one. If applied on the root node (the node for the tracker) the newly created issue will have no parent. Otherwise the parent will be the issue represented by the selected node. Note, that after clicking the menu item a new node will appear with some default name (for example "New requirement"). If you don't change this default name then the new issue will not be created.
• Insert a New Item Before/After This: the same as the previous one except that creates the new issue on the same level as the selected node. The new issue will precede or succeed the selected one.
• Generate Test Case: available only in the document view of requirement trackers. Generates a test case for the requirement in the default test case tracker of the project.
• Delete: deletes the selected node. Pops up a confirmation dialog. The issue is only deleted if you confirm that you want to remove it permanently.
• Add Association: pops up the overlay window shown in the section about associations where you can associate an other issue to the selected node
• Copy: copies the selected node and its children (recursively, that is, the whole structure under the selected node) to the codeBeamer clipboard. This menu item is also available in readonly mode (when a baseline is selected). In that case it is the structure that existed in that version is that gets copied. The clipoard's content can be pasted anywhere (in an other document view, in table view etc.) where pasting is allowed.
• Paste as New Child/Above This/Below This: pastes the contents of the codeBeamer clipboard. These menu items are not available in read-only mode.
• Export selection to word: select a few nodes in the tree, right click and select this menu point. It will export all the selected issues to word for you.

The context menu of folders and the root node has an item New Folder. This will create a new folder as the child of the item right clicked.

Transition menu

If the workflow is enabled on the tracker you can open the transitions menu by clicking on the small icon in front of the issue summary:

Using this menu you can set the status of the issue easily. In most of the cases when you'll use this menu the new status will be set immediately, without you filling a form and page reload. However, if there's a mandatory field in the target status that is empty in the issue you'll get a popup where you can set all the mandatory fields.

Filtering

On the top of the middle panel you'll find a filter.

Using this filter you can easily reduce the number of issues shown in the middle panel. You can ilter the issues based on several things:

• the last modification date of the issue
• if the issue has suspected links or test cases with suspected links
• the average rating of the issue

Tree settings

You can configure a few things about the tree. The settings dialog shows up if you click the gear icon in the header of the tree:

There are two important things to note about these settings:

• they are stored on user level. That is, your settings don't affect any other user's trees
• the same settings apply to all trees in all document views. If you change an option on one document view's settings it will affect the tree any other document view's tree

The settings dialog contain three options:

Their meanings:

• Show IDs: if checked then the node names in the tree will contain the issue ids. For example: "[7509] - Project Goal"
• Show numbering: if checked then the node names will be prefixed with the paragraph number of the issue (the same number as on the right side, before the summary of each issue). For example: "1.1 - Project Goal"
• Mark issues with suspected links: if checked then the issues that have suspected links will be marked with a red dot (as shown in the section about suspected links).
• Show test cases: (available only in the document view of requirement tracker) if checked then the test cases verifying the requirements will be also shown in the tree. Requirements that have no test cases will be marked with a black exclamation point.
• Maximum number of issues shown in Document View: you can limit the number of issues shown in document view. The default is 300.

Rating

Using the rating feature you can easily express your opinion about a requirements on a scale from 1 to 5. To be able to use this tool on document view just click on the gear icon above the tree and check the Add Review / Rating option:

After the document view is reloaded you'll see a rating icon in fron of the issue summaries. These small icons show the rounded average rating of the issues.

To add a new rating or rewiev to an issue just click on this icon and click on a star in the popup. After writing an optional comment click on Rate. The rating icon is updated immediately to reflect the new average.

You can also filter the issues by their average rating. The filter is in the top-right corner of the middle panel.

Baselines

For more information on baselining, please consult this wikipage.

Creating baselines in document view

Creating a baseline in document view is simple: just click the "New baseline" menu item from the "more" menu on the breadcrumb and give a name and a description (optional) to the baseline in the popup window.

Viewing baselines

There is a hashmark icon in the header of the tree for baselines:

If you click on this icon an overlay window will pop up with all the available baselines:

Clicking the name of a baseline will load the document view tracker containing the structure in the selected revision.

When a baseline is selected the background color of the right side turns into yellowish. This makes it easy to recognize that you are browsing a baseline. The tree's context menu is also missing some items (see this section).

Comparing baselines

If you have at least two baselines of a tracker view, you can show the differences between these two baselined revisions, by selecting the two baselines in the baselines overlay window and clicking on Compare Selected Baselines:



The result window will show the differences:




Please note:
Currently (CB-6.0.3) you can only invoke the baseline diff for a tracker via the baselines overlay window of the tracker document view.
It works for both project and tracker scope baselines, but it will not work via Compare Selected Baselines on the Project Baselines page.

Limitations

Although Document View is a very easy to use tool in some cases you have to visit the original tracker or issue details pages to achieve a goal. These cases:

• if there is a required field in the tracker and that field doesn't have a default value then you cannot create new issues or modify existing ones in document view
• in the property editor of each issue there is a fixed list of fields shown. If you want to change a field that is missing from there you have to visit the issue details page (by clicking on the More details link
• only the first 300 issues are shown in document view. To see the missing issues you can create a custom document view with an appropriate filter.
  Displaying very large number of items in the Document View can cause slow performance, so choose the displayed number of items carefully.
  
• the "pages" of document view are loaded with infinite scrolling.

Requirements Library

Watch a video on the requirements library here.

When building a product you may want to reuse the same requirements in multiple versions. A requirement library is a collection of requirement trackers that helps you in this task. When the original issue changes you can rely on the suspected link feature and the diff tool to decide if you have to apply the changes to the copied requirement.

You can access the requirement library on the right side panel on the document view of requirement trackers.

Initially the requirements library lists all non-empty requirement trackers from all projects that you can access. You can customize the list of trackers by clicking on the little gear icon above the tree.

Configuring the requirements library

After clicking on the gear icon you'll see this popup:

Here you can select the trackers that you want to see in the requirement library. Since this is a user level setting, you will see the same list of requirement trackers in every document view.

Note that codeBeamer stores the list of the selected trackers. When you add a new requirement tracker to your project you have to reconfigure the library if you want to display that too.

Reusing requirements fom the library

To reuse a requirement from the library just drag the node in the library tree and drop it to the tree on the left side or to a requirement in the middle panel. This will create a new copy in your tracker. The parent of the new requirement will be the requirement that you dropped on.

Codebeamer will also create an association of type copy between the original requirement and the copy. The trigger suspected flag is set to true on this association. This means that whenever the original issue changes the suspected link is triggered on the association.

Note that not only the issue properties are copied but also the comments and associations.

The copied nodes are marked with a little c icon in the left tree.

Note that if there are custom fields in the original issue they will be mapped automatically if possible. If not, then you'll get a list with the mapping problems and you can decide if you still want to copy the requirement.

Reviewing suspected links

As noted above, when the original issue changes you're "notified" through suspected links.

You can see what changed if you click on the suspected link badge. This will bring up an overlay with the differences.

On this dialog you can see all the common fields of the original and the copy issue (so the unmappable custom fields are not listed). The values from the copy are on the left side and the values from the original are on the right.

If there' a differencein any of the fields (no matter if it was changed in the original or in the copy):

• it is highlighted on the right side
• there's an Apply button in the middle column

If you're sure that you want to take a change from the library issue click on Apply in the row. You can apply all changes by clicking the Apply button in the table header.

After selecting the changes to apply click on the Save button to update the copy. This will also clear the suspected link flag.

Note, that the suspected link is treggered even when some adds a comment to the original issue, but comments cannot be moved to the copy issue. In this case the diff dialog is empty and the Save button will only clear the suspected link.